Legs

Originate an outbound leg

Originate a new outbound leg. The type field selects the transport: sip originates a SIP INVITE; whatsapp originates a WhatsApp call through Meta; websocket dials a remote WebSocket endpoint (audio is PCM in either binary or json_base64 framing, with bidirectional text and caller-supplied X-/P- headers). For sip legs, outbound_proxy sets the next hop for this INVITE as a loose Route header, leaving the Request-URI unchanged. It outranks the matched trunk's outbound_proxy and SIP_OUTBOUND_PROXY; a to that resolves to an AOR registered to this server outranks all three and is delivered to the bound contact.

post/legs

Request body

type'sip' | 'whatsapp' | 'websocket' | 'livekit_room' required

Leg type

tostring

Destination. For sip legs, a SIP URI (e.g. "sip:alice@example.com"); a "sips:" URI or a ";transport=tls" param sends the INVITE over TLS, and ";transport=tcp" over TCP. For whatsapp legs, an E.164 phone number (with or without '+').

uristring

Deprecated alias for to (sip legs only). Prefer to.

fromstring

Caller ID. A bare user-part (e.g. "+15551234567", "alice") sets the user of the SIP From header. A full SIP URI (e.g. "sip:alice@pbx.example.com") sets both the user and the host; otherwise the host comes from the matched trunk's AOR realm, falling back to SIP_DOMAIN.

outbound_proxystring

Next-hop SIP proxy for this INVITE, attached as a loose "Route" header (the Request-URI is left unchanged). Overrides the matched trunk's outbound_proxy and SIP_OUTBOUND_PROXY. Ignored when "to" resolves to an AOR registered to this server, which is delivered to the registered contact instead. SIP legs only.

privacystring

SIP Privacy header value (e.g. "id", "none")

ring_timeoutinteger

Seconds to wait for answer; 0 = no timeout

max_durationinteger

Maximum call duration in seconds after connect. Automatically hung up when reached. 0 or omitted = no limit.

codecsstring[]

Codec preference order (sip legs only)

headersobject

Custom headers to include in the outbound INVITE (sip/whatsapp) or the WebSocket upgrade request (websocket)

room_idstring

Room ID to auto-add the leg to once media is ready (early_media or connected). If the room does not exist, it is automatically created.

webhook_urlstring uri

Route all events for this leg exclusively to this URL instead of global webhooks.

webhook_secretstring

HMAC-SHA256 signing secret for the per-leg webhook.

accept_dtmfboolean

If false, this leg will not receive DTMF digits broadcast from other legs in the same room. Defaults to true.

app_idstring

Application identifier. Carried through to all events for this leg. Use to filter the WebSocket event stream by app.

speech_detectionboolean

If true, emit speaking.started and speaking.stopped events for this leg. If false, suppress them. Omit to use the server default (SPEECH_DETECTION_ENABLED env var, default false).

rttboolean

For sip legs: offer Real-Time Text (ITU-T T.140 over RTP per RFC 4103) alongside audio. For websocket legs: enable the bidirectional text-message channel. Default: false.

{"stackTrail":"components:schemas:CreateLegRequest:properties:custom_data","oasType":"schema","type":"unknown","description":"Opaque application JSON attached to the leg. Any JSON value is accepted (object, array, string, number, boolean). It is echoed on the leg view and carried at the top level of every event published for this leg, so external state can be correlated without keeping a leg_id lookup table. Capped by CUSTOM_DATA_MAX_BYTES (default 1024 bytes, 0 = unlimited)."}

urlstring uri

