Aller au contenu
Développeurs

Endpoints

Conversations

Open, close, assign and hand over conversations, pause the AI, and leave team comments.

Les chemins sont relatifs à l’URL de base. Chaque carte indique la permission requise par l’appel et chaque paramètre, avec son type et ses limites.

GET
/conversations

List conversations, most recently updated first.

Permission : inbox
Ancien format de réponse

Paramètres de requête

  • limitfacultatifinteger

    1–100, default 20.

  • offsetfacultatifinteger

    Number of conversations to skip, default 0.

  • Returns a plain JSON array (offset pagination, not the list envelope).
GET
/conversations/:id

Retrieve a conversation with its messages, as { conversation, messages }.

Permission : inbox
Ancien format de réponse

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

GET
/conversations/:id/messages

Poll the AI replies of an API-channel conversation. Returns { conversationId, messages, cursor } with assistant messages newer than since.

Permission : inbox
Ancien format de réponse

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

Paramètres de requête

  • sincefacultatifinteger

    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.
PUT
/conversations/:id/status

Open or close a conversation, with an optional closing note.

Permission : inbox

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

Corps JSON

  • statusobligatoireenum

    New status.

    Valeurs autorisées :openclosed

  • closing_note_idfacultatifinteger | null

    A closing note from GET /closing-notes. Only when closing.

  • closing_note_textfacultatifstring | null

    Free-text closing note, up to 2,000 characters. Only when closing.

  • allow_reopenfacultatifboolean

    When closing: whether a new customer message reopens this conversation (true) or starts a new one (false).

PUT
/conversations/:id/assignee

Assign the conversation to a team member, or unassign it.

Permission : inbox

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

Corps JSON

  • user_idfacultatifstring | null

    A user from GET /users. Omit or send null to unassign.

POST
/conversations/:id/ai/pause

Stop AI replies on a conversation.

Permission : inbox

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

Corps JSON

  • untilfacultatifstring (ISO 8601 date-time with offset) | null

    Resume automatically at this time (must be in the future). Omit to pause until resumed.

  • reasonfacultatifstring

    Up to 100 characters, passed to the conversation.ai_paused event.

POST
/conversations/:id/ai/resume

Turn AI replies back on.

Permission : inbox

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

POST
/conversations/:id/handover/resolve

Mark the conversation's open handover requests as handled. Returns resolved_count.

Permission : inbox

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

GET
/conversations/:id/comments

List internal team comments on a conversation, newest first.

Permission : inbox
Paginé

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

POST
/conversations/:id/comments

Add an internal team comment. It is never sent to the customer.

Permission : inbox

Paramètres de chemin

  • idobligatoireinteger

    Conversation ID.

Corps JSON

  • bodyobligatoirestring

    1–5,000 characters.

  • mentionsfacultatifarray of strings

    Up to 20 user IDs from GET /users to notify.