Skip to navigation
API OverviewWebSocket

Create a WebSocket session

View as Markdown

Create a WebSocket session with no phone leg. The session acts as an independent participant and exchanges audio with the configured external WebSocket server. Only type: "websocket" is supported.

The session starts in the connecting state. After the WebSocket connection is established, the session advances to answered. Its lifetime is bound to that connection. If the server disconnects or does not connect before the timeout, the session ends and a session.ended webhook is emitted.

You can add or remove the session from rooms and use all supported session commands. Closing the WebSocket ends the session. This endpoint creates a new session.

Triggered webhooks: websocket.connected, websocket.disconnected, websocket.failed, websocket.audio_playback_completed, session.ended

See WebSocket lifecycle events for complete payload schemas and examples.

See Session lifecycle events for complete payload schemas and examples.

Authentication

AuthorizationBearer

Send Authorization: Bearer <app_uuid>:<api_key> using an active API key. See Authentication for details.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]*$"<=128 characters

Optional key for safely retrying mutating requests. An explicitly empty header is treated like omission and does not enable replay protection. See Idempotency for details.

Request

This endpoint expects an object.
typeenumRequired

Session type to create. Only websocket is supported.

Allowed values:
websocketobjectRequired

WebSocket audio connection configuration. Audio in both directions is raw mono PCM16 or G.711 mu-law, independently selected, and carried in binary WebSocket frames. Do not include a WAV header.

Response headers

traceparentstringOptionalformat: "^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$"=55 characters

Server-owned W3C Trace Context for correlating this response with support and observability data. It is present on successful and error responses. A valid incoming traceparent is linked to, but never becomes, the server-owned trace identifier.

Response

Session created. Born in the connecting state.

created_atdatetime

When the session was created, as an RFC 3339 / ISO 8601 UTC string (e.g. “2025-05-06T12:41:36.000Z”). Storage resolution is one second, so the millisecond fraction is always .000. Empty string if the originating timestamp is missing or unparseable.

session_uuidstring
Session identifier.
stateenum

Current lifecycle state of the session. connecting applies to a websocket session whose WebSocket server connection has not yet been established.

typeenum

The nature of the session:

  • phone_in: inbound phone call from a carrier
  • phone_out: outbound phone call placed with dial
  • sip: a registered SIP device
  • websocket: a WebSocket session with no phone leg
  • unknown: could not be determined or is not a supported public session type
Allowed values:
caller_idstringOptional

Caller ID in canonical international E.164 format with leading + (e.g. +972500000000). Empty for websocket sessions (no phone leg).

didstringOptional

Called DID in canonical E.164 format with leading + (e.g. +972740000000). Empty for websocket sessions (no phone leg).

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
406
Not Acceptable Error
409
Conflict Error
413
Content Too Large Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error