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
