# WhatsApp calls

> Answer calls to a Twilio WhatsApp number with a published voice agent via the whatsapp.call.inbound trigger: prerequisites, threads, errors.

A customer taps **call** in their WhatsApp chat with your number and a published
voice agent answers. Enable it with a `whatsapp.call.inbound`
[trigger](https://docs.talqing.com/integrations/triggers.md) on a Twilio [WhatsApp integration](https://docs.talqing.com/whatsapp/messaging.md).
From then on it is an ordinary voice call — recorded, analysed and billed like a
phone call, able to end the call and press keypad buttons — listed under
**Calls** as **WhatsApp**. Gupshup numbers cannot take calls.

## Prerequisites

- The number is a [WhatsApp integration](https://docs.talqing.com/whatsapp/messaging.md) on **Twilio**.
- Your WhatsApp Business Account has a **messaging limit of at least 2,000**,
  which Meta grants after Business Verification. Below it, Twilio refuses to
  turn calling on.
- The sender's **Voice Endpoint Configuration** in Twilio is empty. Talqing will
  not replace one that points at another app.
- A **published voice agent** whose `required` [variables](https://docs.talqing.com/agents/variables.md)
  all have defaults — a call carries no request to supply them.

## Turn calls on

Pick a published voice agent in the number's **Calls** cell under
**WhatsApp → Numbers**, or:

```bash
curl -X POST "https://api.talqing.com/v1/integrations/$INTEGRATION_ID/triggers" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_type": "whatsapp.call.inbound",
    "agent_id": "3b7e9d20-5a14-4c8f-b2e6-71d0c9a4f853",
    "enabled": true
  }'
```

Talqing creates a TwiML app named `Talqing WhatsApp calls +<number>` in your
Twilio account and sets it on the sender; nothing else in Twilio or Meta needs
touching. The call button then appears in the customer's chat with your number
(reopening the chat's info page shows it sooner).

Disabling the trigger, or disabling or deleting the integration, clears the
sender's voice configuration and deletes the app. Enabling the integration again
turns calling back on.

Every WhatsApp call is hosted in the `us` region, whatever the number's country.

## One thread per person

A call and an open chat with the same person are **one conversation**: the voice
agent sees the chat so far, and the text agent's next reply sees the call. A
WhatsApp call always continues their open WhatsApp chat, whatever the voice
agent's `conversation.context` says; with no open chat it joins their newest
conversation. The caller is the same `phone:<your number>:<their number>` contact
as their messages and their phone calls to that number. Every call, even one that
is refused, refreshes their 24-hour messaging window.

| Variable | Value |
| --- | --- |
| `{{userdata.whatsapp.phone}}` | The caller's number, E.164 |
| `{{userdata.whatsapp.profile_name}}` | Their WhatsApp profile name |
| `{{system_vars.human_phone_number}}` | The caller's number |
| `{{system_vars.agent_phone_number}}` | Your WhatsApp number |
| `{{system_vars.channel}}` | `whatsapp_call` |

A [batch](https://docs.talqing.com/whatsapp/creating-a-batch.md) row's columns are in userdata too. A
caller who hides their number shows as **WhatsApp user** in **Calls** and has no
phone number variables.

## Messages during a call

What the caller sends in the chat while the call is on goes to the voice agent,
not the text agent: an email address they type, a photo, a PDF. The voice agent
reads it as sent on WhatsApp and answers out loud, unless the caller is
speaking, in which case their turn picks it up. No chat reply is sent, and the
message appears in the call's transcript. Images reach the agent only if its
model can see them, and voice notes are not transcribed during a call. The same
holds on a phone call to a number that is also your WhatsApp number.

## No transfer to a phone number

Meta does not allow a WhatsApp call to be bridged to the phone network. A
[transfer](https://docs.talqing.com/tools/transfer.md) fails with
`calls on WhatsApp can't be transferred to a phone number`, and its
`on_failure` runs.

## Cost

Twilio bills the WhatsApp leg and the SIP leg to Talqing per minute, on your
Twilio account. Meta charges nothing for a call the customer starts. Talqing
charges the [voice platform fee](https://docs.talqing.com/get-started/pricing-and-credits.md), and your AI
providers bill as for any call.

## When something goes wrong

| What you see | Why |
| --- | --- |
| `400` on enable: `WhatsApp calls work only on numbers connected through Twilio` | The integration is on Gupshup |
| `400` on enable: `Calling on this number is already set up elsewhere in Twilio. Turn it off there first.` | The sender's Voice Endpoint Configuration points at another app. Clear it in Twilio, then enable again |
| `400`/`502` on enable: `could not turn on calling in Twilio: …` | Twilio refused the sender update; its message says why. Below the 2,000 messaging limit is the usual cause |
| `502` on enable: `could not set up calling on Talqing's side: …` | Retry |
| `400` on enable: `'<name>' is required and has no default, and a WhatsApp call carries no request to supply it …` | Give the variable a default or make it optional |
| `502` on disable: `Calls are off in Talqing, but Twilio refused to turn them off on the number …` | Usually a rotated Auth Token. Clear the sender's Voice Endpoint Configuration in Twilio |
| Call listed as *Calls are turned off on this WhatsApp number* | It arrived while the trigger or integration was off, usually just after turning calls off |
| Call listed as *WhatsApp did not say who was calling* | Twilio sent no caller |
| Call listed as *This workspace was out of credits* | Top up; the next call connects |
| Call listed as *Your inbound webhook did not answer* | The agent asks your [inbound webhook](https://docs.talqing.com/platform/inbound-webhook.md#refusals) and it failed; `error.message` says how |
| Call listed as *The call rang without ever connecting* | The caller hung up before the call reached the agent |

## Next

- [WhatsApp](https://docs.talqing.com/whatsapp/messaging.md): Connect the number and answer its messages.
- [Inbound calls](https://docs.talqing.com/telephony/inbound-calls.md): What any inbound voice session knows and can do.