Endpoints
Conversations
Open, close, assign and hand over conversations, pause the AI, and leave team comments.
Paths are relative to the base URL. Each card lists the permission the call needs and every parameter, with its type and limits.
/conversationsList conversations, most recently updated first.
Query parameters
- limitoptionalinteger
1–100, default 20.
- offsetoptionalinteger
Number of conversations to skip, default 0.
- Returns a plain JSON array (offset pagination, not the list envelope).
/conversations/:idRetrieve a conversation with its messages, as { conversation, messages }.
Path parameters
- idrequiredinteger
Conversation ID.
/conversations/:id/messagesPoll the AI replies of an API-channel conversation. Returns { conversationId, messages, cursor } with assistant messages newer than since.
Path parameters
- idrequiredinteger
Conversation ID.
Query parameters
- sinceoptionalinteger
Return only messages with a larger ID (pass the previous cursor). Default 0.
- For every message of any conversation, use GET /messages?conversation_id= instead.
/conversations/:id/statusOpen or close a conversation, with an optional closing note.
Path parameters
- idrequiredinteger
Conversation ID.
JSON body
- statusrequiredenum
New status.
Allowed values:
openclosed - closing_note_idoptionalinteger | null
A closing note from GET /closing-notes. Only when closing.
- closing_note_textoptionalstring | null
Free-text closing note, up to 2,000 characters. Only when closing.
- allow_reopenoptionalboolean
When closing: whether a new customer message reopens this conversation (true) or starts a new one (false).
/conversations/:id/assigneeAssign the conversation to a team member, or unassign it.
Path parameters
- idrequiredinteger
Conversation ID.
JSON body
- user_idoptionalstring | null
A user from GET /users. Omit or send null to unassign.
/conversations/:id/ai/pauseStop AI replies on a conversation.
Path parameters
- idrequiredinteger
Conversation ID.
JSON body
- untiloptionalstring (ISO 8601 date-time with offset) | null
Resume automatically at this time (must be in the future). Omit to pause until resumed.
- reasonoptionalstring
Up to 100 characters, passed to the conversation.ai_paused event.
/conversations/:id/ai/resumeTurn AI replies back on.
Path parameters
- idrequiredinteger
Conversation ID.
/conversations/:id/handover/resolveMark the conversation's open handover requests as handled. Returns resolved_count.
Path parameters
- idrequiredinteger
Conversation ID.
/conversations/:id/commentsList internal team comments on a conversation, newest first.
Path parameters
- idrequiredinteger
Conversation ID.
/conversations/:id/commentsAdd an internal team comment. It is never sent to the customer.
Path parameters
- idrequiredinteger
Conversation ID.
JSON body
- bodyrequiredstring
1–5,000 characters.
- mentionsoptionalarray of strings
Up to 20 user IDs from GET /users to notify.