> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychert.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a chat

> POST /api/v1/chats - create a chat and send the first message.

Creates a 1:1 chat or group chat and sends the first message. Use this when your app wants an addressable `chat.id` for follow-ups, history, typing, media, and group operations.

<Note>
  Text parts use `value`. The request must include `message.parts`.
</Note>

`rich_link` parts use the same public shape on every Chert sender line:

```json theme={null}
{ "type": "rich_link", "url": "https://example.com" }
```

Optional `title`, `summary`, `image_url`, and `icon_url` fields are accepted.
When those fields are omitted, Chert fetches preview metadata when the sender
line supports native rich-link previews.

## Request

```bash theme={null}
curl https://console.trychert.com/api/v1/chats \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15555550100",
    "to": ["+14155551234"],
    "message": {
      "parts": [
        { "type": "text", "value": "Hi Sam - got a minute?" },
        { "type": "rich_link", "url": "https://example.com/demo" }
      ],
      "idempotency_key": "chat-2026-05-01-001"
    }
  }'
```

## Group chat

Use 2-31 recipients in `to`.

```json theme={null}
{
  "from": "+15555550100",
  "to": ["+14155551234", "+14155559876"],
  "message": {
    "subject": "Launch follow-up",
    "parts": [{ "type": "text", "value": "Starting this group here." }]
  }
}
```

<Warning>
  Media attachments and rich links are not supported in the first group-create call. Create the group with text, then send attachments or rich links with `POST /api/v1/chats/{id}/messages`.
</Warning>

## Response

```json theme={null}
{
  "chat": {
    "id": "0f2d3c1a-8b4e-4f6a-90d2-1a3b4c5d6e7f",
    "display_name": "Sam Chen",
    "handles": [{ "service": "imessage", "address": "+14155551234" }],
    "is_group": false,
    "service": "imessage",
    "health_score": 87,
    "created_at": "2026-05-01T12:00:00Z"
  },
  "message": {
    "id": "46eb1003c8b54b7ea8f1c2b03e9a7d12",
    "chat_id": "0f2d3c1a-8b4e-4f6a-90d2-1a3b4c5d6e7f",
    "parts": [{ "type": "text", "value": "Hi Sam - got a minute?" }],
    "status": "sent",
    "direction": "outbound",
    "created_at": "2026-05-01T12:00:00Z",
    "delivered_at": null,
    "read_at": null,
    "service": "imessage"
  }
}
```

## Fields

| Field                     | Required | Notes                                                                                                                            |
| ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `from`                    | Yes      | Sender phone number from [Phone numbers](/api/phone-numbers).                                                                    |
| `to`                      | Yes      | One E.164 recipient for a DM, 2-31 for a group.                                                                                  |
| `message.parts`           | Yes      | Array of `text`, `media`, `rich_link`, or legacy `link` parts. `rich_link` uses `{ "type": "rich_link", "url": "https://..." }`. |
| `message.idempotency_key` | No       | Reuse the same key and body to safely retry.                                                                                     |
| `message.subject`         | No       | Used as the group display name for multi-recipient chat creation.                                                                |

## Ids

| Field        | Use it with                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `chat.id`    | Chat-scoped routes such as `POST /api/v1/chats/{id}/messages` and `GET /api/v1/chats/{id}/messages`.    |
| `message.id` | Message-scoped routes such as `POST /api/v1/messages/{id}/react` and `POST /api/v1/messages/{id}/edit`. |

## Errors

| Code   | When                                                                                                              |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| `1001` | Missing `from`, `to`, or `message.parts`.                                                                         |
| `1003` | Invalid phone number.                                                                                             |
| `1005` | URL in a first-message text part, or a legacy `link` part in a first message. Use `rich_link` for previewed URLs. |
| `2006` | `from` is not assigned to this tenant.                                                                            |
| `4001` | Downstream delivery failed.                                                                                       |

## See also

* [Send a follow-up](/api/chats/send-message)
* [Create a group](/api/group-chats/create)
* [Phone numbers](/api/phone-numbers)