A conversation is one thread between a connected human and an agent identity. Conversations are created automatically when a human connects through the router and messages the agent, and they persist as history even if the human later disconnects.
Every conversation read carries an assignment_status field reflecting the current connection: "active" means the recipient is connected right now, "released" means they disconnected. Sends, tapbacks, read receipts, and typing indicators into a released conversation return 409 until the recipient reconnects through the router.
List conversations GET
GET /conversations
List conversation summaries ordered by most recent message, with latest-message preview and unread count.
Query parameters
Parameter
Type
Default
Description
agent_identity_id
UUID
-
Narrow to one identity. Ignored for identity-scoped API keys, which always see their own identity
limit
integer
50
Number of results (1-200)
offset
integer
0
Pagination offset
is_blocked
boolean
-
Filter by blocked state of the underlying messages. true summarizes blocked rows only, false non-blocked rows only, and omitting it applies the caller's default visibility
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.
Response (200)
JSON
Error responses
Status
Description
400
agent_identity_id names an identity that is not enabled for iMessage
403
Identity-scoped key passed an agent_identity_id other than its own
404
agent_identity_id not found, or not visible to the caller
Optional identity assertion — returns 404 if the conversation belongs to a different identity
Response (200)
JSON
Error responses
Status
Description
404
Conversation not found, belongs to another organization, or belongs to a different identity than asserted
List connections GET
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
Parameter
Type
Default
Description
agent_identity_id
UUID
-
Narrow to one identity. Ignored for identity-scoped API keys, which always see their own identity
limit
integer
50
Number of results (1-200)
offset
integer
0
Pagination offset
Response (200)
JSON
Error responses
Status
Description
403
Identity-scoped key passed an agent_identity_id other than its own
404
agent_identity_id not found, or not visible to the caller
Mark conversation read POST
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
Field
Type
Required
Description
conversation_id
UUID
Yes
The conversation to mark read
Request example
JSON
Response (200)
JSON
updated_count: 0 means no inbound messages needed updating; the read receipt is still sent.
Error responses
Status
Description
400
The conversation's identity is not enabled for iMessage
403
The conversation's recipient is blocked by a contact rule
404
Conversation not found, or not visible to the caller
409
The recipient has disconnected from this agent and must reconnect through the router
502
Upstream delivery failure — safe to retry
Send typing indicator POST
POST /typing
Show the typing bubble to the conversation's recipient — useful while your agent prepares a longer reply. The indicator clears on its own or when the next message arrives.
Request body
Field
Type
Required
Description
conversation_id
UUID
Yes
The conversation whose recipient should see the typing bubble
Response (200)
JSON
Error responses
Status
Description
400
The conversation's identity is not enabled for iMessage
403
The conversation's recipient is blocked by a contact rule
404
Conversation not found, or not visible to the caller
409
The recipient has disconnected from this agent and must reconnect through the router
502
Upstream delivery failure — safe to retry
Conversation object
Field
Type
Description
id
string (UUID)
Conversation ID — the stable key for reads, replies, mark-read, and typing
assignment_id
string (UUID)
The connection (one human ↔ one agent) carrying this conversation
assignment_status
string
"active" while the recipient is connected, "released" after they disconnect
JSON