# WhatsApp Calling

## Overview

WhatsApp Calling lets your workspace place and receive real WhatsApp voice calls right from the browser, using the official WhatsApp Business Calling API. The audio runs in your browser, and every call is recorded in the call log.

Calling is managed from WhatsApp Calling settings (turn it on or off per number). The live calling controls — the dial button, the incoming-call popup, and the on-call panel — appear inside Team Inbox when you're working a conversation on a calling-enabled number. The full archive of recordings and transcripts lives in Call Logs.

> Official Cloud API only. WhatsApp Calling is a feature of the official WhatsApp Cloud API (WABA). It isn't available on the Unofficial API or Twilio — calling only works on a WABA number.

## Prerequisites

All of these must be in place before a number can place or take calls:

Requirement | Detail
--- | ---
Engine | WhatsApp Cloud API (WABA). The number must be connected as an official Cloud API number with a valid phone-number ID and access token.
Plan feature | The WhatsApp Calling plan feature. Without it, the calling controls are hidden.
Role | Manager or Admin to manage calling. Operators use the live call controls inside Team Inbox.
Calling enabled on the number | Calling must be turned on for the specific WABA number (see Per-number status).
Calling webhook configured | In Meta, subscribe your WhatsApp Business Account to the calls webhook field and point it at `https://YOUR-DOMAIN/webhooks/wa-calling` (see below). Without it, incoming calls, call-ended events, and permission updates never reach WaDesk.
Browser microphone | The operator's browser must allow microphone access so it can capture your voice (see Microphone permission).
Customer permission (outbound) | To call a customer, they must have given calling permission first (see Outbound dialling).

> The crown badge. WhatsApp Calling and Call Logs share the WhatsApp Calling plan feature. If your plan doesn't include it, the controls show an upgrade crown and are disabled. Recording additionally needs the Call Recording feature, and the live AI answering agent needs the AI Voice Agent feature — see the AI Call Assistant.

## Configure the calling webhook

Meta sends call events to WaDesk over a dedicated webhook, separate from the messages webhook:

- Callback URL: `https://YOUR-DOMAIN/webhooks/wa-calling`
- Verify token: the value your admin set under Admin → Settings → WhatsApp Message. Meta's verification check only passes when this matches.
- App secret: set the WABA app secret on the same admin screen. Every incoming call webhook is checked against this secret to prove it really came from Meta; if it isn't set, WaDesk refuses the webhook outright (there's no bypass, because each call changes your workspace's data).
- Field to subscribe: calls.

Three kinds of event come through: an incoming call (or your outbound call being picked up), a call-ended event (Meta sends the official duration and reason), and a permission update (the customer accepted or declined a calling-permission request).

## Per-number status & enabling calling

The WhatsApp Calling settings list shows every WABA number in the workspace with its current state:

- Phone number and display label.
- Connection status — the provider connection health.
- Calling enabled — whether voice calling is on for that number, and when it was last enabled.

Toggling calling on/off tells Meta to enable or disable calling for that number and saves the result. Only WABA numbers can be toggled — it's rejected on any other number. Once a number is enabled, conversations on it show the Call button in Team Inbox.

## Microphone permission

Voice runs entirely in your browser, so it must be allowed to use the microphone. WaDesk turns the mic on before connecting the call; otherwise the call would be one-way and the customer would hear silence. The first time you start or accept a call, the browser asks for microphone access — grant it. If it's blocked, WaDesk stops the call with a clear error ("Microphone access blocked — the caller will not hear you") rather than connecting a one-way call. Re-enable the microphone for the site in your browser settings and try again.

> Two different "permissions". The microphone permission is a browser setting on your own device. It's separate from the customer calling permission — the consent the customer gives in WhatsApp before you can dial them (see Outbound dialling).

## Outbound dialling

To call a customer, open a conversation on a calling-enabled WABA number and click Call. What happens:

1. Your browser turns on the mic and sets up the call connection.
2. WaDesk checks the customer's calling permission, then asks Meta to place the call to their number. The call is recorded so you can find it later.
3. The on-call panel appears with a live timer. When the customer answers, the audio connects. Use Mute and Hang up from the panel.

> Customer consent is required first. WhatsApp doesn't let a business cold-call a user. The customer must have granted calling permission, which WaDesk tracks per number and contact. If there's no active permission on file, the call is refused with a message to send a permission request first. Use the permission request action to send the customer a "Can we give you a quick call?" message; their Accept / Decline comes back and updates the stored permission. A granted permission expires — after it lapses you must ask again.

## Incoming calls: toast, accept & reject

When a customer calls one of your enabled numbers, Team Inbox shows an incoming-call popup with the caller's name and number. The inbox checks for ringing calls every few seconds, and the popup offers two choices:

- Accept — answer the call (see the next section).
- Decline — reject the call. The customer stops ringing and the call is recorded as rejected.

## Accepting a call

