WhatsApp

PocketPaw supports WhatsApp through two modes: Business API (requires Meta account) and Personal Mode (QR code scan, no Meta account needed).

Personal mode uses the neonize library to connect via WhatsApp Web’s multi-device protocol. Just scan a QR code — no Meta Business account, webhooks, or tunnels required.

Install

Terminal window
curl -fsSL https://pocketpaw.xyz/install.sh | sh


# Or add the WhatsApp extra manually
pip install pocketpaw[whatsapp-personal]

Configure mode

Terminal window
export POCKETCLAW_WHATSAPP_MODE="personal"

Start and scan QR

Start PocketPaw with the web dashboard:

Terminal window
pocketpaw

Open the Channels modal, go to WhatsApp, and scan the QR code with your phone.

QR Code Pairing

When using Personal mode through the web dashboard:

  1. Open the Channels modal → WhatsApp tab
  2. Select “Personal (QR)” mode
  3. Click “Start”
  4. A QR code appears — scan it with WhatsApp on your phone
  5. The bot connects to your WhatsApp account

The QR code endpoint is available at GET /api/whatsapp/qr. The frontend polls every 2 seconds until pairing completes.

Business API Mode

Business mode uses the WhatsApp Business Cloud API via Meta.

Set up Meta Business

  1. Create a Meta Business account
  2. Set up a WhatsApp Business API app
  3. Get your access token and phone number ID

Configure

Terminal window
export POCKETCLAW_WHATSAPP_MODE="business"
export POCKETCLAW_WHATSAPP_ACCESS_TOKEN="your-token"
export POCKETCLAW_WHATSAPP_PHONE_NUMBER_ID="123456"
export POCKETCLAW_WHATSAPP_VERIFY_TOKEN="your-verify-token"

Set up webhook

The dashboard exposes a webhook at /webhook/whatsapp (auth-exempt). Point Meta’s webhook configuration to your server’s public URL.

Configuration

SettingEnv VariableDescription
ModePOCKETCLAW_WHATSAPP_MODEpersonal or business
Access tokenPOCKETCLAW_WHATSAPP_ACCESS_TOKENBusiness API token
Phone number IDPOCKETCLAW_WHATSAPP_PHONE_NUMBER_IDBusiness phone number ID
Verify tokenPOCKETCLAW_WHATSAPP_VERIFY_TOKENWebhook verification token
Allowed numbersPOCKETCLAW_WHATSAPP_ALLOWED_PHONE_NUMBERSComma-separated phone numbers

Features

No Streaming

WhatsApp doesn’t support message editing, so responses are accumulated and sent as a complete message when the agent finishes.

Access Control

Terminal window
export POCKETCLAW_WHATSAPP_ALLOWED_PHONE_NUMBERS="+1234567890,+0987654321"

Session Keys

Each phone number gets a unique session: whatsapp:{phone_number}

Last updated: February 12, 2026
Edit this page