The Conversation object

A conversation is a UUID-keyed record describing one visitor chat session. It’s the parent for messages, notes, and tag assignments.

Identifiers

string

required

Always "conversation".

string

required

UUID. Use this as your foreign key in external systems.

string | null

UUID of the Chatbot the visitor was talking to. null if the conversation predates the Chatbot being deleted or originated outside any chatbot.

Updating a conversation

PATCH /conversations/{id} accepts only the writable fields — status, priority, title, the three contact_* fields, and assigned_to. The endpoint is strict: any unknown or unrecognized field in the body (including read-only fields like summary, sentiment_score, or last_message_at) is rejected with 400. Send only the fields you intend to change.

Status

string

required

One of open, bot_active, agent_requested, resolved, closed, archived. See Lifecycle for the transition rules.You can read bot_active here, but you cannot set it via PATCH — once a human or API caller is driving the conversation, you can’t put the bot back in the loop.

string

required

One of low, medium, high. Defaults to medium on creation; agents bump it via PATCH.

string | null

Human-readable summary line shown in the inbox. The Chatbot generates this automatically once enough context has accumulated; you can overwrite it via PATCH.

string | null

Longer recap of the conversation, generated when the thread is resolved or closed. Set by AI; not editable via API.

integer | null

Integer between 0 and 100. 0 is fully negative, 100 fully positive. null until the model has scored the thread. Set by AI; not editable via API.

Contact

The visitor’s volunteered contact details. All three are nullable and stay null for anonymous threads.

string | null

Best email of record for the visitor. Used to send the away-email follow-up when an agent replies and the visitor isn’t watching the tab.

string | null

Display name. Free-text — don’t assume any particular format.

string | null

Phone number, as the visitor typed it. No normalization.

Assignment

string | null

UUID of the agent who currently owns the conversation. null means unassigned (anyone on the team can pick it up). When an API key posts the first reply, the conversation stays unassigned — there’s no user to claim with.When you set assigned_to via PATCH, the id must belong to an active member of your organization; an unknown user, or a removed/foreign member, is rejected with 422. Pass null to unassign.

Attribution

Set at creation time from the visitor’s entry point. Drives routing rules and analytics.

string | null

QR code the visitor scanned to get here. null for any other entry path.

string | null

Product that drove this session, when the visitor scanned a product code.

string | null

Custom object that drove this session, when the visitor scanned an /o/<slug> URL.

object | null

The QR scan context the chatbot actually used for this conversation: which code was scanned, its group, and the properties the chatbot received. Refreshed on each chatbot turn, so after you change a code’s or group’s properties, the next reply (and this field) picks them up within about a minute. null when the conversation didn’t start from a QR scan.

Show QR context fields

object

required

{ id, name } of the scanned QR code. name may be null.

object | null

required

{ id, name } of the code’s QR group, or null when the code isn’t in a group.

object

required

Flat key → value map of string properties. The group’s properties merged with the code’s own; the code wins on a key clash. Empty {} when neither has any.

Activity

string | null

First 200 characters of the most recent message. Use for inbox rows — saves a round trip to /messages.

string | null

ISO 8601. Updated on every message, including system markers.

Timestamps

string | null

ISO 8601. Stamped when status moves to resolved. Cleared on reopen.

string | null

ISO 8601. Stamped when status moves to closed. Cleared on reopen.

string

required

ISO 8601. Set by the chat widget at session start.

Example

{
  "object": "conversation",
  "id": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "chatbot_id": "0a5c8e1f-3d2b-4a7c-9e1f-2c4d6b8a0e3f",
  "status": "open",
  "priority": "high",
  "title": "Refund request — order 4421",
  "summary": null,
  "sentiment_score": 22,
  "contact_email": "[email protected]",
  "contact_name": "June Park",
  "contact_phone": null,
  "assigned_to": "c2d4f6a8-1b3e-4d5f-9a8c-7b6e2f1d0a9b",
  "last_message_preview": "Thanks — I'll send the return label to your inbox now.",
  "last_message_at": "2026-05-22T14:11:08+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,
  "qr_context": {
    "qr_code": {
      "id": "f1d2c3b4-a5e6-4f7a-8b9c-0d1e2f3a4b5c",
      "name": "Room 7 — TV"
    },
    "qr_group": {
      "id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "name": "Room 7"
    },
    "properties": {
      "TV Model Number": "LG 43UQ9000PSD",
      "Kettle Model Number": "Breville LKE755"
    }
  }
}

Fields you won’t find here. Cost, token usage, the model that handled a turn, billing rates, internal resume tokens, and presence timestamps are all server-only. They never appear in API responses or webhook payloads.

Get started

Identity

Concepts

Webhooks

Chatbots

Customers

Articles

Article Categories

Article Tags

Knowledge Bases

Conversations

Conversation Tags

Submissions

Pages

QR Codes

QR Groups

Products

Objects

Custom Domains

Custom Domain Routes

Team

Identifiers

Updating a conversation

Status

Contact

Assignment

Attribution

Activity

Timestamps

Example

​Identifiers

​Updating a conversation

​Status

​Contact

​Assignment

​Attribution

​Activity

​Timestamps

​Example

Identifiers

Updating a conversation

Status

Contact

Assignment

Attribution

Activity

Timestamps

Example