API Overview

WebSocket overview

Connect an audio Session to your WebSocket server.
View as Markdown

A WebSocket Session is a media-only participant backed by a connection to your WebSocket server. Create one with POST /v1/sessions:connectWebsocket when your application needs to exchange live audio without creating a phone call.

When to use

Use WebSocket to connect a real-time voice application, such as a voice agent or live transcription service, to a conversation.

Use the Session in a Room

Add the WebSocket Session and one or more phone Sessions to a Room to build a bidirectional voice agent. Your server receives audio from the WebSocket Session and sends audio back through the same connection. The Room connects that media to the other participants.

Connection lifecycle

The create request returns a Session in the connecting state while the platform opens the WebSocket connection. The Session becomes answered after your server accepts the connection. If the connection fails or closes, the WebSocket Session ends.

Follow the lifecycle events on this page to observe connection success, connection failure, disconnection, and completion of buffered audio playback. Follow Session lifecycle events for the complete WebSocket Session lifecycle.

Audio format

The Session exchanges raw mono audio in binary WebSocket messages without a WAV header. The required media_format object configures each direction from the Session’s perspective:

  • from_session describes audio that the platform sends from the Session to your WebSocket server.
  • to_session describes audio that your WebSocket server sends to the Session.

Each direction independently accepts signed 16-bit little-endian PCM at a supported multiple of 8 kHz, or G.711 mu-law at 8 kHz. The two directions can use different formats. See WebSocket audio formats for the supported matrix and POST /v1/sessions:connectWebsocket for the complete request schema.

The platform exchanges raw audio only. It does not implement Twilio Media Streams JSON envelopes, base64 payloads, or control messages.

Lifecycle events

These events report the WebSocket connection owned by a type: "websocket" Session created through POST /v1/sessions:connectWebsocket. The wire event names use the websocket.* namespace.

All webhook deliveries are signed. See Verifying signatures before processing an event.

Every event contains these fields. operation_uuid is optional; all other fields are required.

FieldTypeDescription
audstringApplication UUID that identifies the intended recipient.
eventstringExact event name documented in the corresponding section.
session_uuidstringWebSocket Session identifier.
operation_uuidstringOriginating WebSocket operation identifier. Present when correlation is available.
timestampstringRFC 3339 UTC event time with a Z suffix.

websocket.connected

Fires when the WebSocket server accepts the connection. The WebSocket Session then advances from connecting to answered without emitting session.answered.

1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "websocket.connected",
4  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5  "operation_uuid": "550e8400-e29b-41d4-a716-446655440000",
6  "timestamp": "2026-08-23T08:53:20.000Z"
7}

websocket.disconnected

Fires when an established connection closes unexpectedly or the WebSocket server initiates the close. The event also contains:

FieldTypeDescription
codeintegerWebSocket close code, or 0 when unavailable.
reasonstringHuman-readable close reason, or an empty string when unavailable.
1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "websocket.disconnected",
4  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5  "operation_uuid": "550e8400-e29b-41d4-a716-446655440000",
6  "code": 1000,
7  "reason": "bye",
8  "timestamp": "2026-08-23T08:54:20.000Z"
9}

The WebSocket Session ends after this event, and a session.ended event follows.

websocket.failed

Fires when the connection cannot become usable. The event also contains:

FieldTypeDescription
errorstringSanitized category: handshake_failed or connection_failed.
http_statusintegerWebSocket handshake response status, or 0 when no response was available.
reasonstringStable reason: session_codec_unsupported, destination_unreachable, tls_failed, handshake_rejected, or connection_precondition_failed.
1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "websocket.failed",
4  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5  "operation_uuid": "550e8400-e29b-41d4-a716-446655440000",
6  "error": "handshake_failed",
7  "http_status": 403,
8  "reason": "handshake_rejected",
9  "timestamp": "2026-08-23T08:53:20.000Z"
10}

The WebSocket Session ends after this event, and a session.ended event follows.

websocket.audio_playback_completed

Fires when the platform reports that all buffered audio received from the WebSocket server has played and the buffer is idle. The event also contains:

FieldTypeDescription
played_msintegerMilliseconds of server audio reported as played, or 0 when unavailable.
1{
2  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3  "event": "websocket.audio_playback_completed",
4  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5  "operation_uuid": "550e8400-e29b-41d4-a716-446655440000",
6  "played_ms": 1840,
7  "timestamp": "2026-08-23T08:54:22.000Z"
8}

Treat this as a lifecycle signal from the platform. A successful WebSocket connection or this event alone does not prove that another participant received non-silent audio.