Conversations

A conversation is one stable iMessage thread owned by an agent identity. Shared and dedicated inbound conversations are 1:1 and start when a human messages the agent. A dedicated outbound number can also start 1:1 conversations and group chats. Conversations persist as history after a 1:1 connection is released or a dedicated number is detached.

For 1:1 conversations, assignment_status reflects the current connection: "active" means the recipient is connected right now, and "released" means they disconnected. Group conversations instead return null assignment_id, assignment_status, and remote_number, plus is_group: true, a best-known participants list, and group_creation_status.

GET /conversations

List conversation summaries ordered by most recent message, with latest-message preview and unread count.

Query parameters

Identity-scoped API keys never see blocked rows in conversation summaries. With is_blocked=false, previews, ordering, unread counts, and totals are computed from non-blocked rows only.

start_datetime, end_datetime, and tz filter on the conversation's created_at — when the conversation was created, not its latest-message time. This list is ordered by most recent message, but the date filter is on creation time. Previews, unread counts, totals, and ordering still describe the full conversation — they are not sliced to the window. Both bounds are optional and non-breaking — omit them for unchanged behavior. See Filtering by date.

Response (200)

JSON

Error responses

GET /conversations/{conversation_id}

Get a single 1:1 or group conversation by ID. Known group UUIDs work directly even though group list results are opt-in. To read the messages in it, use GET /messages?conversation_id=....

Path parameters

Query parameters

Response (200)

JSON

For a group, group_creation_status is "creating" while the first send is establishing the group, "not_created" before creation or after a definitive creation failure, and "ready" after the group is established. A failed creation attempt remains in the same conversation's message history; send another message using its conversation_id to retry. See Group creation lifecycle.

Error responses

The bounded projection list follows the same compatibility rule: GET /conversation-projections defaults to include_groups=false, and GET /conversation-projections?include_groups=true opts groups in before pagination. GET /conversation-projections/{conversation_id} reads a known group directly.

Projection conversation objects add the same participants and is_group fields and return null assignment/recipient fields for groups. They do not include group_creation_status. MCP conversation reads use this projection surface; MCP can read opted-in groups but cannot send or perform group actions in V1.

GET /assignments

List active iMessage connections, newest first — one row per recipient currently connected to an agent identity through the router. Released connections are not returned; use assignment_status on conversation reads to detect a disconnect after the fact.

Query parameters

Response (200)

JSON

Error responses

POST /mark-read

Send a read receipt to the human — they see "Read" under their latest message — and mark the conversation's inbound messages as read.

Request body

Request example

JSON

Response (200)

JSON

updated_count: 0 means no inbound messages needed updating; the read receipt is still sent.

Error responses

POST /typing

Show the typing bubble to a 1:1 conversation's recipient — useful while your agent prepares a longer reply. The indicator clears on its own or when the next message arrives. Group conversations do not support typing indicators.

Request body

Response (200)

JSON

Error responses

Returned by List conversations; adds latest-message preview fields:

Group summaries use the same nullable assignment/remote fields and participants, is_group, and group_creation_status fields as the conversation object. Groups appear only when include_groups=true.

Returned by List connections. The pool line carrying the connection is managed by Inkbox and never appears in API responses.