> ## 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.

# Overview

> Send and receive iMessage from any system over HTTP.

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.

<Note>
  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.
</Note>

## 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](/api/quickstart)               |
| Copy common flows | [Usage examples](/api/usage-examples)       |
| Auth              | [Authentication](/api/authentication)       |
| Conversation API  | [Create a chat](/api/chats/create)          |
| Group chats       | [Create a group](/api/group-chats/create)   |
| Attachments       | [Attachments](/api/attachments)             |
| Replies           | [Receiving replies](/api/receiving-replies) |
| Errors            | [Errors](/api/errors)                       |