# Calling on WhatsApp

> How the WhatsApp Business Calling API works on Meta's side - call settings, customer-initiated calls, permission requests, call events - and every place Avox lets you use it.

Source: https://docs.theavoxai.com/whatsapp/calling

The WhatsApp Business Calling API lets customers call a business's WhatsApp number from the
WhatsApp app, the same way they call friends. This page explains how calling works on WhatsApp's
side, and where each part shows up in Avox. To turn it on, see [Calling](https://docs.theavoxai.com/connections/calling); for
your call history, see [Calls](https://docs.theavoxai.com/calls).

- [Turn calling on](https://docs.theavoxai.com/connections/calling): One switch per connection, for Admins.

- [See your calls](https://docs.theavoxai.com/calls): Call history with search and filters.

- [Use it from your server](https://docs.theavoxai.com/integrations/whatsapp-calling): Send permission requests through the Avox API.

## Calling is a per-number setting

Calling is switched on or off for each phone number, in the number's call settings on Meta's side.
When an Admin flips the **Calling** switch on a connection's page in Avox, Avox updates that setting
with Meta for you - you don't need to change anything in WhatsApp Manager yourself. The switch only
stays on once Meta confirms the change. Meta decides which numbers are eligible to use calling.

With calling on for a number:

- Customers can call it from their WhatsApp chat with you.
- Avox logs every call event Meta reports on [Calls](https://docs.theavoxai.com/calls) and in **Recent calls** on
  [Health](https://docs.theavoxai.com/health).
- A number that calls you for the first time becomes a [contact](https://docs.theavoxai.com/contacts).
- You can ask customers for permission to call them.

## Two kinds of call

| Kind | Who starts it | What's needed | Shown in Avox as |
| --- | --- | --- | --- |
| **Customer-initiated** | The customer calls your business from their WhatsApp chat with you. | Calling turned on for your number. | **Inbound** |
| **Business-initiated** | Your business calls the customer. | Calling turned on, **and** the customer's permission first. | **Outbound** |

## Asking a customer for permission

WhatsApp protects customers from unwanted calls: before a business calls someone, the customer must
agree. A business asks with a **call permission request** - a special interactive message in the
customer's chat. The customer then chooses whether to allow calls from your business, right in the
chat.

By default the request reads:

> We'd like to call you about your recent conversation - is that okay?

### Every way to send one in Avox

| Where | How | Window |
| --- | --- | --- |
| [Calls](https://docs.theavoxai.com/calls) | The **Request calling permission** card: pick the customer under **Choose a contact**, then click **Send request**. You see "Permission request sent." | Needs the 24-hour window |
| [Inbox](https://docs.theavoxai.com/inbox) | **Request a call** in the conversation header. It changes to **Request sent** once it's gone. | Needs the 24-hour window |
| [Automation](https://docs.theavoxai.com/automation/actions#request-a-call) | A **Request a call** step, with your own optional message (up to 1024 characters) in place of the default text. The premade **Callback request** automation uses it. | Needs the 24-hour window |
| [Templates](https://docs.theavoxai.com/templates) | A template of the **Calling permission request** type, in the Utility or Marketing category, with your own header, body and footer. Send it from an automation or the Avox API once it's approved. | Works outside the window |
| [Avox API](https://docs.theavoxai.com/integrations/whatsapp-calling#build-your-own-server-for-whatsapp-calling) | An `interactive` message of type `call_permission_request`. | Needs the 24-hour window |

Sending a request needs calling turned on for the number ("Enable calling on this connection
first." otherwise). In the dashboard, anyone who can **Reply in the Inbox** and **See calls** can send
one - by default, every Admin and Manager. See [Permissions](https://docs.theavoxai.com/switchboard/members#permissions).

### The window and permission requests

A permission request is a regular WhatsApp message, so it follows the
[24-hour customer service window](https://docs.theavoxai.com/whatsapp/messaging-window): send it while the customer has messaged
you within the last 24 hours. Outside the window, Avox shows "It's been over 24 hours since this
contact last messaged you - send a template to reopen the conversation." For that customer, send an
approved template of the **Calling permission request** type, or any approved
[template](https://docs.theavoxai.com/whatsapp/template-categories) - once they reply, the window is open again.

> **Tip**
>
> Get a **Calling permission request** template approved before you need it. It's the one way to ask
> for permission from customers who haven't written in the last 24 hours.

## What customers see

- **Your business name and profile**, as on any WhatsApp chat with you. See
  [Display names](https://docs.theavoxai.com/whatsapp/display-names).
- **A way to call you** from the chat, once calling is on for your number.
- **Your permission request**, as an interactive message they can answer in the chat.

Calls happen over the customer's internet connection inside WhatsApp, not as a regular phone call.

## Call events

As a call progresses, Meta sends call events to the number's webhook under the `calls` field. Avox
receives them and logs each one on [Calls](https://docs.theavoxai.com/calls):

| Event | Shown in Avox as | Meaning |
| --- | --- | --- |
| `connect` | **Connected** | The call was set up. |
| `terminate` | **Ended** | The call finished. Includes the call's duration when it was answered. |

When WhatsApp reports a missed call, it shows as **Missed** in your log. Each call also shows its
**Direction**: **Inbound** when the customer called you, **Outbound** when your business called
them. For the full event format, with an example, see [Meta webhooks](https://docs.theavoxai.com/whatsapp/webhooks#calls).
Every call event is also listed on [Logs](https://docs.theavoxai.com/logs) under the event type `calls`.

### Finding a call

The call log on [Calls](https://docs.theavoxai.com/calls) shows **Contact**, **Direction**, **Status**, **Duration** and
**When** for each call. Narrow it down with:

- **Search** - "Name, last digits or call ID".
- **Direction** - **Inbound** or **Outbound**.
- **Outcome** - **Connected**, **Ended** or **Missed**.
- **Duration**, **Category** and **Tags**, and a **From** / **To** date range.

**Clear filters** resets them. To see one customer's calls, click **Calls** at the top of their Inbox
conversation, or on their row in [Contacts](https://docs.theavoxai.com/contacts). Clicking a call opens the contact's profile,
whose **Calls** tab lists their call history.

## Good practice

- **Ask at the right moment.** Send the permission request while the customer is already talking to
  you, so they know why you want to call.
- **Explain first.** A short message before the request ("Can we call you to sort this out?") helps
  customers say yes.
- **Respect a no.** If a customer doesn't allow calls, keep helping them in the chat.
- **Space out requests.** Avox asks you to wait a moment if you send requests too quickly ("You're
  sending too quickly - wait a moment and try again.").
- **Keep your quality high.** Unwanted calls and messages lead to blocks and reports, which affect your
  number's [quality rating](https://docs.theavoxai.com/whatsapp/quality-and-limits).

## Common questions

**Do customers need to do anything to call us?**

Once **Calling** is on for your number, customers call you from their WhatsApp chat with you, the way
they'd call anyone.

**Can I change the wording of the permission request?**

The **Send request** button on Calls and **Request a call** in the Inbox use the default wording. For
your own words, use an automation's **Request a call** step or a **Calling permission request**
template.

**Why can't I send a permission request to this customer?**

Check three things: calling is on for the number ("Enable calling on this connection first."), the
customer has written in the last 24 hours, and you have the **Reply in the Inbox** and **See calls**
permissions. For a customer outside the window, send a **Calling permission request** template.

**Do we have several numbers? Which one does Calls show?**

The [Calls](https://docs.theavoxai.com/calls) page follows your Switchboard's most recently connected number. Turn calling on
for that number to use the page.

## Related pages