Legs

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

Upgrades the HTTP request to a WebSocket and creates a websocket_in leg. Query parameters: sample_rate (8000/16000/24000/48000; default 16000); wire_format (binary default, or json_base64); sample_format (s16le only in v1); room_id to auto-add the leg to a room; app_id for event filtering; rtt=true to enable the bidirectional text channel; webhook_url/webhook_secret for per-leg event routing. X-* and P-* request headers (plus Authorization) are captured into the leg's headers map and surfaced on leg.ringing and in LegView. The leg goes straight to connected (no ringing/answer flow). Audio frames carry PCM16-LE mono at sample_rate; with wire_format=binary each WebSocket binary frame is exactly one 20ms PCM frame, with json_base64 the same payload is wrapped as {"type":"audio","audio":"<base64>"}. Text and control messages always use JSON text frames: {"type":"text","text":...}, {"type":"ping","event_id":N}/{"type":"pong","event_id":N}, and {"type":"hangup"} to terminate from the peer side.

**Actual HTTP method: CONNECT** (HTTP/3 extended-CONNECT for WebTransport). OpenAPI 3.1 does not define connect as a path-item method, so this operation is documented under post with an x-actual-method: CONNECT extension. Standard HTTP clients (e.g. curl -X POST) will receive 405 Method Not Allowed — use a WebTransport-capable HTTP/3 client.

**Experimental / PoC.** Upgrades an HTTP/3 extended-CONNECT request to a WebTransport session and creates an inbound MoQ leg. Reachable only over HTTP/3 on the MoQ listener (not on the regular HTTP/1.1 chi listener). Requires MOQ_ENABLED=true plus MOQ_TLS_CERT_FILE and MOQ_TLS_KEY_FILE. Speaks IETF draft-11 of moq-transport (via mengelbart/moqtransport); browser interop with draft-16 clients (moqtail, moq.dev) is not expected to work. Media is bidirectional within a single MoQ session per leg: the server publishes namespace mix/track audio (downlink, room mix) and subscribes to namespace mic/track audio (uplink, leg mic). Audio is Opus framed one frame per MoQ Object (LOC-style) at 48 kHz mono, 20 ms frames. Query parameters: sample_rate (only 48000 is accepted — the encoder/decoder are hard-wired to 48 kHz; default 48000); room_id to auto-add the leg to a room; app_id for event filtering; webhook_url/webhook_secret for per-leg event routing. X-* and P-* request headers (plus Authorization) are captured into the leg's headers map and surfaced on LegView. The leg goes straight to connected (no ringing/answer flow); no DTMF, no RTT, and event parity is limited to leg.connected / leg.disconnected.

Validates the leg exists and queues a hangup. The HTTP call returns 202 as soon as the leg is found; the SIP work and cleanup run in the background, and the eventual disconnection is observed via the leg.disconnected event.

Without a request body the legacy behavior is preserved: SIP BYE on connected legs (cdr.reason: "api_hangup"), or dialog cancel on unanswered inbound legs (cdr.reason: "caller_cancel").

With {"reason": "<value>"} and an unanswered SIP inbound leg (state ringing or early_media), VoiceBlender sends a final non-2xx response instead of BYE/cancel: busy→486, declined/rejected→603, unavailable→480, not_found→404, forbidden→403, server_error→500. The reason value is passed through to leg.disconnected's cdr.reason.

For connected legs the request body is ignored.

Signals the inbound-call goroutine to send 200 OK. The HTTP call returns 202 immediately; the actual SIP 200 OK is sent in the background, and the leg's transition is observed via leg.connected. Pre-condition failures (wrong state, unknown codec) still return 4xx synchronously. When the caller offers several m=audio sections they are all accepted; streams optionally routes each accepted stream beyond the primary into its own room, applied once the answer is negotiated.

Queues a SIP 180 Ringing provisional response with no SDP. Use when SIP_AUTO_RINGING=false (the default) and you want to indicate alerting before deciding to early-media or answer. Idempotent: each call emits another 180 — receivers tolerate re-sends. The HTTP call returns 202 as soon as the request is validated; SIP-level send failures surface as leg.command_failed with command="ring".

