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

​
Identifiers

​
object
string
required
Always "conversation".
​
id
string
required
UUID. Use this as your foreign key in external systems.
​
chatbot_id
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

​
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.
​
priority
string
required
One of low, medium, high. Defaults to medium on creation; agents bump it via PATCH.
​
title
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.
​
summary
string | null
Longer recap of the conversation, generated when the thread is resolved or closed. Set by AI; not editable via API.
​
sentiment_score
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.
​
contact_email
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.
​
contact_name
string | null
Display name. Free-text — don’t assume any particular format.
​
contact_phone
string | null
Phone number, as the visitor typed it. No normalization.

​
Assignment

​
assigned_to
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.
​
qr_code_id
string | null
QR code the visitor scanned to get here. null for any other entry path.
​
product_id
string | null
Product that drove this session, when the visitor scanned a product code.
​
object_id
string | null
Custom object that drove this session, when the visitor scanned an /o/<slug> URL.

​
Activity

​
last_message_preview
string | null
First 200 characters of the most recent message. Use for inbox rows — saves a round trip to /messages.
​
last_message_at
string | null
ISO 8601. Updated on every message, including system markers.

​
Timestamps

​
resolved_at
string | null
ISO 8601. Stamped when status moves to resolved. Cleared on reopen.
​
closed_at
string | null
ISO 8601. Stamped when status moves to closed. Cleared on reopen.
​
created_at
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
}
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.