# 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 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

| 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](https://docs.polymorfa.com/calls/web) |
| Your server code | `@polymorfa/sdk/calls` over the media socket, for example a voice agent | [Control calls from your server](https://docs.polymorfa.com/calls/server#speak-and-listen-on-a-call) |
| Your server | HTTP requests that place, answer and end calls without carrying media | [Control calls from your server](https://docs.polymorfa.com/calls/server) |
| Your phone system | A SIP trunk that rings your PBX and lets it call out | [Connect a SIP trunk](https://docs.polymorfa.com/calls/sip-trunks) |

Browsers, server code and a SIP trunk can join the same call. Each participant
hears the others, subject to [conference mode](#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.received` and rings every participant that can
answer. An outbound call returns a `callId` while 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 with `call.missed` and
reason `ring_timeout`. After answering, connect media promptly: a call with no
connected media ends with reason `setup_timeout`.

### Connected

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

### 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

| 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: 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 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](https://docs.polymorfa.com/calls/server#change-a-numbers-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](https://docs.polymorfa.com/calls/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](https://docs.polymorfa.com/calls/server#change-a-numbers-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](https://docs.polymorfa.com/calls/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

| 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](https://docs.polymorfa.com/calls/sip-trunks) report more reasons |
| `call.permission_changed` | A person's call permission for a Cloud API Number changed. See [Call permissions](https://docs.polymorfa.com/calls/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`](https://docs.polymorfa.com/api/errors#calls-disabled) | Calling is turned off for the Number |
| `403` | [`call_permission_required`](https://docs.polymorfa.com/api/errors#call-permission-required) | The recipient has not granted your business permission to call them |
| `403` | [`call_recipient_opted_out`](https://docs.polymorfa.com/api/errors#call-recipient-opted-out) | The recipient is on your team's do-not-call list |
| `403` | [`call_destination_blocked`](https://docs.polymorfa.com/api/errors#call-destination-blocked) | Your team's call policy blocks the recipient's country code |
| `403` | [`number_restricted`](https://docs.polymorfa.com/api/errors#number-restricted) | WhatsApp restricts the Number to people it has already chatted with |
| `409` | [`call_claimed`](https://docs.polymorfa.com/api/errors#call-claimed) | Another participant claimed the call |
| `409` | [`call_not_ringing`](https://docs.polymorfa.com/api/errors#call-not-ringing) | The call was already answered, declined or ended |
| `409` | [`connection_limit`](https://docs.polymorfa.com/api/errors#connection-limit) | The call has no room for another connection. Leave an unused connection first |
| `409` | [`unsupported_for_connection`](https://docs.polymorfa.com/api/errors#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](https://docs.polymorfa.com/api/errors) for the error object.

## See also

- [Add calling to a web app](https://docs.polymorfa.com/calls/web)
- [Control calls from your server](https://docs.polymorfa.com/calls/server)
- [Call permissions and opt-outs](https://docs.polymorfa.com/calls/permissions)
- [Connect a SIP trunk](https://docs.polymorfa.com/calls/sip-trunks)
- [Calls API reference](https://docs.polymorfa.com/api/calls/place-outbound-call)
