Trillet AI logo

Connect a Web Call

Initiate a live web-based call session with an AI agent.

POSThttps://api.trillet.ai/v1/api/calls/web/connect

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-idstringrequired

Workspace identifier for the API.

Request Body

agentIdstringrequired

The ID of the agent that will handle this web call. The agent's call flow must be live.

modestring

The mode of the call. Defaults to voice.

dynamic_variablesobject

Values for {{variable}} placeholders in the call flow, as a flat object of strings.

initial_modalitystring

The modality the session starts in.

pathwayIdstring

A call flow ID. When that call flow has an active draft, the call tests the draft's settings instead of the published ones.

test_directionstring

inbound or outbound: which greeting to play. Defaults to the call flow's inbound greeting, or outbound for an outbound-only call flow.

Response Fields

statusstring

success.

callIdstring

A 10-character ID for this call.

callHistoryIdstring | null

The Call History record for this call. Use it with Get a Specific Call History.

roomNamestring

The LiveKit room, web-<agentId>-<callId>. Send it to Disconnect a Web Call to end the call.

tokenstring

The LiveKit access token for the room.

connectionobject

url (the LiveKit server to connect to) and token (the same as token above).

agentobject

id, name, model (the agent's LLM settings) and voice (the agent's voice settings).

Errors

StatusBodyWhen
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