Skip to main content

​
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
  2. Facebook Developer Account — Register at developers.facebook.com
  3. WhatsApp Business App — Create a new app via Meta for Developers
  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 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: 
      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_NAME/$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 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: 
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

transport = SmallWebRTCTransport(
    webrtc_connection=webrtc_connection,
    params=TransportParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(),
    ),
)

​
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

Demo

Pipecat Cloud WhatsApp Demo

​
Troubleshooting

Common issues and their solutions:
  1. Expired WhatsApp Token 
    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