VOvoiceblender
Legs

Originate an outbound leg

Changed on

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. trunk_id places a sip leg through a specific SIP trunk; it takes precedence over selecting a trunk by matching from against trunk AORs.

post/legs

Request

  • Base URL
    http://localhost:8080/v1
  • URL
    http://localhost:8080/v1/legs
  • Auth
    none declared

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.

trunk_idstring

ID of the SIP trunk (POST /v1/sip/trunks) to place this call through. The trunk supplies the route to its upstream, its digest credentials and, unless "from" names a host, the From realm; when "from" is omitted the trunk's AOR is used. Takes precedence over selecting a trunk by matching "from" against trunk AORs. An unknown ID is rejected with 404. SIP legs only.

privacystring

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

ring_timeoutinteger

Seconds to wait for answer (sip) or for the handshake (websocket) before the leg is ended with reason ring_timeout. Defaults to 60 when omitted; 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.

custom_dataunknown
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)

type'sip_inbound' | 'sip_outbound' | 'webrtc' | 'whatsapp_in' | 'whatsapp_out' | 'websocket_in' | 'websocket_out' | 'moq_in' | 'livekit_publish' | 'livekit_participant' required

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-/P- 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. On an inbound INVITE the prefix is matched in any case and names are reported as received.

custom_dataunknown

Changes