How it works
1
Start the call
POST /voice/live/start reserves balance, dials the number and returns a
callId and a wsUrl ready to open.2
Open the WebSocket within 30 seconds
The phone is already ringing. Text frames are events; binary frames
are audio.
3
Exchange audio
Send binary PCM and play (or process) the binary PCM you receive.
4
Finish
Close the WebSocket to hang up. The amount is charged for the talk time and
the recording becomes available.
With the Node SDK
d-api-sdk does the steps below for
you. The call uses the same interface as WhatsApp calls:
{ transport: "webrtc" } as the second
argument of voice.live(); details in
Live IVR calls with WebRTC, with the full browser and Node example.
Step 1 — Start the call
CallPOST /voice/live/start with the destination number (with country code,
digits only).
Call identifier. It is the same
callId used in the webhooks and
the recording.Opaque WebSocket URL, with
callId and token already embedded. Open it
exactly as received — do not build the URL yourself.Access token exclusive to this call, generated on every request. It is
already inside the
wsUrl. It is not your API Key: it only opens this
call’s WebSocket and stops being valid when the call ends.Step 2 — Connect to the WebSocket
The call has already been dialed when the response arrives. Open thewsUrl
within 30 seconds: if the WebSocket does not connect in that window, the
call is hung up and the balance reservation is refunded.
error event and closes the
connection with code 1008.
Step 3 — Exchange audio
Audio on the WebSocket is raw PCM (s16le, 16 kHz, mono), in frames
of 20 ms = 320 samples = 640 bytes, in both directions. See the
Audio encoding section to convert from/to other formats.
- Browser (human agent)
- Server (bot / AI agent)
In the browser the approach is identical to the WhatsApp call: run the
AudioContext at sampleRate: 16000 (the browser resamples the microphone
for you) and convert Float32 ⇄ Int16 in an AudioWorklet. Use the reference
voip-worklet.js worklet from the WhatsApp Stream
Calls page without any changes.Audio encoding
The telephone network carries voice in narrowband: 8 kHz, usually in G.711 (μ-law/A-law), with useful content up to ~3.4 kHz. D-API handles that side and always delivers the same format as the WhatsApp stream:
This means you never send μ-law, A-law, base64, WAV, MP3 or Opus over the
WebSocket — only raw 16 kHz PCM. If your system works with another format,
convert it on your side before sending and after receiving.
Audio received from the phone arrives at 16 kHz, but the content is telephony
audio: there is nothing above ~3.6 kHz. This is expected — it is not a loss in
D-API.
Most common conversions
Files, with
ffmpeg:
Reference functions (Node.js)
Dependency-free implementations for real-time, frame-by-frame conversion.Resampling (8, 16, 24, 48 kHz...)
Resampling (8, 16, 24, 48 kHz...)
Linear resampler with state kept between frames (no clicks at the seams).
When downsampling, it first applies a simple moving average as a
low-pass filter. This is enough for telephony voice; for studio quality, use
ffmpeg/libsoxr.μ-law (G.711 PCMU) ⇄ PCM
μ-law (G.711 PCMU) ⇄ PCM
Reading received audio safely
Reading received audio safely
Do not assume every received frame is exactly 640 bytes. Accumulate the
bytes and always read an even number of bytes, in little-endian:
Saving received PCM as WAV
Saving received PCM as WAV
ffmpeg.Troubleshooting audio issues
Step 4 — Track the lifecycle
WebSocket text frames are JSON events in the{ "type": ... } format.
Unlike WhatsApp, telephony does not emit
calling or ringing: between
the POST /voice/live/start response and accepted, the phone is ringing. An
unanswered call (busy, no answer, rejected) ends with ended without
going through accepted.reason of the ended event:
Step 5 — Control the call
Mute / unmute
Mute / unmute
On the IVR, muting is on your side: stop sending audio frames (or send
silence). The WhatsApp
{ "type": "mute" } control is ignored here.Hang up
Hang up
Closing the WebSocket hangs up the call. You can also send a text
control:
Billing
The call is paid with your wallet balance, at the same rate as the IVR calls in your plan (30/6: a first 30-second block, then 6-second blocks).- Reservation at the start.
POST /voice/live/startreserves the amount formin(maximum duration, time your balance covers). Without balance for the first 30-second block, the response is402. - Billed for talk time. Counted from the
acceptedevent until the end. Unanswered calls and false answers (false-answer) are not charged. - Automatic cutoff. When the reserved time runs out, the call is hung up
(
endedwithreason: "hangup"). For long calls, keep enough balance before dialing. - Refund of the remainder. When the call ends, the unused part of the reservation returns to your available balance — even if the WebSocket never connects.
Reconnection (optional)
It works like WhatsApp: add&resume=1 to the wsUrl and a socket drop does
not hang up the call — it waits for you to reconnect with the same wsUrl
for up to 20 seconds. Time keeps running (and being charged) while the
socket is down. See the reconnection example in WhatsApp Stream
Calls.
Recording
Every answered call is recorded. Near the end, the server sends:full is the mix, sender is your side and
recipient is the phone. The recording is also available later at
GET /api/v1/calls/:callId. Accounts with media storage disabled have no
recording.
Webhooks
Stream calls fire the samevoice channel account
webhook events as other IVR calls, plus an event
with the recording. data.callId is the same callId returned by
POST /voice/live/start — it ties together the response, the WebSocket, the
webhooks and the recording. In stream calls, bulkCallId is always null.
In stream calls,
cause and causeDescription are null: the reason the
call ended comes in the reason of the WebSocket ended event. False answers
end with answered: false and are not charged.call.audio carries the same files as the WebSocket recording event:
Errors and limits
The carrier rejected the call (
code: "gateway_error"). Nothing is charged
and the reservation is refunded.The voice stream is currently unavailable. Try again later.
error events carry a code: unavailable, not_found, unauthorized or
forbidden.
Next steps
WhatsApp Stream Calls
The same WebSocket for WhatsApp voice calls, with the reference worklet.
API Reference
Authentication and all D-API endpoints.
