WhatsApp Transport

Overview

WhatsAppClient 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 client 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 WhatsAppClient, install the required dependencies:

uv add "pipecat-ai[webrtc]"

Prerequisites

WhatsApp Business API Setup

Before using WhatsAppClient, you need:

WhatsApp Business API Account: Set up through Meta Developer Console
Phone Number Configuration: Enable voice calling capability for your business number
Webhook Configuration: Configure webhook endpoint to receive call events
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.

str

required

WhatsApp Business API access token for authentication.

str

required

WhatsApp Business phone number ID.

aiohttp.ClientSession

required

An aiohttp session for making async HTTP requests to the WhatsApp Cloud API.

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).

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, so pass the raw request body and the X-Hub-Signature-256 header to handle_webhook_request() as raw_body and sha256_signature; a webhook without them raises.

Usage

WhatsAppClient requires a webhook server to handle incoming calls and a bot implementation to process the conversations. It 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.

Connection Callback Signature

When handling webhook requests, you provide a connection callback that receives the established WebRTC connection and call metadata:

from pipecat.transports.smallwebrtc.connection import SmallWebRTCConnection
from pipecat.transports.whatsapp.api import WhatsAppConnectCall

async def connection_callback(
    connection: SmallWebRTCConnection,
    call: WhatsAppConnectCall
):
    # Access caller information
    caller_number = call.from_  # Caller's phone number
    call_id = call.id
    direction = call.direction  # "inbound" or "outbound"

    # Spawn your bot with the connection
    await spawn_bot(connection, call)

The WhatsAppConnectCall object contains:

from_: Caller’s phone number
to: Called phone number
id: Unique call identifier
direction: Call direction (“inbound” or “outbound”)
timestamp: Call timestamp

The single-argument connection_callback(connection) signature is deprecated as of Pipecat 1.4.0. Update your callbacks to accept both connection and call arguments to receive caller metadata. The old signature still works but emits a DeprecationWarning.

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

Methods

handle_verify_webhook_request()

async def handle_verify_webhook_request(
    self, params: dict[str, str], expected_verification_token: str
) -> int

Returns the hub.challenge of Meta’s webhook verification request, for the endpoint to send back. params are the request’s query parameters. Raises ValueError when a parameter is missing, hub.mode isn’t "subscribe", or hub.verify_token doesn’t match expected_verification_token.

handle_webhook_request()

async def handle_webhook_request(
    self,
    request: WhatsAppWebhookRequest,
    connection_callback: Callable[..., Awaitable[None]] | None = None,
    raw_body: bytes | None = None,
    sha256_signature: str | None = None,
) -> bool

Handles a call webhook: a connect event answers the call with a new SmallWebRTCConnection and passes it to connection_callback, and a terminate event disconnects the call. Returns True when the event was handled, and False when ending a call fails. Raises ValueError when the request has no connect or terminate event, and Exception when the signature check or answering the call fails. An exception in connection_callback is logged, not raised.

Parameter	Type	Default	Description
`request`	`WhatsAppWebhookRequest`	(required)	The webhook’s JSON body
`connection_callback`	`Callable[..., Awaitable[None]] \| None`	`None`	Called with each new connection and its call. See Connection Callback Signature
`raw_body`	`bytes \| None`	`None`	The raw request body, checked against the signature when `whatsapp_secret` is set
`sha256_signature`	`str \| None`	`None`	The request’s `X-Hub-Signature-256` header

terminate_all_calls()

async def terminate_all_calls() -> None

Ends every ongoing call through the WhatsApp API and disconnects its connection. Call it when your server shuts down.

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.

Additional Resources

Events Overview - Overview of all events in Pipecat
SmallWebRTCTransport - The underlying transport used for WebRTC connectivity
WhatsApp Cloud API Calling Docs - Official WhatsApp calling documentation

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

WhatsApp Transport

Overview

WhatsApp API Reference

WhatsApp Client Reference

Example Implementation

WhatsApp Business API Docs

Installation

Prerequisites

WhatsApp Business API Setup

Required Environment Variables

Key Features

Configuration

WhatsAppClient

Usage

Connection Callback Signature

Methods

handle_verify_webhook_request()

handle_webhook_request()

terminate_all_calls()

Notes

Additional Resources

​Overview

WhatsApp API Reference

WhatsApp Client Reference

Example Implementation

WhatsApp Business API Docs

​Installation

​Prerequisites

​WhatsApp Business API Setup

​Required Environment Variables

​Key Features

​Configuration

​WhatsAppClient

​Usage

​Connection Callback Signature

​Methods

​handle_verify_webhook_request()

​handle_webhook_request()

​terminate_all_calls()

​Notes

​Additional Resources

Overview

Installation

Prerequisites

WhatsApp Business API Setup

Required Environment Variables

Key Features

Configuration

WhatsAppClient

Usage

Connection Callback Signature

Methods

handle_verify_webhook_request()

handle_webhook_request()

terminate_all_calls()

Notes

Additional Resources