Sends a SIP 401 Unauthorized carrying a WWW-Authenticate digest challenge on an unanswered inbound INVITE. The current leg is torn down (a leg.disconnected with reason="challenged" is published); the UAC's credentialed re-INVITE arrives as a new inbound call surfaced via leg.ringing with authenticated=true once VoiceBlender verifies the response against the supplied credential. Provide either password or ha1. An invalid retry is answered with 403 Forbidden and never surfaced.

Queues a SIP 183 Session Progress with SDP and the RTP/codec setup. The HTTP call returns 202 as soon as the request is validated; the leg transitions to early_media state asynchronously, observable via leg.early_media. Setup failures surface as leg.command_failed with command="early_media".

A muted leg's audio is excluded from the room mix and speaking events are suppressed. Taps (recording/STT) still receive the muted leg's own audio.

Queues a re-INVITE with sendonly SDP direction. The HTTP call returns 202 as soon as the leg is validated; the re-INVITE is sent in the background and success surfaces as leg.hold. Failures surface as leg.command_failed with command="hold". The RTP timeout is paused while held, and a 2-hour auto-hangup timer starts.

Queues a re-INVITE with sendrecv SDP direction. The HTTP call returns 202; success surfaces as leg.unhold, failures as leg.command_failed with command="unhold".

