How calls work
Learn how a WhatsApp call rings, is answered and ends, who takes part, and how audio and video reach each participant.
A connected Number places and receives WhatsApp voice and video calls. Your application decides who is invited, who answers and whether other participants can join; nothing answers a call automatically.
- The call rings, is answered or declined, and ends. Ending it disconnects everyone.
- Participants act in the call. Polymorfa derives the participant from the credential:
- A client token acts as
client:<ephemeralId>, using theephemeralIdit was minted with. Client tokens cannot name another participant. - A team key or project token acts as
server:<participant>. Pass the optionalparticipantname (1 to 128 characters fromA-Z,a-z,0-9,.,_,:,@and-). It defaults toserver:default.
- A client token acts as
- Connections carry a participant's audio and video. Each browser tab or server client is one connection, and a participant can hold several. Leaving closes one connection and never ends the call.
Where your participants run#
| Where | How it joins a call | Page |
|---|---|---|
| A browser | @polymorfa/browser with a client token, rendered by the call components | Add calling to a web app |
| Your server code | @polymorfa/sdk/calls over the media socket, for example a voice agent | Control calls from your server |
| Your server | HTTP requests that place, answer and end calls without carrying media | Control calls from your server |
| Your phone system | A SIP trunk that rings your PBX and lets it call out | Connect a SIP trunk |
Browsers, server code and a SIP trunk can join the same call. Each participant hears the others, subject to conference mode, and receives their video. The SDKs handle media connections, reconnects and token renewal.
Voice agents and speech processing are bring-your-own. Your server code reads and writes the call's audio and connects it to the speech or agent service you choose. Polymorfa does not run a voice agent for you.
Lifecycle#
Ringing
An inbound call raises
call.receivedand rings every participant that can answer. An outbound call returns acallIdwhile the callee's device rings.Answered, declined or missed
A participant answers (
call.accepted) or declines (call.rejected). A call nobody answers or declines within the ring window ends withcall.missedand reasonring_timeout. After answering, connect media promptly: a call with no connected media ends with reasonsetup_timeout.Connected
Participants and connections join and leave. Webhooks report each change as
call.participant_*andcall.connection_*events.Ended
call.endedcarries thereason,directionanddurationSeconds, thencall.telemetryreports timing and quality, andusage.recordedreports the metered call.
Answer, join, decline and claim#
| Action | Effect |
|---|---|
| Answer | Answers the ringing call and connects your media |
| Join | Joins a call another participant answered, without claiming it |
| Decline | Declines a ringing call. This ends the call for everyone |
| Leave | Disconnects one connection. The call continues for others |
| End | Ends the call for everyone |
Choose exclusive on each answer:
exclusive: trueclaims the call. Other participants stop ringing, cannot answer or connect, and their open connections close. Use it when one person handles the call, for example when the first agent to pick up takes it.exclusive: false(the default) leaves the call shared. Other participants keep ringing and can join.
A later answer on a shared call joins it. Repeating an answer as the same participant is safe. Only the participant that answered can claim a shared call later; a claim from anyone else fails with call_claimed, so participants who already joined stay connected. On a call you placed, the placing participant is the answering participant.
When another participant claims a call, the SDKs mark it as claimed elsewhere. Stop ringing and do not decline it: declining ends the call for the participant who answered.
Conference mode#
Your participants are everyone you connect to a call: people in a browser, your servers and bots, and your phone system through a SIP trunk. Conference mode decides whether they hear each other.
| Conference mode | Each of your participants hears | The people on WhatsApp hear |
|---|---|---|
| On (default) | The people on WhatsApp and every other participant you connected | All of your participants |
| Off | Only the people on WhatsApp | All of your participants |
Nobody hears their own voice in either mode. A participant with more than one connection to the same call, for example while reconnecting, does not hear itself through its other connection.
Turn conference mode off when each participant talks to the WhatsApp side independently, for example a bot that transcribes the call alongside a human agent who should not hear the bot. Conference mode is a Number's call setting; see Change a Number's call settings.
Audio and video#
Each participant receives one merged audio stream. Polymorfa forwards each participant's video as a separate stream and does not combine them into a grid. The WhatsApp side of the call receives one video stream: the camera of the first participant that sends video while that participant remains connected.
Each call reports its capabilities: video and invite. The SDK components hide controls that a call does not support.
Linked-device and Cloud API Numbers#
A linked-device Number calls as the WhatsApp app on the phone does: voice and video, one-to-one or group calls, and invites. A Number connected through the WhatsApp Business Cloud API has these limits:
- Calls are one-to-one and audio only. Their
capabilitiesreportvideo: falseandinvite: false. Placing a video call or inviting a participant fails withunsupported_for_connection. Answering with video answers with audio only. - Before you place a call, the recipient must grant your business permission to call them. Without it, placing the call fails with
call_permission_required. See Call permissions. - WhatsApp allows 30 to 60 seconds to answer an inbound Cloud API call. Answer within 30 seconds to avoid a missed call.
- Incoming calls reach your Calls apps only after you turn on
hostCloudApiCallsfor the Number. Until then your Graph API integration answers them. See Change a Number's call settings.
Calls to people who never chatted with the Number#
WhatsApp sometimes restricts a Number to starting conversations and calls only with people it has already chatted with. While that restriction is active, Polymorfa refuses a call or invite to anyone else with 403 number_restricted before anything reaches WhatsApp, and returns Retry-After when WhatsApp reported an end time. Calls to people the Number has chatted with keep working, and so do incoming calls.
session.restriction_updated tells you when the restriction starts, changes and ends. If a call does reach WhatsApp while the Number is restricted, it ends with reason: "call_restricted". See Calling best practices.
Limits#
Every credential has the same call limits. Team keys, project tokens and client tokens share the limits below, and usage limits apply to each of them in the same way.
- Outbound starts. Each source Number in your team has a limit of 30 calls it starts per minute. Changing the destination or using another key or client token does not reset it. A placement above the limit fails with
429without ringing the destination; wait for the next minute. - Credential boundary. Team keys control calls across their team. Project tokens control calls on any Number in their project. Client tokens control calls only on their bound Number. A call outside the boundary fails with
409before the operation changes call state. - Client rules. A client token's
rateLimitcaps its requests per minute, including call requests; exceeding it fails with429. Thevoip_place,voip_answerandvoip_signalactions permit placing, answering and connecting media.allowedNumberlists the E.164 numbers a client token can call or invite; a destination outside the list fails with403.
maxSetupsPerMinute and maxConcurrency are deprecated. Client rules still accept and return them, but they have no effect.
Events#
| Event | When |
|---|---|
call.received | An inbound call arrived and is ringing. Carries capabilities and the Number's sessionConnection |
call.accepted | A participant or the callee answered. Carries answeredBy, capabilities and, for a claimed call, exclusive: true |
call.rejected | A participant declined a ringing inbound call |
call.missed | A ringing inbound call was never answered (reason: "ring_timeout") |
call.ended | The call ended, with reason, direction and durationSeconds. A call whose media host was lost reports reason: "pod_lost" and from: null. A call WhatsApp refused because the Number is restricted reports reason: "call_restricted" |
call.telemetry | Timing and quality figures for the finished call |
call.participant_joined | A participant entered the call roster |
call.participant_state | A participant's call state changed |
call.participant_left | A participant left the call roster, with an optional reason |
call.connection_joined | One of your participants connected. Carries the participant and the connection id |
call.connection_left | A connection left, with reason left, replaced or claimed. SIP trunks report more reasons |
call.permission_changed | A person's call permission for a Cloud API Number changed. See Call permissions |
usage.recorded | The ended call was metered |
Participants use the same Polymorfa user id everywhere. Known aliases appear as phoneNumber, bsuid or username. The audioMuted and video fields of a participant are reserved and remain false, because WhatsApp does not report either state per participant.
Errors#
| Status | Code | Meaning |
|---|---|---|
400 | invalid_parameter | A field is invalid, or a client token named a participant |
403 | permission_denied | The credential cannot act on this call, Number or destination |
403 | calls_disabled | Calling is turned off for the Number |
403 | call_permission_required | The recipient has not granted your business permission to call them |
403 | call_recipient_opted_out | The recipient is on your team's do-not-call list |
403 | call_destination_blocked | Your team's call policy blocks the recipient's country code |
403 | number_restricted | WhatsApp restricts the Number to people it has already chatted with |
409 | call_claimed | Another participant claimed the call |
409 | call_not_ringing | The call was already answered, declined or ended |
409 | connection_limit | The call has no room for another connection. Leave an unused connection first |
409 | unsupported_for_connection | The Number's connection does not support the operation, such as video on a Cloud API Number |
409 | state_conflict | The call is not ready for this operation or is outside your credential's boundary |
410 | resource_gone | The call ended because its media host is gone |
429 | rate_limit_exceeded | The Number's outbound-start limit, a client token's request rate (rateLimit) or a connection's report limit was reached |
501 | operation_not_supported | Outbound calls are not available on this deployment |
503 | service_unavailable | The call is at capacity, call authority or call settings are unavailable, or the media host is draining |
The SDKs raise these as typed errors; call_claimed is a CallClaimedError. See Errors for the error object.