The conversation object

Shape of the Conversation resource, what's saved when a user (or trigger) chats with an agent.

The Conversation resource is the persistent record of a chat between an agent and a user (or a webhook). Every message, every tool call, every sub-agent handoff lives inside a conversation.

Object shape

{
  "id": "conv_6a392325b438d825ccaf0dc1",
  "title": "process ticket 549",
  "source": "autonomous",
  "agent_id": "agent_6a28e310f2ec711ef6dc1dcf",
  "model": "gpt-5",
  "autonomous": true,
  "is_onboarding": false,
  "is_simulation": false,
  "conversation_number": 225,
  "parent_conversation_id": null,
  "credits_used": 3,
  "metadata": {
    "ticketId": 549,
    "webhookReceivedAt": "2026-06-10T05:25:59.439Z"
  },
  "message_count": 6,
  "last_message_at": "2026-06-10T05:26:55.455Z",
  "created_at": "2026-06-10T05:25:59.447Z",
  "updated_at": "2026-06-10T05:26:56.048Z"
}

Attributes

Field	Type	Notes
`id`	string	Prefixed identifier `conv_<24 hex>`.
`title`	string \| null	LLM-generated summary of what the conversation is about.
`source`	enum	`"dashboard"` \| `"autonomous"` \| `"embed"` \| `"sub-agent"`. How the conversation started.
`agent_id`	string \| null	Which agent handled it. Null on agent-less conversations.
`model`	string \| null	Model that ran the conversation. May be `null` if it predates model tracking.
`autonomous`	boolean	`true` if fired by a webhook/scheduled trigger, not a user.
`is_onboarding`	boolean	The one-time post-onboarding welcome conversation.
`is_simulation`	boolean	Test runs fired via the agent builder's "Test run" button.
`conversation_number`	integer \| null	Per-org sequence number. `null` for sub-agent runs (they don't get a number).
`parent_conversation_id`	string \| null	Set on sub-agent runs. Points at the parent conversation.
`credits_used`	integer	Credits deducted across all assistant responses in this conversation.
`metadata`	object \| null	Free-form. Common keys: `ticketId`, `ticket_id`, plus connector-specific extras. Filterable via `?metadata[KEY]=VALUE`.
`message_count`	integer \| null	Number of messages. Returns `null` in list responses (perf cost); the detail endpoint returns the real count.
`last_message_at`	ISO 8601	Updated on every new message.
`created_at`	ISO 8601	Always UTC.
`updated_at`	ISO 8601	Bumped on any change.

Two response shapes

Conversation endpoints return either the summary shape (above) or the detail shape (summary + messages[]):

List endpoint returns summaries (no messages).
Retrieve endpoint returns the detail (with full message thread).
Messages endpoint paginates a single conversation's messages.

The `messages[]` array

Each message has its own shape:

{
  "id": "msg_64f1c0...",
  "role": "user" | "assistant" | "tool" | "system",
  "content": "...",
  "tool_calls": [
    { "id": "call_abc", "name": "zendesk_get_ticket", "arguments": "{...}", "status": "completed" }
  ],
  "tool_call_id": null,
  "tool_name": null,
  "connector_type": null,
  "model": "gpt-5.4",
  "created_at": "2026-06-10T05:25:59.500Z"
}

For role: "tool" messages, content is usually a JSON-stringified blob, consumers should attempt JSON.parse before treating it as text. tool_calls is only set on assistant messages that invoked tools.

The `trigger_payload` field (opt-in)

For autonomous conversations, the raw webhook payload that fired the run is stored alongside the conversation. It's not returned by default because it can contain customer PII (requester email, ticket body, custom fields). Pass ?include_trigger_payload=true on the retrieve endpoint to opt in.

📘

message_count is null in lists by design

Computing message counts at list time requires loading every conversation's full message array, a perf cliff we deliberately avoid. The detail endpoint loads the array and returns the real count.