TelephonyOutbound Calls

Create Outbound Call

Place an outbound call from an agent to a phone number. LiveKit originates the SIP INVITE through the outbound trunk bound to the agent's workspace; the agent worker is dispatched into the room automatically. The response is returned as soon as LiveKit accepts the INVITE. Poll `GET /v1/agents/conversations/{conversation_id}` for status transitions: `pending` → `active` (answered) → `completed`. Requires a Twilio or BYOC trunk. LiveKit-native numbers are inbound-only.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.
agent_idstringRequired
ID of the agent that handles the answered call.
tostringRequired

Destination phone number in E.164 format (e.g. +12025559876).

caller_id_numberstringOptional

The number shown to the callee as caller ID, in E.164 format. Defaults to the first outbound-capable number in the workspace. Useful for multi-number campaigns where you want to rotate caller IDs.

dtmf_prefixstringOptional

DTMF digits dialed automatically after the call is answered, before the agent begins speaking. Use this for IVR navigation (e.g. 1ww2 presses 1, waits two seconds, presses 2). w is a half-second pause; W is a one-second pause.

dynamic_variablesmap from strings to anyOptional

Per-call variable overrides merged on top of the agent’s stored defaults. Keys must not use the reserved system__ prefix. Useful for injecting per-call context (customer name, order ID) into the agent prompt.

ringing_timeout_msintegerOptional

How long to wait for the callee to answer before abandoning, in milliseconds. Defaults to 30000 (30s). Capped at 80000 (80s).

amdobjectOptional

Optional per-call override for the AMD routing config. When set, wholesale-replaces the agent’s stored AMD shape for this single call (PATCH-replace, not merge). Unlocks the batch-campaign pattern: one agent dialling many recipients with per-row tailored voicemail messages via the existing dynamic_variables substitution. Validation rules match the agent-update boundary.

Response

The outbound call was accepted by LiveKit.
conversation_idstring
ID of the conversation created for this call. Use to poll status.
roomstring
LiveKit room name the answered call joins.
sip_participant_idstring
LiveKit participant ID for the outbound SIP call leg.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error