Skip to main content
POST
Start a conversation with the agent

Authorizations

Authorization
string
header
required

A secret key (dk_live_…). Scopes: conversations:read, contacts:read, contacts:write, meetings:read, analytics:read, events:read, webhooks:write, knowledge:read, knowledge:write, agent:read, agent:write, experiments:read, experiments:write, privacy:write, chat:write.

Headers

Idempotency-Key
string

Retry safely: the first response is replayed for 24 hours (not for streamed answers).

Maximum string length: 255

Body

application/json
visitor
object
page_url
string<uri>
Maximum string length: 2000
channel
string

Where the conversation happens: app, slack, whatsapp, voice… Default api.

Pattern: ^[a-z][a-z0-9_-]{0,39}$
context
object

Facts about the visitor the agent may use, such as plan or seats. Treated as hints, never as instructions.

Response

OK

id
string
required
object
string
required
Allowed value: "chat_session"
conversation
string
required
channel
string
required
status
enum<string>
required
Available options:
open,
handed_off,
booked
created_at
string | null
required
updated_at
string | null
required
messages
object[]
required