Voice Platform APISessions

Create a standalone session

View as Markdown
Create a [standalone session](/api/sessions) that has no phone leg and exists only to bridge audio to an external WebSocket backend. Only `type: "websocket"` is supported. The session is born `connecting`; once the backend WebSocket is established it advances to `answered`. Its lifetime is bound to that WebSocket — when the backend disconnects (or never connects within the connect timeout) the session ends and a `session.ended` webhook is emitted. **Triggered webhooks:** `websocket.connected`, `websocket.disconnected`, `websocket.failed`, `session.ended`

Authentication

AuthorizationBearer
Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>`. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]+$"<=128 characters
Optional client-generated key for a mutating endpoint. It identifies one method, route, query, content type, and exact raw body within the authenticated app. Reusing it for a different request returns 422. While its record exists, a retry replays the original accepted response when available. Keys are valid for 1 hour. Allowed characters: letters, digits, dot, hyphen, underscore; max 128 characters. See the Idempotency guide.

Request

This endpoint expects an object.
typeenumRequired

Session type to create. Only websocket is supported.

Allowed values:
websocketobjectRequired

WebSocket audio relay configuration. Shared by the ws/start command and the ws block of POST /v1/sessions.

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
Opaque session identifier. Return it to the API exactly as received.
stateenum

Current lifecycle state of the session. connecting applies to a websocket session whose backend WebSocket has not yet connected.

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
  • webrtc: a WebRTC client
  • websocket: a standalone WebSocket session with no phone leg
  • unknown: could not be determined
caller_idstringOptional

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

didstringOptional

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

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden 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