Skip to main content

DialogueRead

A dialogue is a single conversation between an agent and a contact over one messaging channel. Its lifecycle state is the state-tree node it sits on (last_tree_node_id): every agent's tree carries a fixed set of system nodes (initial, attempted, started, the failure and expiry outcomes) next to the nodes the tenant configures, so "where is this dialogue" has one answer. The record also tracks whether the bot is muted, the parking (pending) episode — a wait on top of the node, not a node of its own — and references to the last user/bot messages.

idIdrequired

Unique numeric identifier of the record.

product_idProduct Idrequired

ID of the product (workspace) that owns this record. Most endpoints scope access by product.

customer_id object

Canonical company-level customer ID used for shared communication context; null for legacy dialogues that have not been resolved.

anyOf
integer
agent_idAgent Idrequired

ID of the agent (a configured AI assistant / bot persona) this record belongs to.

contact_idContact Idrequired

ID of the contact this record relates to.

created_atdate-timerequired

Creation time (UTC, ISO 8601).

channel_idChannel Idrequired

ID of the messaging channel this record relates to.

chat_idChat Idrequired

The channel-specific chat identifier this dialogue maps to.

last_user_msg_id objectrequired
anyOf
integer
last_user_msg_at objectrequired
anyOf
date-time
last_bot_msg_id objectrequired
anyOf
integer
is_mainIs Mainrequired

Whether this is the active (primary) dialogue for the agent/contact pair; superseded dialogues are set to false.

bot_mutedBot Mutedrequired

When true, the bot will not auto-respond in this dialogue (e.g. after a human takeover).

pending_until objectrequired

When a parked dialogue is resumed (UTC). Null unless the dialogue is parked.

anyOf
date-time
pending_type object

Why the dialogue is parked (e.g. follow_up, human_clarification, async_tool, custom_follow_up).

anyOf
PendingType

Possible values: [follow_up, human_clarification, async_tool, custom_follow_up, future_meeting]

pending_ref object

Opaque reference associated with the parking episode (a clarification id, a tool call id, …).

anyOf
string
pending_id object

Identifier of the current parking episode. A deadline refresh keeps it; a new park replaces it, so a scheduler that acts on an episode can tell whether it is still the one it saw.

anyOf
uuid
state_revisionState Revision

Monotonic counter bumped by every lifecycle write to the dialogue (movements, parks, unparks, resets). Carry it into a decision made outside the write (an operator UI, a queued job) so the platform can reject the decision when the dialogue has moved on in the meantime.

Default value: 0
started_at objectrequired

When the dialogue first left the initial node (UTC).

anyOf
date-time
ext_id objectrequired

External identifier of the conversation in the channel/provider, if any.

anyOf
string
waba_opener_sent_after_window_num objectrequired
anyOf
integer
is_sub_outreachIs Sub Outreachrequired

Whether this outreach was sent into an existing chat with the contact rather than as a cold outreach. Set when an outreach campaign reuses a channel the contact was already messaged on (the agent's persist_channel_in_outreach option): to the contact it is the same conversation, but the platform counts it against a separate "sub-outreach" daily limit, since messaging platforms (WhatsApp, Telegram, …) are less restrictive inside existing dialogues than for cold outreach.

warmup_pair_id objectrequired

For phone-warmup conversations, the warmup pair this dialogue belongs to.

anyOf
integer
is_incomingIs Incomingrequired

Whether the dialogue was started by an inbound message from the contact.

is_group_chatIs Group Chatrequired

Whether the conversation is a group chat.

skip_response_for_user_msg_id objectrequired
anyOf
integer
skip_response_until objectrequired
anyOf
date-time
last_tree_node_idLast Tree Node Idrequired

ID of the state-tree node the dialogue currently sits on — its lifecycle state. Always set; the node belongs to the dialogue's agent, and GET /tree/ resolves it to a title, system_kind, is_final and group. A parked dialogue (is_pending) keeps its node and resumes there.

subject objectrequired

Email subject line, for email channels.

anyOf
string
enabled_playbook_version_idsinteger[]

Prompt-version IDs of the playbooks this dialogue has enabled, in enable order (by the model through its tool, or by the platform from crm_fields_conditions). Append-only: a playbook is never disabled, at most one version per playbook is held, and the dialogue keeps that version even if the playbook is edited later. Match them against enabled_version_id in the agent's playbook list (GET /prompts/?type=playbook) or against a playbook's version list.

is_pendingIs Pendingrequired

Whether the dialogue is waiting for something (a follow-up time, a manager's answer, a tool result, a meeting) before it acts again. Derived from pending_until. Parking does not move the dialogue: last_tree_node_id still names the node it will resume on.

DialogueRead
{
  "id": 0,
  "product_id": 0,
  "customer_id": 0,
  "agent_id": 0,
  "contact_id": 0,
  "created_at": "2024-07-29T15:51:28.071Z",
  "channel_id": 0,
  "chat_id": "string",
  "last_user_msg_id": 0,
  "last_user_msg_at": "2024-07-29T15:51:28.071Z",
  "last_bot_msg_id": 0,
  "is_main": true,
  "bot_muted": true,
  "pending_until": "2024-07-29T15:51:28.071Z",
  "pending_type": "follow_up",
  "pending_ref": "string",
  "pending_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state_revision": 0,
  "started_at": "2024-07-29T15:51:28.071Z",
  "ext_id": "string",
  "waba_opener_sent_after_window_num": 0,
  "is_sub_outreach": true,
  "warmup_pair_id": 0,
  "is_incoming": true,
  "is_group_chat": true,
  "skip_response_for_user_msg_id": 0,
  "skip_response_until": "2024-07-29T15:51:28.071Z",
  "last_tree_node_id": 0,
  "subject": "string",
  "enabled_playbook_version_ids": [
    0
  ],
  "is_pending": true
}