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

# WhatsAppTransport

> Real-time voice communication through WhatsApp Business API using WebRTC

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

<CardGroup cols={2}>
  <Card title="WhatsApp API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.transports.whatsapp.api.html">
    API methods for Pipecat's WhatsApp Cloud API integration
  </Card>

  <Card title="WhatsApp Client Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.transports.whatsapp.client.html">
    Pipecat's Client for handling webhooks and WebRTC connections
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat-examples/tree/main/whatsapp">
    Complete WhatsApp voice bot example
  </Card>

  <Card title="WhatsApp Business API Docs" icon="book" href="https://developers.facebook.com/docs/whatsapp/cloud-api/calling/">
    Meta's official WhatsApp calling documentation
  </Card>
</CardGroup>

## Installation

To use WhatsAppTransport, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[webrtc]"
```

## Prerequisites

### WhatsApp Business API Setup

Before using WhatsAppTransport, you need:

1. **WhatsApp Business API Account**: Set up through [Meta Developer Console](https://developers.facebook.com/apps)
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

<Tip>
  For development, Meta provides free test phone numbers valid for 90 days.
  Production use requires business verification.
</Tip>

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

<ParamField path="whatsapp_token" type="str" required>
  WhatsApp Business API access token for authentication.
</ParamField>

<ParamField path="phone_number_id" type="str" required>
  WhatsApp Business phone number ID.
</ParamField>

<ParamField path="session" type="aiohttp.ClientSession" required>
  An aiohttp session for making async HTTP requests to the WhatsApp Cloud API.
</ParamField>

<ParamField path="ice_servers" type="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`).
</ParamField>

<ParamField path="whatsapp_secret" type="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.
</ParamField>

## 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](https://github.com/pipecat-ai/pipecat-examples/tree/main/whatsapp) 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

* [Events Overview](/api-reference/server/events/overview) - Overview of all events in Pipecat
* [SmallWebRTCTransport](/api-reference/server/services/transport/small-webrtc) - The underlying transport used for WebRTC connectivity
* [WhatsApp Cloud API Calling Docs](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/) - Official WhatsApp calling documentation