Create a sidecar WebSocket audio relay | Voice Platform

Attach a live, bidirectional sidecar audio relay between this session and an external WebSocket server. Audio streams both ways for the life of the relay.

The relay is a singleton subresource: only one may exist per session. Creating a second returns 409. After a websocket_relay.disconnected or websocket_relay.failed event the session is free again: retrying this request creates a fresh relay, replacing any remnant of the previous one.

Asynchronous operation; outcomes arrive as websocket_relay.* webhook events. For per-call relays, those events include this create request’s operation_uuid when correlation is available.

Use this endpoint when your WebSocket server should observe or participate in one existing call. It creates a sidecar relay attached to that call. If your server should instead be an independent participant, create a standalone WebSocket session.

Triggered webhooks: websocket_relay.connected, websocket_relay.disconnected, websocket_relay.failed, websocket_relay.message_received, websocket_relay.audio_playback_completed

Attach a live, bidirectional sidecar audio relay between this session and an external WebSocket server. Audio streams both ways for the life of the relay. The relay is a singleton subresource: only one may exist per session. Creating a second returns `409`. After a `websocket_relay.disconnected` or `websocket_relay.failed` event the session is free again: retrying this request creates a fresh relay, replacing any remnant of the previous one. Asynchronous operation; outcomes arrive as `websocket_relay.*` webhook events. For per-call relays, those events include this create request's `operation_uuid` when correlation is available. <Tip>Use this endpoint when your WebSocket server should observe or participate in one existing call. It creates a sidecar relay attached to that call. If your server should instead be an independent participant, [create a standalone WebSocket session](api:voice-api:POST/v1/sessions:connectWebsocket).</Tip> **Triggered webhooks:** `websocket_relay.connected`, `websocket_relay.disconnected`, `websocket_relay.failed`, `websocket_relay.message_received`, `websocket_relay.audio_playback_completed`

Authentication

AuthorizationBearer

Application auth. Send Authorization: Bearer <app_uuid>:<api_key> using any active key in the app’s collection. See Authentication for details.

Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>` using any active key in the app's collection. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.

Path parameters

uuidstringRequired

Session identifier.

Request

WebSocket audio relay configuration. Shared by POST /v1/sessions/{uuid}/websocket-relay and the websocket block of POST /v1/sessions:connectWebsocket. Audio in both directions is raw signed 16-bit linear PCM, little-endian and mono, carried in binary WebSocket frames. Do not include a WAV header.

media_formatobjectRequired

Audio formats in both directions. from_session is audio sent from the session to the WebSocket server; to_session is audio sent from the WebSocket server to the session.

urlstringRequiredformat: "uri"<=4096 characters

WebSocket relay URL. Both ws:// and wss:// URLs are accepted. The host must resolve to a permitted public address.

operation_uuidstringOptionalformat: "uuid"

Optional command correlation UUID. Reuse it within 10 minutes only when retrying the same pause, resume, or relative-seek admission; reuse for a different command is rejected. It is not a general idempotency key or a resource name.

connection_headersmap from strings to stringsOptional

Customer-controlled HTTP header name→value map sent when opening the connection to the WebSocket server (e.g. auth). The platform owns User-Agent, Origin, Host, Connection, Upgrade, Sec-WebSocket-, Content-Length, Transfer-Encoding, Proxy-, Forwarded, X-Forwarded-*, X-Real-IP, and CF-Connecting-IP. The platform sets User-Agent and derives Origin from the target URL. Header names must be valid HTTP field names; bounded count and total size; values may not contain line breaks.

Customer-controlled HTTP header name→value map sent when opening the connection to the WebSocket server (e.g. auth). The platform owns User-Agent, Origin, Host, Connection, Upgrade, Sec-WebSocket-*, Content-Length, Transfer-Encoding, Proxy-*, Forwarded, X-Forwarded-*, X-Real-IP, and CF-Connecting-IP. The platform sets User-Agent and derives Origin from the target URL. Header names must be valid HTTP field names; bounded count and total size; values may not contain line breaks.

start_mutedbooleanOptionalDefaults to false

If true, the user’s audio is not sent to the WebSocket server until websocket-relay/unmute.

Response

Command accepted for async execution

operation_uuidstringformat: "uuid"

statusenum

already_endedtrueOptional

Optional. Set to true on idempotent terminal commands when the session was already in a terminal state at the time the request was received. Absent otherwise.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

409

Conflict Error

413

Content Too Large Error

415

Unsupported Media Type Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error