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

# WhatsApp Business Calling API

> Learn how to receive WhatsApp voice calls in your Pipecat application

## Overview

This guide explains how to integrate WhatsApp Business voice calling into your Pipecat application using the **WhatsApp Cloud API** and **SmallWebRTC**. Once configured, your Pipecat bot will be able to receive and handle real-time voice calls directly from WhatsApp users.

## Prerequisites

### WhatsApp Business Setup

Before proceeding, ensure you have completed the following steps:

1. **Facebook Account** — Create one at [facebook.com](https://facebook.com)
2. **Facebook Developer Account** — Register at [developers.facebook.com](https://developers.facebook.com)
3. **WhatsApp Business App** — Create a new app via [Meta for Developers](https://developers.facebook.com/apps)
4. **Phone Number** — Add and verify a WhatsApp Business phone number
5. **Business Verification** — Required for production environments
6. **Webhook Configuration** — You’ll need a public webhook URL to receive call events

> **Note**: Voice calling is only available for WhatsApp Business API numbers with calling capability enabled.

For reference:

* [WhatsApp Cloud API Getting Started](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/)
* [Voice Calling API Documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/)
* [Webhook Setup](https://developers.facebook.com/docs/whatsapp/webhooks/)

## WhatsApp Configuration

> **Note**: For these settings you must be logged into your **Meta Developer Console** and inside your **App**.

### 1. Enable Voice Calls

To enable voice calls for your number:

* Go to **WhatsApp** → **Configuration → Phone Numbers → Manage Phone Numbers**
* Select your WhatsApp number
* Under the **Calls** tab, enable **“Allow voice calls”**
* Save the configuration

> For development, Meta provides a **free test number** valid for **90 days**.

### 2. Configure Webhook

Set up your webhook to receive **WhatsApp call events**.

1. In the **Meta Developer Console**, go to
   **WhatsApp → Configuration → Webhooks**

2. **Set your callback URL** — this is where WhatsApp will send incoming call notifications.

   #### For local development

   * Make sure your local Pipecat server is running (e.g. `http://localhost:7860`).
   * Use **ngrok** (or a similar tunneling tool) to expose your local server:
     ```bash theme={null}
     ngrok http --domain=YOUR_NGROK_DOMAIN http://localhost:7860
     ```
   * Copy the generated HTTPS URL and set your webhook to:
     `https://YOUR_NGROK_DOMAIN/whatsapp`
   * ✅ **Important:** Always include the `/whatsapp` path at the end of your webhook URL.

   #### For Pipecat Cloud

   * Ensure your Pipecat agent is already **deployed and running**.
   * Use the following format for your webhook URL:
     ```
     https://api.pipecat.daily.co/v1/public/webhooks/$ORGANIZATION_ID/$AGENT_NAME/whatsapp
     ```
   * ✅ **Important:** Always include the `/whatsapp` path at the end of your webhook URL.

3. **Enter your Verify Token**
   * For **local development**, set the environment variable
     `WHATSAPP_WEBHOOK_VERIFICATION_TOKEN` to match the verify token you enter in Meta.
   * For **Pipecat Cloud**, set the verify token to your **public API key**.

4. Click **Verify and Save** to confirm your webhook setup.

5. Under **Webhook Fields**, enable the following event type:
   * `calls` → *(required to receive voice call events)*

### 3. Configure Access Token

1. Go to **WhatsApp → API Setup**
2. Click **Generate Access Token**
3. Use the generated token as your `WHATSAPP_TOKEN` environment variable (or secret)
4. Note your **Phone Number ID** and configure it as `PHONE_NUMBER_ID`

> This will create a temporary access token, which usually expires in less than 02 hours.

> To create a permanent access token, you can follow [this document](https://developers.facebook.com/blog/post/2022/12/05/auth-tokens/) from Meta.

### 4. Configure App secret

1. Go to **App settings → Basic**
2. Click to show your **App secret**
3. Use the app secret as your `WHATSAPP_APP_SECRET` environment variable (or secret)

> This secret is used to verify that the webhooks you receive are actually from WhatsApp.

## Pipecat Integration

WhatsApp works with any bot using `SmallWebRTCTransport`.

All you need to do is configure WhatsApp as described above and provide the correct environment variables when starting your Pipecat bot.

Make sure your `.env` file includes:

```bash theme={null}
WHATSAPP_TOKEN=
WHATSAPP_PHONE_NUMBER_ID=
WHATSAPP_APP_SECRET=

# Only needed for local development
WHATSAPP_WEBHOOK_VERIFICATION_TOKEN=pk_**
```

> If you are using Pipecat Cloud, you must configure these values as secrets.

### Example

```python theme={null}
transport = SmallWebRTCTransport(
    webrtc_connection=webrtc_connection,
    params=TransportParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
    ),
)
```

## Testing the Integration

1. From the WhatsApp app, call your registered WhatsApp Business number.
2. The call will be routed to your Pipecat application.
3. Your bot should automatically answer and begin the conversation.

## Full demo

<Card horizontal title="Demo" icon="play" href="https://github.com/pipecat-ai/pipecat-examples/tree/main/p2p-webrtc/pipecat-cloud">
  Pipecat Cloud WhatsApp Demo
</Card>

## Troubleshooting

Common issues and their solutions:

1. **Expired WhatsApp Token**

   ```bash theme={null}
   Error validating access token
   ```

   * Generate a new access token under **WhatsApp → API Setup**, then update your `WHATSAPP_TOKEN` and redeploy your agent.

2. **Webhook Verification Failed**
   * Ensure the verify token in Meta Developer Console matches your environment variable.
   * If using Pipecat Cloud, it must be your public API key.
   * Confirm that your webhook URL is publicly accessible.

3. **Bot Not Answering Calls**
   * Verify your phone number has calling enabled.
   * Check that your environment variables are correctly set.
   * Ensure Pipecat is running and reachable.

## Notes

* Voice calling requires WhatsApp Business API access.
* Test phone numbers are valid for 90 days in development mode.
* Production deployment requires verified business credentials.

## References

* [WhatsApp Cloud API – Getting Started](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/)
* [Voice Calling API Docs](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/)
* [Webhook Configuration](https://developers.facebook.com/docs/whatsapp/webhooks/)
* [SDP Overview & Examples](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/reference#sdp-overview-and-sample-sdp-structures)