Skip to main content
Starts a voice conversation (modality: voice) or chat (modality: chat) with this Roark-hosted agent and returns its id right away. channel: web is a conversation in a browser on your site. Call this endpoint from your server, never the browser: it needs your API key. Give the page only web.clientToken; the web SDK spends it to join from one of allowedOrigins before web.clientTokenExpiresAt. Read it back with GET /v1/conversation/{conversationId} straight away: PENDING until the browser joins, IN_PROGRESS, then ENDED. One nobody joins ends without ever starting and is never billed. Starting a voice conversation needs call:create, a chat chat:create, and the agent a published version that takes that kind.
Calls POST /v1/agent/{agentId}/conversations

​
Arguments

​
string
required
The agent-id.

​
Options

​
string
required
voice or chat. The agent must have that modality turned on. One of voice, chat, call
​
string
required
How it is reached. web: in a browser on one of allowedOrigins, joined with the web SDK. One of web
​
array
required
The origins your page may join from, exactly as the browser sends them: https only (http on localhost for development), no paths or wildcards. Repeatable.
​
integer
How long the browser has to join, in seconds. Default 120.

​
Example

Every command also takes the global options and sets one of the exit codes.