Sign in
Legs

Change a leg's routing role

Updates the leg's routing role and, if the leg is currently in a room, recomputes the room's matrix-derived allow-sets atomically (single mixer-mutex acquisition). The next mix tick (≤ 20 ms) reflects the change.

patch/legs/{id}/role

Request body

rolestring required

New routing role for the leg. The room's routing matrix decides which other legs this leg hears and is heard by based on roles. Pass an empty string to clear the role (full mesh).

Response

Updated leg view

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-* 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 4 of the 67 revisions of this API.132

  • 89ff267f09581See the full diff
    • ○

      added the optional property custom_data to the response with the 200 status

      response-optional-property-added

  • 2c52561082343See the full diff
    • ●

      added the new livekit_participant enum value to the type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new livekit_publish enum value to the type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new moq_in enum value to the type response property for the response status 200

      response-property-enum-value-added

  • 98f1f6130e2c1See the full diff
    • ○

      endpoint added

      endpoint-added

  • d09c97c6ca8c1See the full diff
    • ▲

      api path removed without deprecation

      api-path-removed-without-deprecation

    This revision also has 40 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog