Conversations - Inkbox

A conversation is one stable iMessage chat owned by an agent identity. It can contain multiple reply threads. Standard shared-service conversations are 1:1 and start when a human messages the agent. Organizations with their own organization-owned shared pool can instead connect through the API, available only by request. A dedicated line can also start 1:1 conversations and group chats. Conversations persist as history after a 1:1 connection is released or a dedicated line is detached. For 1:1 conversations, assignment_status reflects the current connection: "active" means the recipient is connected right now, and "released" means the connection is no longer active. A standard shared-service connection can also be released after inactivity. Expiry preserves history and does not introduce a separate assignment status. 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.

List conversations

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
`include_groups`	boolean	false	Include group conversations. Groups are excluded before pagination when false
`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
`start_datetime`	string	-	Only conversations created on or after this date/time
`end_datetime`	string	-	Only conversations created on or before this date/time; a bare date includes the whole day
`tz`	string	UTC	IANA zone for interpreting zone-less `start_datetime`/`end_datetime` values. Defaults to UTC

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

[
  {
    "id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
    "assignment_id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
    "assignment_status": "active",
    "remote_number": "+15555550123",
    "participants": ["+15555550123"],
    "is_group": false,
    "group_creation_status": null,
    "latest_text": "Can you move my 3pm?",
    "latest_message_at": "2026-06-09T14:30:00Z",
    "latest_direction": "inbound",
    "latest_has_media": false,
    "unread_count": 2,
    "total_count": 15
  }
]

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

Get conversation

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

Parameter	Type	Description
`conversation_id`	UUID	Unique identifier of the conversation

Query parameters

Parameter	Type	Description
`agent_identity_id`	UUID	Optional identity assertion — returns 404 if the conversation belongs to a different identity

Response (200)

JSON

{
  "id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
  "assignment_id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
  "assignment_status": "active",
  "remote_number": "+15555550123",
  "participants": ["+15555550123"],
  "is_group": false,
  "group_creation_status": null,
  "created_at": "2026-06-08T09:12:00Z",
  "updated_at": "2026-06-09T14:30:00Z"
}

For a group, group_creation_status is "creating" while the first send is establishing the group, "not_created" when no confirmed group is available, and "ready" after the group is established. Failed or unconfirmed creation attempts remain in the conversation’s message history. A fresh explicit send can try creation again, but do not blindly repeat an earlier message whose delivery is unknown. See Group creation lifecycle.

Error responses

Status	Description
404	Conversation not found, belongs to another organization, or belongs to a different identity than asserted

Get conversation thread

GET /conversations/{conversation_id}/threads/{thread_id}

Read one reply thread within a 1:1 or group conversation. Use thread_id from a message or thread response; it is an opaque UUID, not the root message ID. The thread must belong to the specified conversation. An unknown or inaccessible conversation or thread returns 404; an invalid cursor or pagination parameter returns 422. This endpoint accepts optional agent_identity_id, limit (default 50, maximum 200), and cursor. It returns the same thread response: thread_id, conversation_id, nullable thread_root_message_id, oldest-first messages, and next_cursor. Continue with the cursor until it is null. To discover the thread from any member message instead, use GET /messages/{message_id}/thread. To filter the existing flat, newest-first message list, pass both conversation_id and thread_id to GET /messages. That list returns 200 with [] for an unknown or inaccessible thread within an accessible conversation, rather than this endpoint’s 404.

List connections

GET /assignments

List active iMessage connections, newest first — one row per recipient currently connected to an agent identity through the router or the connect endpoint. 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

[
  {
    "id": "9b2e4a68-8cb1-4f18-b97d-a2324c8b4d1f",
    "remote_number": "+15555550123",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organization_id": "org_2abc123def456",
    "status": "active",
    "released_at": null,
    "created_at": "2026-06-08T09:11:00Z",
    "updated_at": "2026-06-08T09:11:00Z"
  }
]

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

Release connection

DELETE /assignments/{assignment_id}

Disconnect a recipient from an agent identity. Requires an admin API key or a console session; identity-scoped keys are rejected. Inbound from the recipient stops routing to the agent, sends into the conversation return 409, and the line carrying the connection can be reassigned. The conversation stays readable with assignment_status set to released. Outgoing messages whose sending has not started are canceled. They remain in history with status: "error" and error_code: "imessage_assignment_inactive". Pool connections report these cancellations through imessage.delivery_failed. Messages already being sent cannot be recalled. The recipient is not notified. Standard shared-service recipients reconnect by texting the router again, which starts a new connection with a new id. For a organization-owned shared pool, use connect, subject to its eligibility checks. You can also disconnect by identity and recipient without looking up an assignment ID.

Path parameters

Parameter	Type	Description
`assignment_id`	UUID	Connection identifier from List connections

Response (204)

No content.

Error responses

Status	Description
403	Caller is an identity-scoped API key
404	Connection not found or already released
409	`imessage_connection_busy`: another connection operation is in progress. Honor `Retry-After` and retry.

Mark conversation read

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

{
  "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819"
}

Response (200)

JSON

{
  "conversation_id": "82cf24f6-78fe-48da-a673-6a75b4f4a819",
  "updated_count": 2
}

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 connection is no longer active (`imessage_connection_expired` for inactivity expiry), or the conversation is a group and read receipts are not supported for groups
422	`recipient_not_e164` when the conversation has a non-phone sender address and is receive-only
502	Upstream delivery failure — safe to retry

Send typing indicator

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

Field	Type	Required	Description
`conversation_id`	UUID	Yes	The conversation whose recipient should see the typing bubble

Response (200)

JSON

{
  "status": "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 connection is no longer active (`imessage_connection_expired` for inactivity expiry), or the conversation is a group and typing indicators are not supported for groups
422	`recipient_not_e164` when the conversation has a non-phone sender address and is receive-only
502	Upstream delivery failure — safe to retry

Conversation object

A dedicated-line conversation can have a non-phone sender address. You can read its history, but it is receive-only. An assignment_status of "active" does not make every sender address a valid outbound recipient.

Field	Type	Description
`id`	string (UUID)	Stable conversation key for reads, replies, and supported actions
`assignment_id`	string (UUID) \| null	The 1:1 connection carrying the conversation; null for groups
`assignment_status`	string \| null	`"active"` or `"released"` for 1:1 conversations; null for groups
`remote_number`	string \| null	Sender address for a 1:1 conversation; can be a non-phone address on a dedicated line. Null for groups
`participants`	string[]	One sender address for a 1:1 conversation, or the append-only best-known E.164 participant history for a group
`is_group`	boolean	Whether this is an iMessage group chat
`group_creation_status`	string \| null	Group creation lifecycle: `"creating"`, `"not_created"`, or `"ready"`; null for 1:1 conversations
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Conversation summary object

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

Field	Type	Description
`latest_text`	string \| null	Latest message body preview
`latest_message_at`	string (ISO 8601) \| null	Latest message timestamp
`latest_direction`	string \| null	Direction of the latest message
`latest_has_media`	boolean	Whether the latest message carries media
`unread_count`	integer	Unread inbound message count in the summarized view
`total_count`	integer	Total message count in the summarized view

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.

Connection object

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

Field	Type	Description
`id`	string (UUID)	Connection ID — matches `assignment_id` on conversations
`remote_number`	string	The connected sender address; can be a non-phone address on a dedicated line
`agent_identity_id`	string (UUID)	The agent identity the human is connected to
`organization_id`	string	Owning organization
`status`	string	Always `"active"` on returned rows — released connections are not listed
`released_at`	string (ISO 8601) \| null	When the connection was released; `null` while active
`created_at`	string (ISO 8601)	When the human connected
`updated_at`	string (ISO 8601)	Last update timestamp

​List conversations

​Query parameters

​Response (200)

​Error responses

​Get conversation

​Path parameters

​Query parameters

​Response (200)

​Error responses

​Get conversation thread

​List connections

​Query parameters

​Response (200)

​Error responses

​Release connection

​Path parameters

​Response (204)

​Error responses

​Mark conversation read

​Request body

​Request example

​Response (200)

​Error responses

​Send typing indicator

​Request body

​Response (200)

​Error responses

​Conversation object

​Conversation summary object

​Connection object

List conversations

Query parameters

Response (200)

Error responses

Get conversation

Path parameters

Query parameters

Response (200)

Error responses

Get conversation thread

List connections

Query parameters

Response (200)

Error responses

Release connection

Path parameters

Response (204)

Error responses

Mark conversation read

Request body

Request example

Response (200)

Error responses

Send typing indicator

Request body

Response (200)

Error responses

Conversation object

Conversation summary object

Connection object