> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soneka.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Calling: Place & Receive Voice Calls in Soneka

> Enable real WhatsApp voice calls on your WABA numbers — dial customers, accept incoming calls, hand off to AI, and record everything, all from the browser.

**WhatsApp Calling** lets your workspace place and receive real WhatsApp voice calls straight 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 the [Team Inbox](/features/team-inbox) whenever you're working a conversation on a calling-enabled number. The full archive of recordings and transcripts lives in [Call Logs](/features/call-logs).

<Info>
  **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. See [Connect Your WhatsApp Number](/connect-whatsapp).
</Info>

## 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.                                                                                     |
| 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`. |
| Browser microphone             | The operator's browser must allow microphone access.                                                                                        |
| Customer permission (outbound) | To call a customer, they must have given calling permission first.                                                                          |

<Warning>
  **The crown badge.** WhatsApp Calling and [Call Logs](/features/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 [AI Call Assistant](/features/ai-call-assistant).
</Warning>

## Configure the calling webhook

Meta sends call events to Soneka over a dedicated webhook, separate from the messages webhook.

<Steps>
  <Step title="Set the callback URL">
    `https://YOUR-DOMAIN/webhooks/wa-calling`
  </Step>

  <Step title="Set the verify token">
    Use the value your admin set under **Admin → Settings → WhatsApp Message**. Meta's verification check only passes when this matches.
  </Step>

  <Step title="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, Soneka refuses the webhook outright (there's no bypass, because each call changes your workspace's data).
  </Step>

  <Step title="Subscribe the calls field">
    In Meta's webhook settings, subscribe your WhatsApp Business Account to the **calls** field.
  </Step>
</Steps>

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. Soneka 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, Soneka 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.

<Info>
  **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 below).
</Info>

## Outbound dialling

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

<Steps>
  <Step title="Your browser turns on the mic">
    And sets up the call connection.
  </Step>

  <Step title="Soneka 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.
  </Step>

  <Step title="The on-call panel appears">
    With a live timer. When the customer answers, the audio connects. Use **Mute** and **Hang up** from the panel.
  </Step>
</Steps>

<Warning>
  **Customer consent is required first.** WhatsApp doesn't let a business cold-call a user. The customer must have granted calling permission, which Soneka 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.
</Warning>

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

* **Accept** — answer the call.
* **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. Soneka 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.

<Info>
  **Built for a shared team.** If two teammates click Accept on the same ringing call, the first one wins and the second sees "already accepted by another teammate". Accepting also tells the AI agent to stand down, so an AI and a person don't both answer.
</Info>

## AI answering & the voicemail fallback

When a call comes in, Soneka decides who picks up. It first looks for an [AI Call Assistant](/features/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).** If an assistant is found, it answers the call, speaks its greeting, and holds a real spoken conversation: it transcribes the caller's speech (Deepgram), sends it to your chosen AI model, turns the reply into a voice (ElevenLabs), and plays it back — on a loop. Once the AI claims the call, the voicemail timer stands down.
2. **Voicemail fallback.** If no assistant is set up, the voice service is unavailable, or Deepgram / ElevenLabs keys are missing, the call is declined so the customer stops ringing. After a short wait (15 seconds by default), Soneka 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. If no voice-enabled AI agent exists, the call is simply declined and logged as missed.

<Warning>
  **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, Soneka 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.
</Warning>

## Call recording (3-way) & transcript

Recording applies to AI-answered calls and is set per assistant in the [AI Call Assistant](/features/ai-call-assistant)'s routing step. It 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, alongside any skills the AI used mid-call. Recordings are only saved for calls the AI actually handled; operator-handled calls have no recorder.

Everything captured for a call — recordings, transcript, mid-call skill timeline, duration, status, and cost — is recorded from the first ring (status "in progress") and finalised when the call ends.

<Warning>
  **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.
</Warning>

## Where to find call records

WhatsApp Calling is where the live action happens — placing, answering, and ending calls. To review what happened afterwards, go to [Call Logs](/features/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 "server misconfigured"             | The WABA app secret isn't set. Set it in Admin → Settings → WhatsApp Message.                                                                                                            |
| "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 first.                                                                                                                               |
| Caller hears silence on an AI call, then voicemail | Voice keys (Deepgram / ElevenLabs) or the voice service are missing, so it fell back to voicemail. Make sure the voice service is running and keys are set in Admin → API Keys.          |
| AI didn't answer, only voicemail                   | No active AI Call Assistant, or **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. |