Create a chat

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.

Text parts use value. The request must include message.parts.

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

{ "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. If a rich preview cannot be generated, the URL may be delivered as plain text instead of a preview bubble.

Request

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.

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

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.

Response

{
  "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. Common formatting is normalized before matching the assigned line.
`to`	Yes	One recipient for a DM, 2-31 for a group. Each recipient may be an E.164 phone or Apple ID email handle. Common US phone formatting is normalized; emails are lowercased.
`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 or Apple ID email handle.
`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.

Get started

Messages

Chats

Group chats

Contact sharing

Webhooks and events

Reference

Create a chat

Request

Group chat

Response

Fields

Ids

Errors

See also

​Request

​Group chat

​Response

​Fields

​Ids

​Errors

​See also

Request

Group chat

Response

Fields

Ids

Errors

See also