Skip to main content
IVR Stream Calls let your application talk to a phone (landline or mobile) in real time: you start the call with an HTTP request, open a WebSocket and exchange audio in both directions — your audio (microphone, bot, AI agent) goes to the phone, and the voice of whoever answered comes back to you. The WebSocket contract is the same as WhatsApp Stream Calls: same URL, same audio format and the same event model. If you have already integrated WhatsApp, you can reuse your code.
You need wallet balance and the account API Key. The call is charged to your wallet at the same rate as IVR calls (see Billing). Generate your key in the Dashboard.

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.
Under the hood, D-API dials over the telephone network and bridges the phone and your WebSocket, converting telephony audio (8 kHz) to the stream format (16 kHz) in both directions.

With the Node SDK

d-api-sdk does the steps below for you. The call uses the same interface as WhatsApp calls:
To send the audio over WebRTC, pass { 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

Call POST /voice/live/start with the destination number (with country code, digits only).
The response contains the call identifier and the stream URL:
string
Call identifier. It is the same callId used in the webhooks and the recording.
string
Opaque WebSocket URL, with callId and token already embedded. Open it exactly as received — do not build the URL yourself.
string
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.
Your API Key must never reach the browser. Start the call from your backend and hand the browser only the wsUrl — it carries only the call token. Even so, treat the wsUrl as a short-lived secret (do not log it) while the call is active.
An example of starting the call from the backend, keeping the key out of the browser:

Step 2 — Connect to the WebSocket

The call has already been dialed when the response arrives. Open the wsUrl within 30 seconds: if the WebSocket does not connect in that window, the call is hung up and the balance reservation is refunded.
There is no post-connection handshake: authentication is in the URL. If the server rejects the connection, it sends an 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.
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.
Keep echoCancellation: true. On telephony, speaker echo coming back through the microphone is very noticeable to the person on the phone.
Do not send audio before the accepted event. Until then the phone is still ringing and the audio is discarded.

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.
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.
Do not assume every received frame is exactly 640 bytes. Accumulate the bytes and always read an even number of bytes, in little-endian:
To send a WAV, strip the header (usually the first 44 bytes) and make sure it is already 16 kHz, mono, 16-bit — otherwise convert it with 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.
The reason of the ended event:

Step 5 — Control the call

On the IVR, muting is on your side: stop sending audio frames (or send silence). The WhatsApp { "type": "mute" } control is ignored here.
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/start reserves the amount for min(maximum duration, time your balance covers). Without balance for the first 30-second block, the response is 402.
  • Billed for talk time. Counted from the accepted event 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 (ended with reason: "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:
The files are 16 kHz mono WAV: 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 same voice 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

Insufficient balance for the first 30-second block (code: "insufficient_balance").
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.
30 s
Deadline to open the wsUrl after the start. Once it passes, the call is hung up.
3600 s
Or less, if your balance covers less time. When reached, the call ends.
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.