Conversations

List conversations

Returns your project’s conversations, newest activity first, cursor-paginated.

{
  "results": [
    {
      "id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "status": "PROCESSING",
      "channel_type": "TELEGRAM",
      "ticket_number": 1042,
      "message_count": 7,
      "contact": { "id": "7c4e9b02-1a55-4e88-b0d1-2f3a4b5c6d7e", "display_name": "Jane Doe" },
      "updated_at": "2026-07-01T10:40:00+00:00"
    }
  ],
  "next_cursor": "MjAyNi0wNy0wMVQxMDo0MDowMHwzZjJi",
  "has_more": true
}

Query parameters

• status — filter by status: NEW, ESCALATING, PROCESSING, WAITING, RESOLVED, CLOSED.
• channel_id — UUID of a channel to filter by.
• updated_since — ISO-8601 timestamp; only conversations updated at or after this time.
• cursor — opaque pagination cursor from a previous response’s next_cursor.
• limit — page size, default 50, max 100.

See Errors, rate limits & pagination for how cursor pagination works.

Get a conversation

{
  "id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
  "status": "PROCESSING",
  "priority": "HIGH",
  "subject": "Refund request",
  "source": "CHANNEL",
  "channel_id": "9a1c5f30-2b6d-4c71-8e42-1a2b3c4d5e6f",
  "channel_type": "TELEGRAM",
  "ticket_number": 1042,
  "detected_language": "en",
  "message_count": 7,
  "contact": { "id": "7c4e9b02-1a55-4e88-b0d1-2f3a4b5c6d7e", "display_name": "Jane Doe" },
  "created_at": "2026-07-01T10:12:00+00:00",
  "updated_at": "2026-07-01T10:40:00+00:00",
  "last_message_at": "2026-07-01T10:40:00+00:00"
}

{ "detail": "conversation_not_found" }

The conversation object

• id — UUID.
• status — one of the six states above.
• priority — LOW / MEDIUM / HIGH / URGENT, or null.
• subject, source (CHANNEL/PORTAL/OPERATOR), ticket_number, detected_language, message_count.
• channel_id, channel_type (TELEGRAM, TELEGRAM_GROUP, WEB, EMAIL, HELPDESK, …).
• contact — { id, display_name }.
• created_at, updated_at, last_message_at — ISO-8601.

TELEGRAM_GROUP conversations (one bot serving a Telegram group chat) are read-only in API v1: sending a message returns 400 group_conversations_not_supported, and status changes return 400 status_change_not_supported_for_group.

Conversation statuses

• NEW — handled by AI, no operator yet.
• ESCALATING — flagged for a human; operators notified.
• PROCESSING — an operator has taken over.
• WAITING — operator is waiting on the customer.
• RESOLVED — resolved; a customer reply can reopen it.
• CLOSED — closed.

What the detail response also carries

GET /api/v1/conversations/{id}/ returns more than the list does. These fields cost a query each, which is why they are on the single-conversation response only:

• assigned_operator and assigned_operators — who is handling it, with their display name and avatar.
• tags — the conversation’s tags.
• rating — the customer’s satisfaction rating when they left one: { score, comment, rated_at }, otherwise null.
• ai_autoresponse_mode and ai_active — the AI switch, and whether the AI is actually replying right now.
• webchat — web-chat conversations only: the page the visitor is on, their recent browsing, and who they are.

Visitor details and the pii scope

The webchat.visitor block carries country, browser and operating system with the ordinary read scope. The visitor’s IP address and user agent are only included if the key also has pii — so a key you use for reporting need not carry personal data it has no use for.

Start a conversation

POST /api/v1/conversations/ opens an outbound conversation with a contact — for a shipping notice, say. The contact must already have an identity on that channel (see the Contacts article); without one there is no address to deliver to.

{
  "contact_id": "a7c3…",
  "channel_id": "your-email-channel-id",
  "subject": "Your order has shipped",
  "content": "Tracking number: 1Z999…"
}

The conversation starts unassigned and in NEW, which means your AI assistant is live on it: if the customer replies, they get an answer instead of landing in an empty queue. If you would rather it stayed silent, set ai_autoresponse_mode to OFF or assign an operator.

Email and helpdesk channels allow several open conversations with the same person; everywhere else a second one returns 409 conversation_already_open with the id of the existing conversation.

Assigning an operator

POST /api/v1/conversations/{id}/assign/ with {"operator_id": "…"} hands the conversation to a teammate, moving it to PROCESSING exactly as claiming it in the dashboard does. POST .../unassign/ returns it to the queue. Both need the admin scope; get operator ids from GET /api/v1/operators/.

This is why PATCH refuses to set PROCESSING directly — that status means a person has the conversation, so it follows from assigning one rather than being set on its own.

Tags

POST /api/v1/conversations/{id}/tags/ with {"tag_id": "…"} adds a tag and DELETE /api/v1/conversations/{id}/tags/{tag_id}/ removes one; PATCH with tag_ids replaces the whole set. GET /api/v1/tags/ lists what is available.

Finding the ids you need

Three read-only endpoints exist so you do not have to hard-code anything: GET /api/v1/tags/, GET /api/v1/channels/ and GET /api/v1/operators/.