Realtime API
Create Realtime Call
The first step of a Realtime API call: creates the call and returns the WebSocket url, a single-use ticket valid 60 seconds, and the audio format.
POST
Requires the
pearls:websocket scope. Then open url?ticket=<ticket> within 60 seconds: Stream Call describes the connection, the audio and the events.
Path parameters
string
required
Your Pearl’s id. It must be an active voice Pearl. Find it on your Pearl’s overview page, in the Settings popover.
Body
string
required
Your own id for the person on the call, such as a customer id, an e-mail or a phone number (1 to 200 characters). A Realtime API call has no phone number, so this takes its place: in the call history, in your Pearl’s memory, and in the flow’s Phone Number variable. Send the same value for the same person every time, and never one value for different people; if you have no id for the person, send a session id.
object
The flow’s pre-call variables, by variable name: the same dictionary as a phone call’s
callData.Required entries: every variable used in the opening sentence, and every input of a pre-call API, present and not blank. Other variables are optional.Keys are letters (any script), digits, _ and -, up to 40 characters. Values are strings, up to 200 characters.string
default:"ulaw_8000"
The audio format of the call, the same in both directions:
ulaw_8000: 8 kHz G.711 μ-law, phone quality.pcm_24000: 24 kHz 16-bit little-endian PCM, HD.
null or empty means ulaw_8000, and any other value is refused.Response
string
The WebSocket URL. Open it with the ticket:
url?ticket=<ticket>. Always use the returned value rather than a fixed address.string
The single-use ticket for the connection, starting with
wct_. It is valid for 60 seconds and is consumed by the first successful connection. Treat it as a secret.string
When the ticket stops being accepted, in ISO 8601 UTC: creation plus 60 seconds.
object
The format of every audio frame, in both directions.
Errors
A
400 lists its messages in errors.validation. Several callData problems are reported together.
Two cases answer with a
title and a detail instead:
Malformed JSON, a field of the wrong type (a number as
audioFormat, for example) or a missing or blank endUserId get the standard 400, with the error under the field name: The EndUserId field is required. for endUserId.
A successful create reserves one of your Pearl’s agents until the call ends. A call that is never connected keeps it for about 90 seconds and costs nothing. There is no endpoint to cancel a created call.A create refused with
No agent is available… or Could not start the call. still appears in the call history, as a call that never started.