Chats API
The Chats API gives you programmatic access to every non-phone conversation in your echowin account — web chat, web agent, voice chat, and WhatsApp — including full transcripts. These are the same conversations you see under Chats in the dashboard. For phone calls, use the Calls API.
Rate Limits
- List Chats: 100 requests per minute
- Get Chat Details: 100 requests per minute
- Max Results Per Page: 100 conversations
Reading a subteam's conversations
Agency owners can use their agency API key to read any subteam's conversations by appending ?teamId=<subteam-team-id> to the request. Without it, the key returns its own team's conversations. See the Agency API docs for the full cross-team access model.
Table of Contents
/api/v1/chatsGet a paginated list of chat conversations for a single channel
Query Parameters
channelstring(default: web)Which channel to list: web, webagent, voice, or whatsapp
pageinteger(default: 1)Page number
limitinteger(default: 20)Number of results per page (max 100)
searchstringSearch within conversation transcripts
agentIdstringFilter by agent ID (UUID)
dateFromstringStart date for filtering (ISO 8601 format)
dateTostringEnd date for filtering (ISO 8601 format)
sortOrderstring(default: desc)Sort order by creation date: asc or desc
teamIdstringAgency keys only — scope to a subteam's conversations (UUID)
Responses
{
"data": [
{
"id": "chat-uuid-1234",
"channel": "web",
"status": "active",
"createdAt": "2024-01-15T14:30:00.000Z",
"endedAt": null,
"duration": null,
"phoneNumber": null,
"agent": {
"id": "agent-uuid-1234",
"name": "Customer Support Agent"
},
"transcript": [
{
"speaker": "user",
"text": "Do you have the XYZ product in stock?",
"timestamp": "2024-01-15T14:30:05.000Z"
},
{
"speaker": "agent",
"text": "Yes, we do! Would you like to place an order?",
"timestamp": "2024-01-15T14:30:08.000Z"
}
],
"messageCount": 2
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 42,
"totalPages": 3
}
}API Tester
/api/v1/chats/:chatIdGet detailed information about a specific conversation including full transcript and activity timeline
Path Parameters
chatIdstringrequiredThe unique identifier (UUID) of the conversation
Responses
{
"data": {
"id": "chat-uuid-1234",
"channel": "voice",
"status": "completed",
"createdAt": "2024-01-15T14:30:00.000Z",
"endedAt": "2024-01-15T14:33:20.000Z",
"duration": 200,
"phoneNumber": null,
"memory": "Customer prefers email follow-ups.",
"agent": {
"id": "agent-uuid-1234",
"name": "Customer Support Agent"
},
"transcript": [
{
"speaker": "user",
"text": "Is the XYZ product in stock?",
"timestamp": "2024-01-15T14:30:05.000Z"
},
{
"speaker": "agent",
"text": "Yes, it is. Would you like to order?",
"timestamp": "2024-01-15T14:30:08.000Z"
}
],
"activityTimeline": [
{
"id": "log-uuid-1",
"type": "RESPONSE",
"sender": "user",
"data": "Is the XYZ product in stock?",
"toolData": null,
"timestamp": "2024-01-15T14:30:05.000Z"
},
{
"id": "log-uuid-2",
"type": "TOOL_CALL",
"sender": "tool",
"data": "Looking up inventory...",
"toolData": {
"tool": "check_inventory",
"result": {
"inStock": true,
"quantity": 50
}
},
"timestamp": "2024-01-15T14:30:06.000Z"
}
],
"metadata": {}
}
}{
"error": "Chat not found"
}API Tester
Channels
web Web chat widget conversations.
webagent Web agent conversations.
voice Voice chat widget conversations — include duration and endedAt.
whatsapp WhatsApp conversations — include the contact phoneNumber.
Response Fields Reference
Conversation Object
idUnique identifier for the conversationchannelweb, webagent, voice, or whatsappdurationLength in seconds (voice only; null otherwise)phoneNumberContact phone number (whatsapp only; null otherwise)messageCountNumber of transcript messagesTranscript Entry
speaker"user" or "agent"textThe message texttimestampWhen this was sent (ISO 8601)