Skip to main content
These events cover WhatsApp voice calls (VoIP) on the session’s number: incoming calls and the lifecycle of outgoing calls. They are all delivered to the per-session webhook, with the common envelope { event, sessionId, data, timestamp, traceId? }.
Do not confuse this with the IVR product. IVR events use a different envelope — { event, channel: "voice", data: { callId, bulkCallId, ... } } — and are not what this page documents. Here we only cover WhatsApp voice calls on the session’s number.
Call events are dispatched only to the D-API webhook and to RabbitMQ — they are not sent to CRM integrations. The call.offer event is delivered even with automatic rejection enabled.

Event direction

Outgoing calls are started via POST /calls/place (standard call) and POST /calls/stream (mode with recording). The events below reflect the progress of those calls.

Who is on the other end: phone

All call.* events carry phone: the phone number on the other end of the call — whoever called the session or whoever the session called —, digits only, without @s.whatsapp.net. It is never the session’s own number, in either direction. Use this field to identify the contact.
string | null
required
Phone number of the other end, digits only (e.g. 5511999999999). It is null when WhatsApp only provided a LID with no known phone number; in that case the LID comes in lid. It does not appear in the live call.audio chunks.
string
LID of the other end (...@lid). Present only when phone is null. A LID is not a phone number: do not use its digits as a number.
Do not use from or callCreator to identify the contact. They indicate who started the call: on a call placed by the session, both carry the session’s own number. They remain in the payload for compatibility.

call.offer — incoming call

Fired when the session’s number receives a call.
string
required
Call identifier.
string | null
required
Phone number of the caller. See phone.
string
required
Who started the call, resolved to a phone number when possible (or ...@lid). Kept for compatibility — prefer phone.
string
Who started the call, as reported by WhatsApp. May come as @lid. Kept for compatibility — prefer phone.
boolean
required
true when it is a group call.
string
Group JID. Present only when isGroup is true.
number
required
Time of the call in milliseconds (epoch).

Outgoing calls — base payload

Outbound events (call.ringing, call.connected, call.ended, call.not_answered) share the same base payload (CallEvent):
string
Call identifier.
string
Call state. Varies by event (see below).
string
Reason the call ended. Present only in call.ended.
string
Peer JID in @lid format. Optional.
string
Peer JID in phone number format. Optional.

call.ringing

State "ringing" — the call is ringing. It is the first event of an outgoing call, emitted as soon as the call is started (dialed) — before call.connected.

call.connected

State "active" — the call was answered and is in progress.

call.ended

State "idle" — the call has ended. The reason field is filled in.
A call generates exactly one call.ended (duplicate events from the bridge are deduplicated by callId). For outgoing calls, call.ended covers only those that were answered — one that rang and was not answered generates call.not_answered instead.

call.not_answered

State "idle" — an outgoing call that rang but was never answered (ended before connecting, including the no-answer timeout). It replaces call.ended in this case, so you can tell “not answered” apart from “answered and ended” without inspecting reason. It applies only to outgoing calls.
Unanswered calls do not generate a recording: there is no audio upload and no call.audio event. (The call is still recorded in the internal audit trail, flagged as not answered.)

call.audio

The call.audio event has two variants, depending on how the outgoing call was started.
In the live chunks variant, call.audio can be high volume — about 1 event per second per call. Enable it only if you are going to consume the audio.

Variant A — live audio chunks

Audio streamed in pieces of ~1s each, ordered by seq, with final: true on the last chunk.
string
Call identifier.
number
Chunk sequence number. Use it to order the pieces.
number
Sample rate (typically 16000).
number
Number of channels (typically 1).
string
Audio encoding (pcm_s16le).
string
PCM audio chunk in base64.
boolean
true on the last chunk of the call.

Variant B — finished recording (stream mode)

A single event at the end of the call, with the recording URLs. It happens in stream mode (POST /calls/stream) only for answered calls — calls that were not answered generate neither a recording nor this event.
string
Call identifier.
object
16kHz mono audio tracks:
string
deprecated
Deprecated — alias of files.full.
number
Recording duration in milliseconds.
number | null
File size in bytes.
string
File type (audio/wav).
string | null
Phone number of the other end, digits only.

call.accepted / call.rejected

call.accepted: an incoming call answered on another device. call.rejected: a rejected call — an incoming one the session rejected, or one placed by the session that the contact rejected. In both cases, phone is the contact.
The payload of these events is relayed as-is from the bridge. The guaranteed fields are callId and phone (the contact). from is who started the call — in the example above, the session itself, which placed the call and was rejected. The other fields mirror the bridge’s call data and are not documented here to avoid assumptions.