Skip to main content
Incoming calls let your application know, the moment the phone rings, that someone is calling the session’s number — and answer or reject that call through the API. When you answer, D-API returns a media WebSocket identical to the one used by Stream Calls: audio flows in both directions over the same channel.
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.
The events channel and the media channel are different WebSockets. The events channel is single, long-lived, and covers multiple sessions; the media channel is per call and is created on each 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 the call.offer webhook, but media does not come up and the call cannot be answered through the gateway.
Incoming calls require an unofficial connection. The Official API (Cloud API) does not expose a calls API and does not have the bridge pod that speaks the WhatsApp call protocol: receive-calls-settings returns 400 for connections of that type, as do /calls/accept and /calls/reject.
This request restarts the connection. The value is saved to the database and applied as an environment variable on the session’s pod, which triggers a restart. During the restart the session is unavailable for a few seconds: messages are neither sent nor received in that window. Make the change in a controlled window, not on every call.
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.
To turn it off, send { "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).
An offer that rang while the socket was down is not redelivered (it would be stale).

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.
string
required
Your API Key. Accepts a user key or a session-scoped key — in the latter case, only that key’s sessions get through.
string
required
Comma-separated list of sessionIds. Duplicate and empty values are discarded. Maximum of 20 sessions per connection.
The URL embeds your API Key. Open the socket from your backend, or hand the browser a URL generated on demand with a session-scoped key. Do not log this URL.
Authorization is all or nothing: each session in the list is checked individually (valid key and session owned by the key’s owner). If one fails, the entire connection is refused with 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:
If the subscription is refused, an error frame arrives and the socket closes with code 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.
The practical consequence: anyone who reconnects in the middle of an offer loses that offer. Keep the socket open continuously, with automatic reconnection, and treat a drop as losing the calls in that interval. For a complete historical trail, use the call webhooks — they keep being delivered in parallel.

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.
string
required
One of call.offer, call.accepted, call.rejected, or call.ended. See the table below.
string
required
Call identifier. This is what you send to /calls/accept and /calls/reject.
string
JID of the caller, already resolved to the phone number when possible. Optional.
string
Original JID reported by the bridge. May come as @lid. Optional.
number
required
Time of the event in milliseconds (epoch). When the bridge does not stamp the event, the server’s arrival time is used.
string
required
Connection that received the call. Added by the server, because one socket covers multiple sessions and accept requires the sessionId.

Events on this channel

call.accepted does not confirm your answer. It signals that the call left the ringing state without going through here: it was answered on the phone itself or on another device connected to the same account. The same applies to call.rejected.The confirmation that you answered is the HTTP response from /calls/accept, with the media wsUrl. Treating call.accepted as your own success makes your application take over calls that were answered on the phone.
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.
string
Call identifier confirmed by the bridge. It may differ from the one you sent — always use the value from the response from here on.
string
Media WebSocket URL, with callId and token already embedded. Open it exactly as received.
string
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.
The response has the same format as 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.
The wsUrl embeds your API Key in the token parameter. Call /calls/accept from your backend and hand the browser only the wsUrl.
Possible errors:
Session does not exist or is outside your scope.
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.
The corresponding 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.
To reject instead of answering, replace the call to 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.