You need an already connected unofficial WhatsApp connection
and an API Key. Generate your key in the Dashboard.
How it works
1
Enable receiving on the connection
POST /sessions/{sessionId}/receive-calls-settings turns the capability on.
The connection restarts.2
Subscribe to events
Open the
/voip/events WebSocket and keep listening. The offer
(call.offer) arrives there.3
Answer or reject
POST /calls/accept returns the media wsUrl. POST /calls/reject ends
the offer.4
Exchange audio
Open the
wsUrl and follow exactly the flow described on the
Stream Calls page.accept.
Step 1 — Enable receiving on the connection
Receiving is off by default. While it is off, the connection does not engage incoming calls: you still receive thecall.offer webhook, but media does not come
up and the call cannot be answered through the gateway.
If updating the environment variable fails, the value is still persisted and
takes effect on the pod’s next startup. The response is still a success
in that case.
{ "receiveCalls": false }. The connection restarts again.
With the Node SDK
With receiving enabled (Step 1),d-api-sdk
subscribes to the events, reconnects on its own and hands you each call with
answer() and reject(). The answered call is the same as in
Stream Calls, including { transport: "webrtc" } (recommended).
Step 2 — Subscribe to real-time events
Open a WebSocket at/voip/events. Authentication goes in the query string,
because browsers cannot set headers on WebSockets.
Your API Key. Accepts a user key or a session-scoped key — in the latter
case, only that key’s sessions get through.
Comma-separated list of
sessionIds. Duplicate and empty values are
discarded. Maximum of 20 sessions per connection.unauthorized. A client that silently
received a subset would believe it is listening to sessions it never
subscribed to.
As soon as the subscription is accepted, the server sends the first frame:
1008:
No history replay
The socket delivers only the events that arrive while it is connected.
There is no backlog redelivery, and this is intentional: a call offer is
valid for a few seconds and cannot be answered after that. Redelivering the
history would make your app announce a call that has already ended — along
with its
call.rejected.Frame format
All frames are JSON text. This channel is read-only: answering and rejecting are HTTP requests, and audio lives on the other WebSocket.Time of the event in milliseconds (epoch). When the bridge does not stamp
the event, the server’s arrival time is used.
Connection that received the call. Added by the server, because one socket
covers multiple sessions and
accept requires the sessionId.Events on this channel
The three terminal events have the same format as
call.offer, only the
type changes:
Any of the three terminal events closes that call’s cycle. Treat all three
as “stop ringing” — do not always wait for
call.ended, because a call
answered on the phone may close with call.accepted and only later, or
never, produce call.ended.Step 3 — Answer the call
POST /calls/accept with the sessionId and callId that came in the
call.offer.
Call identifier confirmed by the bridge. It may differ from the one you
sent — always use the value from the response from here on.
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.POST /calls/stream. From here on,
audio, lifecycle events, mute, hang up, and recording work exactly as described
in Stream Calls — PCM s16le, 16 kHz, mono,
frames of 320 samples. That documentation is not repeated here.
For quick reference, the media socket sends these control events, which
are different from those on the events channel above:
Do not confuse the two channels.
call.ended arrives on the events
channel and signals that the call is over. ended arrives on the media
channel and ends that stream. On a call you answered, both happen.Official API (Cloud API) connection, or the bridge refused to answer — the
offer may have already expired or been answered elsewhere. Nothing is
recorded in this case: you do not receive a
wsUrl that would never deliver
audio.The voice stream is currently unavailable.
Step 4 — Reject the call
POST /calls/reject needs three fields. Besides sessionId and callId, you
send from: the caller’s JID, exactly as it came in the call.offer.
Pass
from through unchanged. WhatsApp rejects against that JID, not
against a normalized number — if the event carried an @lid, send the @lid.call.rejected is asynchronous: it arrives later,
through the events socket and the webhook. A 200 response means the command
was accepted by the bridge, not that the other end has already stopped ringing.
Full example
A Node client that subscribes to events, answers the first offer, and connects to the media WebSocket. The API Key never leaves the server.atender with:
Next steps
Stream Calls
The media WebSocket in detail: audio format, lifecycle, and recording.
Call webhooks
The server-to-server trail of the same events, with history.
