PLATFORM APICalls

Start a WebSocket media call

View as Markdown

Starts an outbound test call and returns a short-lived WebSocket URL for streaming call audio.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
modelIdstringRequiredformat: "uuid"
Agent model UUID.
fromPhoneNumberstringRequired
Caller ID for the test call.
toPhoneNumberstringRequired
Destination phone number.
leadNamestringOptional
Lead display name.
agentVersionstringOptional

Agent version to use. Set to draft to test the draft version, pass a version UUID, or omit for the live version.

wsMediaCodecenumOptionalDefaults to opus

Codec to use for the WebSocket media stream. l16 is raw big-endian 16-bit PCM at 16 kHz.

Allowed values:
wsMediaFramingenumOptionalDefaults to rtp
Wire format for the WebSocket media stream. `rtp` (default) sends full RTP packets; `payload` sends raw codec payloads (RTP header stripped), which is simpler for external AI/STT/TTS clients. Use `payload` with `pcma`/`pcmu` — avoid `payload` with `opus` (see the integration guide for why).
Allowed values:
wsMediaServerNamestringOptionalDefaults to

Media node the client reached, taken from the server-name in the server_info message. Provide it to start the call on that exact node and receive a sid to bind over the open WebSocket (connect-then-bind). Omit it only for the legacy single-node flow that returns a ready-to-use wsMediaUrl.

Response

WebSocket media call created.
callIdstring
Call ID for looking up the call later.
wsMediaUrlstringformat: "uri"

Short-lived WebSocket URL with the session id attached. Used directly by the legacy single-node flow; connect-then-bind clients ignore it and bind sid over the base URL connection instead.

sidstring

Session id for connect-then-bind. Returned when wsMediaServerName is set; send it as { "type": "bind", "sid": "..." } over the WebSocket you already opened to attach your connection to the call. Empty for the legacy single-node flow.

Errors

400
Bad Request Error
401
Unauthorized Error
502
Bad Gateway Error
503
Service Unavailable Error