# WhatsApp Calls

> Your WhatsApp call history and the calling permission request - what each column means, searching and filtering calls, and who can do what.

Source: https://docs.theavoxai.com/calls

Calls is the full call history for your connected WhatsApp number, plus the tool you use to ask a
customer for permission to call them. The header reads "WhatsApp Calling history for your connected
number." and has a **Docs** button that opens this page.

## Before you start

Calls opens once two things are true:

1. **A WhatsApp number is connected.** With no connection at all, the **Calls** item in the sidebar
   (under **Messaging**) shows a lock, and hovering it shows "Calls is locked" with "This feature
   needs a WhatsApp connection first." ([AVX-3001](https://docs.theavoxai.com/error-codes/avx-3001)). When your connection
   exists but isn't currently connected (for example it's paused), the page reads "Connect a WhatsApp
   number to see call history." with a **Go to Connections** button.
2. **Calling is turned on for that connection.** Without it, the page reads "Calling isn't enabled on
   this connection yet - turn it on in Connections to start seeing call history here." with an
   **Enable calling in Connections** button that opens the connection's own page.

An Admin turns Calling on with the **Calling** switch on the connection. See
[Calling](https://docs.theavoxai.com/connections/calling) for the step-by-step.

## Who can use Calls

| Action | Admin | Manager |
| --- | --- | --- |
| View call history | Yes | Yes |
| Send a calling permission request | Yes | Yes |
| Turn Calling on or off for a connection | Yes | No |

The Manager column shows the defaults. Viewing calls needs the **See calls** permission; sending a
permission request needs **See calls** and **Reply in the Inbox**; turning Calling on or off needs
**Manage connections**. An Admin can change these for each person - see
[Permissions](https://docs.theavoxai.com/switchboard/members#permissions).

You can also ask from a conversation with **Request a call** in the [Inbox](https://docs.theavoxai.com/inbox#request-a-call),
or let an automation do it with the [Request a call](https://docs.theavoxai.com/automation/actions#request-a-call) action.

## Request calling permission

WhatsApp requires a customer's permission before a business calls them. The **Request calling
permission** card sends that request as a WhatsApp message. Its note reads "Meta requires a customer's
explicit permission before your number can call them - send a request first (only works within the
same 24-hour reply window as a normal message; a customer who hasn't messaged recently needs a
template instead)."

**1. Choose a contact**

Open the **Choose a contact** picker and select the customer. The picker lists up to 50 of your
contacts, most recently changed first, by name (or phone number when no name is saved). With no
contacts yet, it reads "No contacts yet".

**2. Send the request**

Click **Send request**. When it's sent, you see "Permission request sent." and the
[Avox Avatar](https://docs.theavoxai.com/avox-avatar) says "Sent."

**3. The customer answers in WhatsApp**

The customer receives an interactive message in their chat with your business that reads "We'd
like to call you about your recent conversation - is that okay?" and chooses whether to allow
calls. See [Calling on WhatsApp](https://docs.theavoxai.com/whatsapp/calling) for what the customer sees.

A permission request is a normal WhatsApp message, so it follows the
[24-hour reply window](https://docs.theavoxai.com/whatsapp/messaging-window): you can send it while the customer has messaged
you in the last 24 hours. For a customer who hasn't messaged recently, send a [template](https://docs.theavoxai.com/templates)
first - for example a **Calling permission request** template (see
[Create a template](https://docs.theavoxai.com/templates/create)). Once they reply, the window opens again.

### If the request doesn't send

The reason shows as a pop-up message.

| Message | What to do |
| --- | --- |
| Enable calling on this connection first. | Calling was turned off. Ask an Admin to turn it on - see [Calling](https://docs.theavoxai.com/connections/calling). |
| It's been over 24 hours since this contact last messaged you - send a template to reopen the conversation. | Send a template, wait for a reply, then send the request ([AVX-3059](https://docs.theavoxai.com/error-codes/avx-3059)). |
| Your WhatsApp number isn't connected right now. | Check the connection on [Connections](https://docs.theavoxai.com/connections) ([AVX-3057](https://docs.theavoxai.com/error-codes/avx-3057)). |
| Couldn't find that contact. | The contact no longer exists in this Switchboard. Refresh the page ([AVX-3058](https://docs.theavoxai.com/error-codes/avx-3058)). |
| You're sending too quickly - wait a moment and try again. | Wait a moment, then send again. |
| Couldn't send that permission request. Try again. | WhatsApp didn't accept the request. Try again shortly ([AVX-3065](https://docs.theavoxai.com/error-codes/avx-3065)). |

## The call log

Every call event WhatsApp reports for your number appears here, newest first, 30 per page.

| Column | What it shows |
| --- | --- |
| **Contact** | The contact's avatar and name from [Contacts](https://docs.theavoxai.com/contacts) (or "Unknown contact"), with up to two of their tags and categories. |
| **Direction** | **Inbound** (a customer called you) or **Outbound** (your business called the customer). |
| **Status** | **Connected** (the call was answered), **Ended** (the call finished), or **Missed** (shown in red). |
| **Duration** | How long the call lasted, for example `2m 14s` or `45s`. Shows `-` when WhatsApp didn't report a duration, for example on the Connected event. |
| **When** | How long ago the event happened ("just now", "5m ago", "3h ago", or a date). Hover it to see the call ID. |
| (actions) | **Profile** opens the contact's profile. |

Click anywhere on a row (or select it with **Tab** and press **Enter**) to open that contact's
[profile](https://docs.theavoxai.com/contacts#the-customer-profile), where the **Calls** tab lists their call history.

One call can create more than one row - for example a **Connected** row when it's answered and an
**Ended** row with the duration when it finishes.

With more than 30 events, the footer shows "Page 1 of 3 · 74 calls" with **Previous** and **Next**
buttons. Before the first call, the log reads "No calls logged yet."

### Searching and filtering

Above the log:

- **Search** - type a contact's name, the last digits of their number, or a call ID. The list
  updates as you type.
- **Direction** - **Any direction**, **Inbound** or **Outbound**.
- **Outcome** - **Any outcome**, **Connected**, **Ended** or **Missed**.
- **Duration** - **Any length**, **Under 30 seconds**, **30 seconds to 2 minutes**, **2 to 10
  minutes** or **10 minutes or more**.
- **Category** and **Tags** - show only calls with contacts in the
  [tags and categories](https://docs.theavoxai.com/contacts#tags-and-categories) you tick.
- **From** and **To** - a date range.

Filters work together. **Clear filters** removes them all, and with nothing matching the log reads
"No calls match these filters." Your search and filters are part of the page address, so you can
bookmark or share a filtered view.

The line above the permission card reads "Real call events, populated by Meta's own Calling webhook."
and a **Manage contacts →** link opens [Contacts](https://docs.theavoxai.com/contacts).

### Filtering by contact

To see one customer's calls only, open Calls from that customer:

- The **Calls** button on their row in [Contacts](https://docs.theavoxai.com/contacts).
- The **Calls** button at the top of their conversation in the [Inbox](https://docs.theavoxai.com/inbox).

The log then reads "Showing calls for Maria" (with the contact's name). Click **Clear filter** to see
every call again. The filter lives in the page address (`/calls?contact=...`), so you can bookmark it.

## Recent calls on Health

[Health](https://docs.theavoxai.com/health) shows a shorter **Recent calls** list (10 per page) with a **View all →** link to
this page.

## Errors on this page

| Message | Code |
| --- | --- |
| Couldn't load your call log. Try again. | [AVX-3064](https://docs.theavoxai.com/error-codes/avx-3064) |
| Couldn't send that permission request. Try again. | [AVX-3065](https://docs.theavoxai.com/error-codes/avx-3065) |