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" }
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
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. |
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
