Skip to main content
POST
Create realtime session
Use this endpoint from your backend. It returns { url, token } for the browser SDK. Never put your API key in frontend code.
Rate limited to 10 requests per minute per authenticated user.Concurrent cap of 10 sessions per account. Unused tokens count toward this cap until they expire (15 minutes). In-progress website-widget voice sessions on the same account also count.
The token expires after 15 minutes. Start the browser session before it expires. Minting a token does not create a Call History row. A row appears only after the browser connects and the session actually starts. Unused tokens leave no call record.

Request body

string
required
The assistant UUID. Use the uuid field from Get Assistants, not the numeric id.
object
Optional context variables passed into the assistant (prompt variables). Keys and scalar values only. Maximum 50 keys.
string
Optional CRM or customer id. Passed through as a variable when not already set.Maximum length: 255 characters.

Response

string
Session id (UUID). Useful for your own logging.
string
Media server URL. Pass this to the browser SDK. Do not expose it in a public repo or log it in client analytics.
string
Short-lived session token. Treat it like a password. Pass it to the browser SDK only.
number
Token lifetime in seconds. Currently 900 (15 minutes).

Browser SDK

Install @voice-session/web and pass url and token from this response. Do not send the API key to the browser.
See Realtime voice SDK for events and a full example.

Example

Error responses

boolean
false when the request fails
string
Human-readable error message
string
One of ASSISTANT_NOT_FOUND, ASSISTANT_BLOCKED, INSUFFICIENT_BALANCE, CONCURRENT_LIMIT, CONNECTION_FAILED