Skip to main content
A Conversation is a chat session between a visitor and one of your Chatbots. The API lets you read threads, update routing metadata, post replies as a human agent, and react to lifecycle events via webhooks.
Conversations are always created by a visitor through the chat widget — never via the API. The API is read-and-update only on the conversation itself; the one thing it can create is an agent reply on an existing conversation.

​
What you can do

Read

List conversations, fetch a single conversation, paginate its messages, read notes, list assigned tags.

Update metadata

PATCH /conversations/{id} to change status, priority, contact fields, assignee, or title.

Reply as an agent

POST /conversations/{id}/messages posts a human-agent reply. Triggers human-takeover side effects.

Organize

Pin notes, assign tags from your org-level palette via replace-set semantics.

​
What lives under a conversation

Sub-resourceEndpointNotes
Messages/conversations/{id}/messagesFull thread, including system markers. POST posts an agent reply.
Notes/conversations/{id}/notesInternal annotations. Not visible to the visitor.
Tags/conversations/{id}/tagsReplace-set on PUT. Tags themselves are managed under /conversation-tags.

​
The shape of a conversation

{
  "object": "conversation",
  "id": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "chatbot_id": "0a5c8e1f-3d2b-4a7c-9e1f-2c4d6b8a0e3f",
  "status": "agent_requested",
  "priority": "high",
  "title": "Refund request — order 4421",
  "summary": "Customer asking to return a damaged item.",
  "sentiment_score": 22,
  "contact_email": "[email protected]",
  "contact_name": "June Park",
  "contact_phone": null,
  "assigned_to": null,
  "last_message_preview": "I'd like to send it back, please.",
  "last_message_at": "2026-05-22T14:08:42+00:00",
  "resolved_at": null,
  "closed_at": null,
  "created_at": "2026-05-22T13:51:09+00:00",
  "qr_code_id": "f1d2c3b4-a5e6-4f7a-8b9c-0d1e2f3a4b5c",
  "product_id": null,
  "object_id": null
}
See the full field reference on the Conversation object page.
Cost data — tokens, credits, model used, billing rates — is intentionally never exposed via the API. Inspect usage in the dashboard.

​
Where next

Agent replies

Posting messages from an API caller. What it triggers, what it doesn’t.

Lifecycle

Status transitions, system markers, and which events fire when.

Object reference

Every field on the conversation object.

Conversation tags

Reusable org-level labels with replace-set assignment.