Skip to main content

​
Concept

Chats is the group of endpoints focused on real-time human support operations — what happens when a human agent takes over a conversation that was being managed by AI. While the Conversations group provides a complete view of history (reading, searching, analysis), the Chats group is action-oriented: sending messages on behalf of a human agent, starting and stopping human mode, and deleting messages from active chats. The practical difference: use Conversations to access and analyze historical data; use Chats when you are building a real-time human support interface — such as a custom inbox, a support panel, or an integration with a help desk system.

​
Handoff: How It Works

When a human agent needs to take over a conversation from the AI: 
1. POST /v1/chats/{id}/start-human
   → conversation status changes to "human"
   → AI agent stops responding automatically
   → "agent.handoff_started" webhook is fired

2. Agent replies via POST /v1/chats/{id}/messages
   → message appears to the customer through the original channel

3. POST /v1/chats/{id}/stop-human
   → status returns to "open"
   → AI agent resumes control
   → "agent.handoff_completed" webhook is fired

​
Main Chat Fields

FieldTypeDescription
idstring (UUID)Chat ID (same as conversation_id)
statusenumopen | human | closed
assigned_tostring (UUID)ID of the active human agent
human_started_atstringISO 8601 handoff start timestamp
channel_idstring (UUID)Channel through which messages are sent
contact_idstring (UUID)Contact being attended to

​
Chat Message Fields

FieldTypeDescription
idstring (UUID)Message ID
conversation_idstring (UUID)Conversation it belongs to
contentstringText content
typeenumtext | image | audio | video | document
sender_typeenumagent (AI) | human | contact
sender_idstring (UUID)ID of the human or agent sender
statusenumsent | delivered | read | failed
created_atstringISO 8601 send timestamp

​
Available Endpoints

See the left sidebar for the full list of endpoints in this group. Each endpoint has its own page with request/response schema, cURL/JS/Python examples, and an interactive playground.

​
Next Steps

Your first request

If you haven’t made your first call yet, start here.