# Conversations
> Quickchat AI captures every conversation across all channels. These endpoints let you list and retrieve them.
Quickchat AI automatically captures and analyzes every conversation your AI Agent has across all channels — widget, Slack, WhatsApp, Telegram, and more. The Conversations API gives you programmatic access to this rich dataset for building custom dashboards, feeding downstream analytics pipelines, triggering CRM workflows, or integrating with your existing business intelligence tools.
Every conversation includes AI-powered analysis: **sentiment detection**, **topic classification**, **resolution tracking**, and **automatic flagging** of conversations that may need human attention. Combined with full message history, tracked link clicks, and custom metadata, you have everything you need to understand how visitors interact with your AI Agent.
Conversation data is spread across several endpoints:
- **List Conversations** — Basic info, visitor details, status. Use for dashboards, overviews, and filtered queries
- **Get Conversation Details** — Full info including `unified_analysis` (AI-generated insights) and `client_metadata`
- **Get Conversation Events** — Complete message history, tracked link clicks, and log entries
- **Get/Set Metadata** — Custom key-value data you attach to conversations (see [Conversation Metadata](/api-reference/conversations/conversation-metadata/))
## List Conversations
**Scope: read_all**
`GET https://app.quickchat.ai/v1/api_core/conversations`
**Query Parameters**
| Parameter | Description |
|-----------|-------------|
| `limit`
integer | Items per page |
| `offset`
integer | Items to skip |
| `query`
string | Search by order number, UUID, or message text |
| `assignee_type`
string | `"ai_assistant"`, `"human_operator"`, or `"unassigned"` |
| `source`
string | `"widget"`, `"slack"`, `"telegram"`, `"whatsapp"`, etc. |
| `resolution_status`
string | `"open"` or `"resolved"` |
| `created_timestamp_start_date` datetime | Filter by creation date (start) |
| `created_timestamp_end_date` datetime | Filter by creation date (end) |
| `last_message_at_start_date` datetime | Filter by last message date (start) |
| `last_message_at_end_date` datetime | Filter by last message date (end) |
| `most_frequent_language`
string | Filter by detected language |
**Shell**
```shell
curl 'https://app.quickchat.ai/v1/api_core/conversations?limit=10&resolution_status=open' \
-H 'Authorization: Bearer '
```
**Python**
```python
import requests
response = requests.get(
url="https://app.quickchat.ai/v1/api_core/conversations",
headers={"Authorization": "Bearer "},
params={"limit": 10, "resolution_status": "open"},
)
data = response.json()
```
**Response** `200 OK`
```json
{
"items": [
{
"id": "conv-uuid-1234",
"ord": 42,
"created_at": "2026-01-15T10:30:00Z",
"last_message_at": "2026-01-15T10:35:00Z",
"title": "Return policy question",
"source": "widget",
"terminated": false,
"resolution_status": "open",
"has_unread_messages": true,
"supports_inbox_control": true,
"last_message_content": "What is your return policy?",
"most_frequent_language": "en",
"assignee": {
"type": "ai_assistant"
},
"visitor_name": "John",
"visitor_email": "john@example.com",
"visitor_phone_number": null,
"visitor_label": null
}
],
"offset": 0,
"limit": 10,
"count": 42
}
```
| Field | Description |
|-------|-------------|
| `id`
string | Conversation UUID |
| `ord`
integer | Sequential conversation number |
| `created_at`
string | Conversation creation timestamp |
| `last_message_at`
string | Timestamp of the most recent message |
| `title`
string | AI-generated conversation title |
| `source`
string | Channel the conversation originated from (e.g., `"widget"`, `"slack"`, `"whatsapp"`) |
| `terminated`
boolean | Whether the conversation has ended |
| `resolution_status`
string | `"open"` or `"resolved"` |
| `has_unread_messages`
boolean | Whether there are unread messages |
| `supports_inbox_control`
boolean | Whether the conversation source supports inbox control (assign, handoff) |
| `last_message_content`
string | Content of the last message in the conversation |
| `most_frequent_language`
string | Most frequently detected language in the conversation |
| `assignee`
object | Current assignee (`type`: `"ai_assistant"`, `"human_operator"`, or `"unassigned"`) |
| `visitor_name`
string or null | Visitor's name (from pre-chat form or channel profile) |
| `visitor_email`
string or null | Visitor's email address |
| `visitor_phone_number`
string or null | Visitor's phone number |
| `visitor_label`
string or null | Custom label assigned to the visitor |
## Get Conversation Details
**Scope: read_all**
`GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/`
**Shell**
```shell
curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/ \
-H 'Authorization: Bearer '
```
**Python**
```python
import requests
response = requests.get(
url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/",
headers={"Authorization": "Bearer "},
)
data = response.json()
```
**Response** `200 OK`
```json
{
"id": "conv-uuid-1234",
"ord": 42,
"created_at": "2026-01-15T10:30:00Z",
"last_message_at": "2026-01-15T10:35:00Z",
"title": "Return policy question",
"source": "widget",
"terminated": false,
"resolution_status": "open",
"has_unread_messages": true,
"supports_inbox_control": true,
"last_message_content": "What is your return policy?",
"most_frequent_language": "en",
"assignee": {
"type": "ai_assistant"
},
"url": null,
"client_metadata": {"userId": 12},
"last_visitor_message_at": "2026-01-15T10:34:00Z",
"unified_analysis": {
"sentiment": "neutral",
"resolution_status": "open",
"topic": "Return policy",
"is_flagged": false,
"flag_reason": null
},
"visitor_name": "John",
"visitor_email": "john@example.com",
"visitor_phone_number": null,
"visitor_label": null
}
```
The detail response includes all fields from the list response, plus:
| Field | Description |
|-------|-------------|
| `url`
string or null | URL of the page where the conversation started (widget only) |
| `client_metadata`
object or null | Custom key-value pairs attached to the conversation |
| `last_visitor_message_at`
string | Timestamp of the last visitor message |
| `unified_analysis`
object or null | AI-generated analysis of the conversation (see below) |
**`unified_analysis` fields:**
| Field | Description |
|-------|-------------|
| `sentiment`
string | AI-detected conversation sentiment (e.g., `"positive"`, `"neutral"`, `"negative"`) |
| `resolution_status`
string | AI-assessed resolution status (may differ from top-level `resolution_status`) |
| `topic`
string | AI-detected conversation topic |
| `is_flagged`
boolean | Whether the AI flagged this conversation for human review |
| `flag_reason`
string or null | Reason the conversation was flagged |
:::note[resolution_status vs unified_analysis.resolution_status]
The top-level `resolution_status` field (`"open"` or `"resolved"`) is the canonical status set manually or by automation rules.
The `unified_analysis.resolution_status` is computed by AI analysis and may differ — for example, the AI might classify a conversation as resolved based on content analysis even though the top-level status is still `"open"`. Use the top-level field for filtering and workflow; use `unified_analysis` for analytics and insights.
:::
## Get Conversation Events
Retrieve all events (messages, tracked links, logs) for a conversation.
**Scope: read_all**
`GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/events/`
**Query Parameters**
| Parameter | Description |
|-----------|-------------|
| `limit`
integer | Items per page |
| `offset`
integer | Items to skip |
**Shell**
```shell
curl 'https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/?limit=20' \
-H 'Authorization: Bearer '
```
**Python**
```python
import requests
response = requests.get(
url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/",
headers={"Authorization": "Bearer "},
params={"limit": 20},
)
data = response.json()
```
**Response** `200 OK`
```json
{
"items": [
{
"type": "message",
"data": {
"id": "msg-uuid-001",
"ord": 1,
"created_at": "2026-01-15T10:30:00Z",
"content": "Hello! How can I help you today?",
"author": "ai_assistant",
"handoff_state": null,
"message_insights": null,
"feedback": null,
"client_metadata": null,
"sources_generated": [],
"is_welcome": true,
"attachments": []
}
},
{
"type": "message",
"data": {
"id": "msg-uuid-002",
"ord": 2,
"created_at": "2026-01-15T10:31:00Z",
"content": "What is your return policy?",
"author": "visitor",
"handoff_state": null,
"message_insights": null,
"feedback": null,
"client_metadata": null,
"sources_generated": [],
"is_welcome": false,
"attachments": []
}
}
],
"offset": 0,
"limit": 20,
"count": 2
}
```
**Event types:** `message`, `tracked_link`, `log`
**Author types:** `ai_assistant`, `visitor`, `human_operator`
| Field | Description |
|-------|-------------|
| `type`
string | Event type: `"message"`, `"tracked_link"`, or `"log"` |
| `data.id`
string | Message unique identifier |
| `data.ord`
integer | Sequential message number |
| `data.created_at`
string | Timestamp of the event |
| `data.content`
string | Message content |
| `data.author`
string | `"ai_assistant"`, `"visitor"`, or `"human_operator"` |
| `data.handoff_state`
string or null | Handoff state if applicable |
| `data.message_insights`
object or null | AI-generated message insights |
| `data.feedback`
object or null | User feedback on the message |
| `data.client_metadata`
object or null | Custom metadata attached to the message |
| `data.sources_generated`
array | Knowledge Base articles the AI used when generating its response |
| `data.is_welcome`
boolean | Whether this is a welcome message |
| `data.attachments`
array | File attachments |
---