You need an already connected unofficial WhatsApp connection
and an API Key. Generate your key in the Dashboard.
How it works
The flow is always outbound (you call a number) and runs in the browser, where the microphone and speaker live:1
Start the call
POST /calls/stream returns a callId and a wsUrl ready to open.2
Open the WebSocket
The
wsUrl already carries the authentication. Text frames are
lifecycle events; binary frames are audio.3
Exchange audio
Send the microphone as binary PCM and play the binary audio you receive.
4
Finish
Close the WebSocket to hang up. The recording is available at the end.
call.offer webhook.
With the Node SDK
d-api-sdk does the steps below
for you: starts the call, opens the WebSocket, hands you the audio in 20 ms
frames and reconnects if the network drops. The steps that follow describe the
protocol, for integrations in other languages or straight in the browser.
Step 1 — Start the call
CallPOST /calls/stream with the session and the destination number (with
country code, digits only).
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 for each call. It is
already inside the
wsUrl. It is not your API Key: it only opens this
call’s WebSocket and stops working when the call ends.Step 2 — Connect to the WebSocket
Open thewsUrl and set binaryType to receive audio as an ArrayBuffer.
error event and closes the connection.
Step 3 — Capture and play the audio
Audio on the wire is raw PCM (s16le, 16 kHz, mono), in frames of
20 ms = 320 samples = 640 bytes. The simplest way to get the format right is
to run the AudioContext at 16 kHz — the browser resamples the microphone
for you — and convert Float32 ⇄ Int16 inside an AudioWorklet.
Create the voip-worklet.js worklet (reference implementation, the same one the SDK uses):
Step 4 — Track the lifecycle
The WebSocket’s text frames are JSON events in the{ "type": ... } format.
ended event carries a reason: hangup, rejected, timeout,
accepted_elsewhere, terminate (maximum duration reached), ws_closed, among
others. If the WebSocket closes without an ended, treat it as the call ending.
Step 5 — Control the call
Mute / unmute
Mute / unmute
Just stop sending the microphone. The simplest way is to disable the audio
track:Alternatively, the server also accepts a text control message:
ws.send(JSON.stringify({ type: "mute", muted: true })).Hang up
Hang up
Closing the WebSocket hangs up the call — the server interprets the
close as a
hangup.Finish and release resources
Finish and release resources
When you are done, stop the microphone and close the
AudioContext:Reconnection (optional)
By default, if the WebSocket drops, the server hangs up the call. To keep the call alive through a network drop or a server switch during a deploy, append&resume=1 to the wsUrl. With it:
- A socket drop does not hang up: the call stays active and waits for you to reconnect for up to 20 seconds.
- Reconnect with the same
wsUrl. The server resumes the call and replays the events from the beginning (calling,ringing,accepted…). Ignore the ones you already handled. - The server may close the connection with code
1012(service restart) so that you reconnect. Treat it as a drop. - To hang up, close with code
1000—ws.close(1000)— or send{ "type": "hangup" }. Any other close is treated as a drop. - If nobody reconnects within 20 seconds, the call is hung up. The recording covers the entire call, with silence for the period the socket was down.
Audio format
All audio, in both directions, follows exactly this format:Send at real-time pace (one frame every ~20 ms), without accumulating and
flushing in batches.
Recording
By default, stream calls are recorded. Near the end, the server sends:full = mix, sender/recipient = separate
sides). The same recording is also available later at
GET /api/v1/calls/:callId.
To skip recording, send "record": false in POST /calls/stream:
recording
event or call.audio webhook.
The account can also turn off recording for all calls in the panel’s privacy
settings. When it is off,
"record": true does not turn it back on.Errors and limits
Limit on new calls per user (default: 10 every 60 s). Prevents WhatsApp
blocks caused by too many attempts. Wait before trying again.
The voice stream is currently unavailable. Try again later.
error events carry a code: unavailable, not_found, unauthorized,
or forbidden.
Full example
A minimal client that starts the call (via your backend), connects, streams audio, and offers mute/hang up:Next steps
Call webhooks
Receive incoming calls (
call.offer) and the lifecycle via webhook.API Reference
Authentication, sessions, and every D-API endpoint.
