# WhatsApp calling

> How customers call the business on WhatsApp, how the business calls customers, call permissions and WhatsApp’s limits.

Source: https://docs.nexafone.so/v1/calling/

Nexafon answers and places WhatsApp voice calls on the business’s own number, in the browser, inside your product.
Embedded users take calls in the [softphone](/v1/web/) or `<nexafon-app>`, and start them with a
`<nexafon-call-button>` or `Nexafon.call(phone)`.

## Before calls work

- **Calling is turned on** for the workspace’s WhatsApp number (in the dashboard’s WhatsApp settings). Meta only allows
  it on numbers with a messaging limit of at least 2,000; otherwise you get `whatsapp.calling_cannot_be_enabled`.
- The member’s role includes `calls:answer`, and for embedded users the signing secret key’s scopes include it too.
- The browser has a microphone and the user allows it. The SDK frames carry `allow="microphone; autoplay"`.

## Customers calling the business

A call to the business number rings the team its call routing picks, with that team’s ring strategy
(everyone at once, in order, or priority on plans that include it). The first member to answer takes it; the others
see that someone answered. Unanswered calls end as **missed** and show in the call history. Your page hears
`call.ringing`, `call.answered` and `call.ended` ([events](/v1/web/events/)); your server gets `call.ringing`,
`call.answered`, `call.ended` and `call.missed` [webhooks](/v1/webhooks/events/).

## The business calling a customer

WhatsApp lets a business call a customer only after the customer **allowed** it:

| Rule (set by WhatsApp) | |
| --- | --- |
| Asking for permission | One request a day and two a week per customer, until a call connects (`call_permission_request_limit`) |
| Inside the 24-hour window | The request is a message with **Allow** / **Don’t allow** buttons |
| Outside the window | Only an approved template with a call permission button can ask (`call_permission_template_missing`) |
| How long it lasts | 7 days, unless the customer makes it permanent; they can also refuse |
| Without permission | Calling answers `call_permission_missing` |

The inbox shows the permission state of each customer and offers the request when it is allowed. Other WhatsApp
limits Nexafon passes on:

- A daily cap on connected business-initiated calls per number, and per customer
  (`whatsapp.business_call_limit`), and a cap on simultaneous calls (`whatsapp.call_concurrency_limit`).
- Business-initiated calls are not available from business numbers in some countries (currently the United States,
  Canada, Egypt, Vietnam, Nigeria and Türkiye): `whatsapp_call_country_unsupported`. Customers there can still call
  the business.
- WhatsApp can pause calling on a number for low quality (`whatsapp.calling_disabled_low_quality`).

Outbound calls are billed per minute to the workspace wallet; with a low balance or past-due billing they pause
(`insufficient_balance`, `billing_past_due`) while customers can still call in. See [billing](/v1/billing/).

## Recording

On plans with `call_recording`, calls can be recorded once answered. WhatsApp calls need a recording announcement
chosen in the WhatsApp call settings first (`call_recording_consent_missing`). Recordings are listed by the
[recordings API](/v1/api/recordings/).

## Prayer times

Ringing can pause during prayer times, which Nexafon calculates for the workspace’s location (Umm al-Qura method by
default); a call that ends this way has `endReason: "prayer"`.