Skip to main content

​
Overview

WhatsAppTransport enables real-time voice conversations between WhatsApp users and your Pipecat bot through the WhatsApp Business API. When users call your WhatsApp Business number, the transport handles webhook events, establishes WebRTC connections, and manages the voice call lifecycle. The transport integrates with Meta’s WhatsApp Cloud API to receive incoming calls, process WebRTC signaling, and maintain call state throughout the conversation.

WhatsApp API Reference

API methods for Pipecat’s WhatsApp Cloud API integration

WhatsApp Client Reference

Pipecat’s Client for handling webhooks and WebRTC connections

Example Implementation

Complete WhatsApp voice bot example

WhatsApp Business API Docs

Meta’s official WhatsApp calling documentation

​
Installation

To use WhatsAppTransport, install the required dependencies: 
pip install "pipecat-ai[webrtc]"

​
Prerequisites

​
WhatsApp Business API Setup

Before using WhatsAppTransport, you need:
  1. WhatsApp Business API Account: Set up through Meta Developer Console
  2. Phone Number Configuration: Enable voice calling capability for your business number
  3. Webhook Configuration: Configure webhook endpoint to receive call events
  4. Access Tokens: Generate API access token and phone number ID
For development, Meta provides free test phone numbers valid for 90 days. Production use requires business verification.

​
Required Environment Variables

  • WHATSAPP_TOKEN: WhatsApp Business API access token
  • WHATSAPP_PHONE_NUMBER_ID: Your business phone number ID
  • WHATSAPP_WEBHOOK_VERIFICATION_TOKEN: Token for webhook verification

​
Key Features

  • Incoming Call Handling: Automatically accepts WhatsApp voice calls
  • WebRTC Integration: Establishes peer-to-peer audio connections
  • Webhook Processing: Handles Meta’s webhook events for call lifecycle
  • Call Management: Supports call acceptance, rejection, and termination
  • Real-time Audio: Bidirectional audio streaming for natural conversations

​
Configuration

​
WhatsAppClient

WhatsAppClient is the main class for handling WhatsApp call connections. It manages webhook processing, WebRTC connection establishment, and call lifecycle.
​
whatsapp_token
str
required
WhatsApp Business API access token for authentication.
​
phone_number_id
str
required
WhatsApp Business phone number ID.
​
session
aiohttp.ClientSession
required
An aiohttp session for making async HTTP requests to the WhatsApp Cloud API.
​
ice_servers
List[IceServer]
default:"None"
List of ICE servers for WebRTC connections. If None, defaults to Google’s public STUN server (stun:stun.l.google.com:19302).
​
whatsapp_secret
str
default:"None"
WhatsApp App Secret for validating that webhook requests came from WhatsApp. When set, all incoming webhooks are verified using HMAC SHA-256 signature validation.

​
Usage

WhatsAppTransport requires a webhook server to handle incoming calls and a bot implementation to process the conversations. The transport works with SmallWebRTCTransport under the hood for WebRTC connectivity. The WhatsAppClient handles the WhatsApp-specific webhook processing and call management, while the actual audio transport uses a SmallWebRTCConnection for each call. See the complete example for a full implementation including:
  • FastAPI webhook server with verification endpoint
  • WhatsApp client configuration
  • Bot integration with Pipecat pipeline using SmallWebRTCTransport
  • Environment setup and deployment

​
Notes

  • WhatsApp only supports SHA-256 fingerprints in SDP, so the client automatically filters out other fingerprint types.
  • Each incoming call creates a new SmallWebRTCConnection that can be used with SmallWebRTCTransport.
  • The client supports both pre_accept and accept call flow as required by the WhatsApp Cloud API.
  • Use terminate_all_calls() during shutdown to cleanly end all ongoing calls.

​
Additional Resources