1. Your browser connects to the customer's call and turns on the mic.
2. WaDesk tells Meta you've accepted, and the audio connects between your browser and the customer.
3. The on-call panel takes over with the live timer, mute, and hang-up controls. Hang up ends the call; Meta then confirms the final duration and reason.

> Built for a shared team. Accepting is safe when several people share an inbox. If two teammates click Accept on the same ringing call, the first one wins and the second sees "already accepted by another teammate". If Meta rejects the answer, the call can ring on or be retried. Accepting also tells the AI agent to stand down, so an AI and a person don't both answer.

## AI answering & the voicemail fallback

When a call comes in, WaDesk decides who picks up. It first looks for an AI Call Assistant to attach (one pinned to the conversation, the workspace default, or the first active Live assistant). What happens next depends on whether an assistant is set up and the voice service is available:

1. Live AI pickup (the main path, when fully set up). If an assistant is found, it answers the call, speaks its greeting, and holds a real spoken conversation: it transcribes the caller's speech (with Deepgram), sends it to the AI model you chose, turns the reply into a voice (with ElevenLabs), and plays it back — on a loop. Once the AI claims the call, the voicemail timer below stands down.
2. Voicemail fallback. If no assistant is set up, the voice service is unavailable, or the Deepgram / ElevenLabs keys are missing, the call is declined so the customer stops ringing. After a short wait (15 seconds by default), the fallback fires: WaDesk declines the call and sends a spoken voicemail voice note over chat ("Sorry we missed your call — please reply and we'll get back to you"). The wording comes from the assigned voice agent, and a note is added to the conversation so the operator can see what the AI said. The voice note is only sent when a voice-enabled AI agent exists for the workspace or conversation; otherwise the call is simply declined and logged as missed.

> Prerequisites for live AI answering. Live spoken pickup requires: an AI Call Assistant set up and active; the AI Voice Agent plan feature; the voice service running; and Deepgram (transcription) + ElevenLabs (voice) keys set in Admin → API Keys. If any piece is missing, the system falls back to the voicemail voice note rather than answering silently. An operator clicking Accept always overrides the AI — only one of operator / AI / voicemail ever handles a given call.

## Call recording (3-way) & transcript

Recording applies to AI-answered calls and is set per assistant in the AI Call Assistant's routing step, and needs the Call Recording plan feature. Two independent switches control which audio is captured:

- Record agent — the AI's spoken side.
- Record caller — the customer's side.

During a live AI call each side is saved separately. When both are on you get a 3-way result in Call Logs: an agent track, a caller track, and a combined "Play recording" mix. The transcript is captured automatically — every turn (caller and agent) is saved as it happens and assembled turn-by-turn for the log, alongside any skills the AI used mid-call. Recordings are only saved for calls the AI actually handled; operator-handled calls have no recorder, so no broken players appear.

Everything captured for a call — recordings, transcript, the mid-call skill timeline, duration, status, and cost — is recorded in the call log from the first ring (status "in progress") and finalised when the call ends. Each call action is also logged so a call's full history can be reviewed for support or audit.

> Privacy & retention. Recordings and transcripts can capture sensitive caller information. Only enable the recording toggles you actually need, keep workspace access limited, and review your retention and consent obligations for your jurisdiction.

## Where to find call records

WhatsApp Calling itself is where the live action happens — placing, answering, and ending calls. To review what happened afterwards, go to Call Logs (under More). There you get one row per call with the caller, direction, duration, status, and cost, plus the full detail: transcript, recordings (agent / caller / mixed), the skills the AI used mid-call, and a jump back into the linked conversation in Team Inbox. Call Logs needs the same WhatsApp Calling plan feature as calling.

## Troubleshooting

Symptom | Cause & fix
--- | ---
No Call button in Team Inbox | The number isn't calling-enabled, your plan lacks WhatsApp Calling, or you're not on a WABA conversation. Enable calling on the number and check the plan.
Incoming calls never ring | The calls webhook isn't subscribed or points at the wrong URL. Verify it's `https://YOUR-DOMAIN/webhooks/wa-calling` and the verify token matches.
Webhook returns a "server misconfigured" error | The WABA app secret isn't set. Set it in Admin → Settings → WhatsApp Message — it's required to confirm the webhook is genuine.
"Microphone access blocked" | The browser denied mic access. Allow it for the site and try again; the call stops on purpose rather than going one-way.
Outbound call refused | No active calling permission for that contact. Send a permission request and wait for the customer to accept (it expires, so you may need to re-ask).
"Already accepted by another teammate" | Expected on a shared inbox — someone else picked up the ringing call first.
Caller hears silence on an AI call, then voicemail | The voice keys (Deepgram / ElevenLabs) or the voice service are missing, so the call fell back to voicemail. Make sure the voice service is running and the keys are set in Admin → API Keys.
AI didn't answer, only voicemail | No active AI Call Assistant was found, or the AI Voice Agent feature is off. Set up and activate an assistant.
Recording player is empty | Recording switches were off for that assistant, or the call was handled by a person (no recorder). Turn on Record agent / Record caller and confirm the Call Recording plan feature.