Connect a Web Call
Initiate a live web-based call session with an AI agent.
Initiate a web call that runs entirely via WebRTC in the browser (no phone number required). The response carries the LiveKit URL and token your client uses to join the call.
Authenticate with your API key (x-api-key) or a dashboard session token, and call it from your server.
The workspace's wallet is checked first: a spent balance returns 400 with code INSUFFICIENT_FUNDS.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Request Body
agentIdstringrequiredThe ID of the agent that will handle this web call. The agent's call flow must be live.
modestringThe mode of the call. Defaults to voice.
dynamic_variablesobjectValues for {{variable}} placeholders in the call flow, as a flat object of strings.
initial_modalitystringThe modality the session starts in.
pathwayIdstringA call flow ID. When that call flow has an active draft, the call tests the draft's settings instead of the published ones.
test_directionstringinbound or outbound: which greeting to play. Defaults to the call flow's inbound greeting, or outbound for an outbound-only call flow.
Response Fields
statusstringsuccess.
callIdstringA 10-character ID for this call.
callHistoryIdstring | nullThe Call History record for this call. Use it with Get a Specific Call History.
roomNamestringThe LiveKit room, web-<agentId>-<callId>. Send it to Disconnect a Web Call to end the call.
tokenstringThe LiveKit access token for the room.
connectionobjecturl (the LiveKit server to connect to) and token (the same as token above).
agentobjectid, name, model (the agent's LLM settings) and voice (the agent's voice settings).
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "x-workspace-id header is required"} | No x-workspace-id |
400 | {"code", "error", "message", "fix"} | The agent has no live call flow. code says why, for example FLOW_ARCHIVED or FLOW_INACTIVE |
400 | {"error": "Agent must have a phone number configured to use transfers"} | The call flow has transfers but the agent has no number |
400 | {"error": "Insufficient funds", "code": "INSUFFICIENT_FUNDS", ...} | The wallet balance is spent |
401 | {"error": "..."} | Missing or invalid credentials |
404 | {"error": "Agent not found or unauthorized"} | No agent with that ID in this workspace |
500 | {"error": "Failed to initiate web call", "details", "requestId"} | Server error |
{
"status": "success",
"callId": "k3j9x0a1bq",
"callHistoryId": "a2a2a2a2a2a2a2a2a2a2a2a2",
"roomName": "web-a5a5a5a5a5a5a5a5a5a5a5a5-k3j9x0a1bq",
"token": "<LIVEKIT_TOKEN>",
"connection": {
"url": "wss://livekit.example.com",
"token": "<LIVEKIT_TOKEN>"
},
"agent": {
"id": "a5a5a5a5a5a5a5a5a5a5a5a5",
"name": "Front Desk",
"model": { "provider": "openai", "model": "gpt-4.1-mini" },
"voice": { "provider": "cartesia", "voiceId": "a0e99841-438c-4a64-b679-ae501e7d6091" }
}
}Last updated on