---
title: "Conversations"
description: "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](/docs/leads-and-contacts/managing-contacts), if the visitor was identified. |
| `title` | string | The conversation's title. |
| `state` | string | Who is handling it. See [Conversation states](#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](/docs/developers/agents-and-chat#send-a-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](#get-a-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

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

Returns a [paginated list](/docs/developers#lists-and-pagination), most recently active first. Messages aren't included.

### Filter by your user ID

```bash
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

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

Returns the conversation with its visible messages, oldest first:

```json
{
  "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.