Overview
The Conversations API provides endpoints for managing and retrieving conversation data from AI agents.Authentication
All conversation endpoints require authentication using a Bearer token:Get Conversations
Retrieve a paginated list of conversations for an organization.Endpoint
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | number | No | 1 | Page number for pagination |
limit | number | No | 20 | Number of items per page (max: 100) |
search | string | No | - | Search term to filter conversations |
agent_config_id | string | No | - | Filter by specific agent configuration ID |
start_date | string | No | - | Filter conversations created on or after this date |
end_date | string | No | - | Filter conversations created on or before this date |
product_id | string | No | - | Filter by specific product ID |
include_admin | boolean | No | false | Include admin conversations in results |
Response Structure
The response includes a list of conversations with pagination metadata:-
conversations: Array of conversation objects containing:
- id, summary, duration_seconds, agent_name, agent_config_id
- created_at, status, end_user_email, end_user_identifier
- provider_conversation_id, processing_type, type
- rating, feedback, isAdmin
-
pagination: Object containing:
- page, limit, total, hasMore
Example Request
Get Conversation by ID
Retrieve detailed information about a specific conversation.Endpoint
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The conversation ID |
Response Structure
The response includes detailed conversation information:- Conversation fields: id, audio_url, agent_config_id, end_user_id
- Analysis data: provider_conversation_id, analysis object, conversation_duration_secs
- Status fields: status, processing_type, type
- Timestamps: created_at, updated_at
- Feedback: rating, feedback, isAdmin
- Related data: agent_config (id, name, description), end_user (id, email, identifier)
Example Request
Date Filtering
The start_date and end_date parameters filter conversations based on their created_at timestamp:- start_date: Returns conversations created on or after this date
- end_date: Returns conversations created on or before this date
Error Responses
| Status Code | Description |
|---|---|
400 | Bad Request - Missing required parameters |
404 | Not Found - Resource not found |
500 | Internal Server Error |