Skip to content
Shortcut: /, ⌘K or Ctrl+K

How calls work

Learn how a WhatsApp call rings, is answered and ends, who takes part, and how audio and video reach each participant.

View as Markdown

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 the ephemeralId it was minted with. Client tokens cannot name another participant.
    • A team key or project token acts as server:<participant>. Pass the optional participant name (1 to 128 characters from A-Z, a-z, 0-9, ., _, :, @ and -). It defaults to server:default.
  • 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#

WhereHow it joins a callPage
A browser@polymorfa/browser with a client token, rendered by the call componentsAdd calling to a web app
Your server code@polymorfa/sdk/calls over the media socket, for example a voice agentControl calls from your server
Your serverHTTP requests that place, answer and end calls without carrying mediaControl calls from your server
Your phone systemA SIP trunk that rings your PBX and lets it call outConnect 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#

  1. Ringing

    An inbound call raises call.received and rings every participant that can answer. An outbound call returns a callId while the callee's device rings.

  2. Answered, declined or missed

    A participant answers (call.accepted) or declines (call.rejected). A call nobody answers or declines within the ring window ends with call.missed and reason ring_timeout. After answering, connect media promptly: a call with no connected media ends with reason setup_timeout.

  3. Connected

    Participants and connections join and leave. Webhooks report each change as call.participant_* and call.connection_* events.

  4. Ended

    call.ended carries the reason, direction and durationSeconds, then call.telemetry reports timing and quality, and usage.recorded reports the metered call.

Answer, join, decline and claim#

ActionEffect
AnswerAnswers the ringing call and connects your media
JoinJoins a call another participant answered, without claiming it
DeclineDeclines a ringing call. This ends the call for everyone
LeaveDisconnects one connection. The call continues for others
EndEnds the call for everyone

Choose exclusive on each answer:

  • exclusive: true claims 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 modeEach of your participants hearsThe people on WhatsApp hear
On (default)The people on WhatsApp and every other participant you connectedAll of your participants
OffOnly the people on WhatsAppAll 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 capabilities report video: false and invite: false. Placing a video call or inviting a participant fails with unsupported_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 hostCloudApiCalls for 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 429 without 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 409 before the operation changes call state.
  • Client rules. A client token's rateLimit caps its requests per minute, including call requests; exceeding it fails with 429. The voip_place, voip_answer and voip_signal actions permit placing, answering and connecting media. allowedNumber lists the E.164 numbers a client token can call or invite; a destination outside the list fails with 403.

maxSetupsPerMinute and maxConcurrency are deprecated. Client rules still accept and return them, but they have no effect.

Events#

EventWhen
call.receivedAn inbound call arrived and is ringing. Carries capabilities and the Number's sessionConnection
call.acceptedA participant or the callee answered. Carries answeredBy, capabilities and, for a claimed call, exclusive: true
call.rejectedA participant declined a ringing inbound call
call.missedA ringing inbound call was never answered (reason: "ring_timeout")
call.endedThe 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.telemetryTiming and quality figures for the finished call
call.participant_joinedA participant entered the call roster
call.participant_stateA participant's call state changed
call.participant_leftA participant left the call roster, with an optional reason
call.connection_joinedOne of your participants connected. Carries the participant and the connection id
call.connection_leftA connection left, with reason left, replaced or claimed. SIP trunks report more reasons
call.permission_changedA person's call permission for a Cloud API Number changed. See Call permissions
usage.recordedThe 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#

StatusCodeMeaning
400invalid_parameterA field is invalid, or a client token named a participant
403permission_deniedThe credential cannot act on this call, Number or destination
403calls_disabledCalling is turned off for the Number
403call_permission_requiredThe recipient has not granted your business permission to call them
403call_recipient_opted_outThe recipient is on your team's do-not-call list
403call_destination_blockedYour team's call policy blocks the recipient's country code
403number_restrictedWhatsApp restricts the Number to people it has already chatted with
409call_claimedAnother participant claimed the call
409call_not_ringingThe call was already answered, declined or ended
409connection_limitThe call has no room for another connection. Leave an unused connection first
409unsupported_for_connectionThe Number's connection does not support the operation, such as video on a Cloud API Number
409state_conflictThe call is not ready for this operation or is outside your credential's boundary
410resource_goneThe call ended because its media host is gone
429rate_limit_exceededThe Number's outbound-start limit, a client token's request rate (rateLimit) or a connection's report limit was reached
501operation_not_supportedOutbound calls are not available on this deployment
503service_unavailableThe 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.

See also#