WhatsApp

Customer messages WhatsApp number → Meta POSTs /webhooks/whatsapp → validate X-Hub-Signature-256 → resolve phone → agent → create/resume session (24h TTL) → build LLM history → chat completion → send reply via WhatsApp Cloud API

Customer calls WhatsApp number → Meta POSTs /webhooks/whatsapp (field: "calls") → validate signature → Pipecat WhatsAppClient handles WebRTC (SDP offer/answer) → pre-accept + accept call via Cloud API → Pipecat pipeline (16kHz) → on "terminate" event: cleanup

Setup

Configure environment variables

WHATSAPP_TOKEN=your-access-token
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
WHATSAPP_APP_SECRET=your-app-secret
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-verify-token

Set up Meta webhook

In the Meta Developer Console:

Callback URL: https://your-host/webhooks/whatsapp
Verify Token: must match WHATSAPP_WEBHOOK_VERIFY_TOKEN
Subscribe to: messages + calls

Enable WhatsApp on phone number

curl -X POST http://localhost:8090/v1/phone-numbers \
  -H "Authorization: Bearer tc_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_number_sid": "PNxxx",
    "e164_number": "+15551234567",
    "whatsapp_enabled": true,
    "routing_target_type": "agent",
    "routing_target_id": "AGENT_ID"
  }'

Credentials

Get these from the Meta Developer Console:

Variable	Where to Find
`WHATSAPP_TOKEN`	WhatsApp > API Setup > Access Token
`WHATSAPP_PHONE_NUMBER_ID`	WhatsApp > API Setup > Phone Number ID
`WHATSAPP_APP_SECRET`	App Settings > Basic > App Secret (32 hex chars)
`WHATSAPP_WEBHOOK_VERIFY_TOKEN`	Any string you choose

The app must be in live mode for public access. Development mode requires test numbers.

Getting Started

Guides

WhatsApp Text Flow

WhatsApp Voice Flow

Setup

Credentials

​WhatsApp Text Flow

​WhatsApp Voice Flow

​Setup

​Credentials

WhatsApp Text Flow

WhatsApp Voice Flow

Setup

Credentials