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.
fromPhoneNumberstringOptional

Optional caller ID. Omit to start like a browser web call. Uses the agent’s attached number if present, otherwise the web-call placeholder +17088888888.

toPhoneNumberstringOptional

Optional lead/destination number. Omit to use the same web-call placeholder as when the agent has no attached 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.

sidstringOptional

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