Conversations

Read an agent's conversations and messages through the Chatvox API.

Conversations include your customers’ chats with an agent: from your website widget, Public Chat, WhatsApp, and the API. Your teammates’ chats inside Chatvox and Playground previews aren’t included.

The conversation object

Field	Type	Description
`id`	string	The conversation’s ID.
`agent_id`	string	The agent it belongs to.
`contact_id`	string or null	The contact, if the visitor was identified.
`title`	string	The conversation’s title.
`state`	string	Who is handling it. See Conversation states.
`source`	string	Where it happened: `embed` (web widget), `public_link` (Public Chat), `whatsapp`, or `api`.
`external_user_id`	string or null	Your user ID, if you sent one with the first API message.
`last_message_preview`	string or null	The start of the latest message.
`last_active_at`	string	When the conversation was last active.
`created_at`	string	When it started.
`messages`	array	Only when you get a single conversation.

Conversation states

`state`	Meaning
`ai_active`	The AI agent is answering.
`handoff_requested`	The visitor or agent asked for a person, and the team hasn’t picked it up yet. Website, Public Chat, and WhatsApp only.
`human_active`	A teammate is handling the conversation. The AI doesn’t reply.
`resolved`	A teammate resolved the conversation.

List conversations

GET /api/v1/agents/{agent}/conversations

Returns a paginated list, most recently active first. Messages aren’t included.

Filter by your user ID

curl "https://my.chatvox.co/api/v1/agents/AGENT_ID/conversations?external_user_id=user-42" \
  -H "Authorization: Bearer cvx_your_key"

Returns only the API conversations you started with that external_user_id.

Get a conversation

GET /api/v1/agents/{agent}/conversations/{conversation}

Returns the conversation with its visible messages, oldest first:

{
  "id": "01a121f0-6be6-700e-bda0-9860a935556f",
  "state": "ai_active",
  "source": "api",
  "…": "…",
  "messages": [
    { "id": 725, "role": "user", "origin": "visitor", "content": "What are your plans?", "created_at": "…" },
    { "id": 726, "role": "assistant", "origin": "ai", "content": "We have four plans…", "created_at": "…" }
  ]
}

The message object

Field	Type	Description
`id`	integer	The message’s ID.
`role`	string	`user` for the customer, `assistant` for replies.
`origin`	string	Who wrote it: `visitor`, `ai`, `teammate`, or `system`.
`content`	string	The message text, in Markdown for replies.
`created_at`	string	When it was sent.

Internal steps, such as action calls, aren’t included. Internal notes your team adds in the Helpdesk are never returned.