Asynchronously transfers a SIP leg. The HTTP call returns 202 as soon as the request is validated; the REFER is sent in the background and its outcome is surfaced through leg.transfer_initiated / leg.transfer_progress / leg.transfer_completed / leg.transfer_failed events. Blind transfer when replaces_leg_id is omitted; attended transfer when present (the named leg's dialog identity is embedded as a Replaces parameter per RFC 3891). On terminal 2xx the leg (and the replaces leg, if any) is hung up automatically.

Accepts an inbound transfer surfaced via leg.transfer_requested (default app-driven model, SIP_REFER_AUTO_DIAL=false). Sends 202 Accepted to the referrer and a NOTIFY sipfrag 100 Trying, keeping the refer subscription open. {id} is the referrer leg (the leg that received the REFER). After accepting, re-bridge as needed and report progress via .../transfer/progress and the outcome via .../transfer/complete.

Sends an interim sipfrag NOTIFY (e.g. 180 Ringing) on an accepted inbound transfer so the referrer's UA reflects real progress. The subscription stays active.

Terminates an accepted inbound transfer with a final sipfrag NOTIFY and emits leg.transfer_completed (on success) or leg.transfer_failed. success:true sends 200 OK; otherwise status_code/reason (default 500) carry the failure. The referrer leg is left for the app to hang up.

Rejects a parked (not-yet-accepted) inbound transfer, replying to the referrer with a non-2xx (603 Decline by default; override via code/reason) and emitting leg.transfer_failed.

Allow this leg to receive DTMF digits broadcast from other legs in the same room. This is the default state for new legs.

Block this leg from receiving DTMF digits broadcast from other legs in the same room. DTMF received from this leg's own far end is still emitted as a leg.dtmf event.

Sends UTF-8 text on the leg's RTT (T.140 / RFC 4103) media stream. Requires that the SDP offer/answer agreed on an m=text section with the remote UA. Enable RTT on the server with RTT_ENABLED=true.

Allow this leg to receive RTT text broadcast from other legs in the same room and to emit rtt.received events for incoming text. Default state for new legs.

Block this leg from receiving RTT text broadcast from other legs in the same room and suppress rtt.received events for this leg.

Synthesizes the provided text using the configured TTS provider and plays the audio on the leg. When TTS_CACHE_ENABLED=true, identical requests (same text, voice, model, language, and prompt) are stored on disk in TTS_CACHE_DIR and persist across restarts, without calling the external provider.

Stages a speculative reply. The audio is synthesized and buffered in memory but not played, so that committing it starts playback with no synthesis delay. Intended for the turn-taking loop of a voice agent: start a draft reply on the eager_end_of_turn stt.turn event, then commit it on end_of_turn or discard it on turn_resumed. A tts.staged event reports when the audio is ready; synthesis failures are reported on tts.error. Staged utterances are dropped after TTS_PREFLIGHT_TTL or when the leg ends, and at most TTS_PREFLIGHT_MAX_PER_LEG may be staged on one leg at a time. Preflight is leg-scoped; use POST /rooms/{id}/tts for room announcements.

Starts playback of an utterance staged by the preflight endpoint. Returns immediately, before synthesis has necessarily finished; failure is reported asynchronously on tts.error, exactly as for POST /legs/{id}/tts. Once committed, stop playback with DELETE /legs/{id}/play/{playbackID} using the same tts_id.

Discards an utterance staged by the preflight endpoint, aborting synthesis if it is still in flight. Already-committed utterances are stopped with DELETE /legs/{id}/play/{playbackID} instead.

For SIP legs, recording is stereo (left=incoming, right=outgoing). For legs in a room, stereo at 16kHz (left=participant audio, right=mixed-minus-self).

Replaces incoming audio with silence on the active recording until /record/resume is called. The WAV's timeline is preserved (silent gap where audio was paused), so reviewers can see exactly when sensitive data was excluded. Idempotent: calling while already paused returns status: already_paused.

Resumes writing real audio after a prior /record/pause. Idempotent: calling while not paused returns status: not_paused.

Forces the provider to emit a final transcript for the audio buffered so far while the session keeps running, so a caller that knows the speaker has finished does not have to wait for the provider's own endpointing. Only the deepgram provider supports this; deepgram_flux, azure and elevenlabs answer 501 — /v2/listen has no flush message, and Flux reports turn ends itself on stt.turn. The flushed transcript arrives on the usual stt.text event with is_final true — a segment containing no speech produces no event at all, so do not block on one.

Bridges audio bidirectionally with an ElevenLabs conversational AI agent. Standalone legs use direct audio; legs in a room use mixer taps.

Bridges audio bidirectionally with a VAPI conversational AI agent. Standalone legs use direct audio; legs in a room use mixer taps.

Bridges audio bidirectionally with a self-hosted Pipecat bot via WebSocket. Standalone legs use direct audio; legs in a room use mixer taps.

Bridges audio bidirectionally with a Deepgram Voice Agent. Standalone legs use direct audio; legs in a room use mixer taps.

Sends a context message or instruction to the running agent. Supported by Deepgram (InjectAgentMessage), Pipecat (TextFrame), and VAPI (control URL). Returns 501 for ElevenLabs.

Returns the RFC 7865 recording metadata of an inbound SIPREC session (leg type siprec_in): every recorded participant, every negotiated media stream, and the binding between them. A stream's a=label is what ties the m= section to a participant, so the streams entries carry both the leg stream ID and the participant identity. The raw metadata document is returned verbatim in metadata.

Originates a SIPREC recording session (RFC 7866) carrying one call as two sendonly sections: what the far end says, and what this server sends them. No room is involved. leg_ids is ignored here — the two sections are fixed. Returns the resulting siprec_out leg; delete it to end the session. Requires SIPREC_SRC_ENABLED=true.

Returns every negotiated m=audio section on the leg, in m-line order. A single-stream call has exactly one entry, the primary.

Negotiates an additional m=audio section with a re-INVITE (RFC 3264 §8.1). The new section is appended below the existing ones and binds its own RTP port. Use it to carry a second independent audio stream — a translated feed, for example — alongside the original. Set content to "alt" and lang to the feed's language so the peer can tell them apart. A peer that answers the new section with port 0 leaves the call untouched and this returns 409.

Updates the stream's role in place and, when the stream is mixed into a room, recomputes that room's matrix-derived allow-sets atomically (single mixer-mutex acquisition), so no audio bleeds through mid-change. Emits leg.stream_role_changed and room.routing_changed with reason: leg_stream_role_changed.

Only the role is mutable here. The SDP-level attributes — direction, lang, content, label — are fixed when the stream is negotiated; change them by removing the stream and adding a new one.