Overview - Chert

The Chert Messaging API is a tenant-scoped HTTP API for iMessage. Use it when your product already has a UI and you want Chert to handle lines, delivery, replies, and conversation state.

Chert may route a tenant through different managed delivery infrastructure, but the public API contract stays the same. These docs only cover endpoints Chert supports through the shared API surface.

The model

Object	What it means
Tenant	Your isolated workspace. Authenticated by bearer token or HMAC signature.
Phone number	A Chert-managed sender line assigned to your tenant’s project.
Chat	A 1:1 or group conversation id used with chat-scoped routes such as `/chats/{id}/messages`. Chat-scoped sends use the chat’s current sender line.
Message	One outbound or inbound item in a chat. Message-scoped routes such as `/messages/{id}/react` use the message id, not the chat id.
Event	Durable reply/delivery record delivered by webhook, polling, or SSE.

Route ids

Route family	`{id}` means
`/api/v1/chats/{id}/...`	`chat_id`
`/api/v1/messages/{id}/...`	`message_id`

Common flows

Goal	API path
Send one text message fast	`POST /api/v1/send`
Send a one-time location pin	`POST /api/v1/locations`
Build a conversation UI	`POST /api/v1/chats`, then `POST /api/v1/chats/{id}/messages`
Create a group	`POST /api/v1/chats` with 2-31 recipients in `to`
Look up one message	`GET /api/v1/messages/{id}`
Send a file	`POST /api/v1/attachments`, `PUT upload_url`, then send a `media` part
Send multiple images	Upload attachments, then send them through a chat message with `parallel_attachments: true`
React to a message	`POST /api/v1/messages/{id}/react`
Receive replies in production	`POST /api/v1/webhook-subscriptions`
Develop without a public webhook	`GET /api/v1/events/stream`

Supported today

Capability	Notes
1:1 text sends	Use `/send` for the shortest path or `/chats` for first-class conversation objects.
Follow-up messages	Use `/chats/{id}/messages`; the body must be `{ "message": { "parts": [...] } }`.
Rich link previews	Use a `rich_link` part: `{ "type": "rich_link", "url": "https://..." }`.
One-time location pins	Use `/locations` with `latitude` and `longitude` when enabled on the selected sender line. This is not ongoing Live Location sharing.
Attachments	Upload first, then reference `attachment_id` in a `media` part. Create group chats with text first; send media and rich links through `/chats/{id}/messages` after the group exists.
Multiple-image attachments	Send multiple uploaded images through `/chats/{id}/messages` with `parallel_attachments: true`. It can render as one grouped iMessage on supported Apple devices.
Group chats	Create with 2-31 recipients. Use text for the first group message; participant management requires a pinned group chat.
Tapbacks	Six standard iMessage reactions: `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`.
Typing indicator	Best-effort on existing pinned chats. Treat it as a UI signal, not a delivery guarantee.
Webhooks and events	`message.received` is the recommended real-time inbound event. Legacy `lead_reply` remains available.

Where to go next

Goal	Read
First send	Quickstart
Copy common flows	Usage examples
Auth	Authentication
Conversation API	Create a chat
Group chats	Create a group
Attachments	Attachments
Replies	Receiving replies
Errors	Errors

⌘I