WebSocket target URL (ws:// or wss://) for outbound websocket legs. Required when type=websocket.

sample_rateinteger

PCM sample rate for websocket legs. The room's mixer automatically resamples between this and the room rate.

wire_format'binary' | 'json_base64'

Audio framing for websocket legs. binary ships raw PCM as WebSocket binary frames; json_base64 wraps PCM as {"type":"audio","audio":"<base64>"} text frames (browser-friendly).

sample_format's16le'

On-the-wire PCM sample encoding for websocket legs. v1 only supports s16le.

Response

Leg created

instance_idstring

Instance identifier

idstring required

Unique leg identifier (UUID)

Leg type

state'ringing' | 'early_media' | 'connected' | 'held' | 'hung_up' required

Leg state

room_idstring

Room ID if the leg is in a room, empty otherwise

mutedboolean required

Whether the leg is muted (cannot be heard by others)

deafboolean required

Whether the leg is deaf (cannot hear others)

accept_dtmfboolean required

Whether the leg receives DTMF digits broadcast from other legs in the same room. Defaults to true.

heldboolean required

Whether the call is on hold (SIP legs only)

rolestring

Routing role used by the room's audio routing matrix (e.g. "customer", "agent", "supervisor"). Empty string means unroled (full mesh).

app_idstring

Application identifier for event stream filtering.

sip_headersobject

Deprecated: X-* headers from the inbound INVITE. Only present on sip_inbound legs. Use headers for new code; it carries the same map plus surfaces handshake headers for websocket legs.

headersobject

Custom protocol headers exposed by the leg's transport — X-/P- headers from a SIP INVITE, the WebSocket upgrade request, or supplied at outbound dial time.

{"stackTrail":"components:schemas:Leg:properties:custom_data","oasType":"schema","type":"unknown","description":"Opaque application JSON attached to the leg. Any JSON value is accepted (object, array, string, number, boolean). It is echoed on the leg view and carried at the top level of every event published for this leg, so external state can be correlated without keeping a leg_id lookup table. Capped by CUSTOM_DATA_MAX_BYTES (default 1024 bytes, 0 = unlimited)."}

Changes

Changed in 18 of the 67 revisions of this API.162442

Sep 1, 202689ff267f09582See the full diff
- ○
  added the new optional request property custom_data
  new-optional-request-property
- ○
  added the optional property custom_data to the response with the 201 status
  response-optional-property-added
Aug 17, 20264efc843fe56f1See the full diff
- ○
  added the new optional request property outbound_proxy
  new-optional-request-property
Aug 4, 20269b0a18aea1e21See the full diff
- ○
  added the new optional request property streams
  new-optional-request-property
Jun 15, 202641268cfc61431See the full diff
- ○
  added the new AMR-NB enum value to the request property codecs/items/
  request-property-enum-value-added
Jun 12, 2026dee6706a77301See the full diff
- ○
  added the new AMR-WB enum value to the request property codecs/items/
  request-property-enum-value-added
Jun 8, 20262c525610823432See the full diff
- ●
  added the new livekit_participant enum value to the type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new livekit_publish enum value to the type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new moq_in enum value to the type response property for the response status 201
  response-property-enum-value-added
- ○
  added the new optional request property livekit
  new-optional-request-property
- ○
  added the new livekit_room enum value to the request property type
  request-property-enum-value-added
May 21, 202698f1f6130e2c1See the full diff
- ○
  added the optional property role to the response with the 201 status
  response-optional-property-added
May 13, 202697117ab6a5c426See the full diff
- ●
  added the new websocket_in enum value to the type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new websocket_out enum value to the type response property for the response status 201
  response-property-enum-value-added
- ○
  added the new optional request property sample_format
  new-optional-request-property
- ○
  added the new optional request property sample_rate
  new-optional-request-property
- ○
  added the new optional request property url
  new-optional-request-property
- ○
  added the new optional request property wire_format
  new-optional-request-property
- ○
  added the new websocket enum value to the request property type
  request-property-enum-value-added
- ○
  added the optional property headers to the response with the 201 status
  response-optional-property-added
May 11, 20267ab34b92424f1See the full diff
- ○
  added the new optional request property rtt
  new-optional-request-property
Apr 29, 20266a046e0fe81524See the full diff
- ●
  added the new whatsapp_in enum value to the type response property for the response status 201
  response-property-enum-value-added
- ●
  added the new whatsapp_out enum value to the type response property for the response status 201
  response-property-enum-value-added
- ○
  added the new optional request property to
  new-optional-request-property
- ○
  the request property auth/allOf[SIPAuth]/username became optional
  request-property-became-optional
- ○
  the request property uri became optional
  request-property-became-optional
- ○
  added the new whatsapp enum value to the request property type
  request-property-enum-value-added

Full history (18 revisions)