WhatsApp Messaging Channel

WhatsApp supports two intake modes:

• cloud uses the official Meta WhatsApp Cloud API with a SurfSense-owned system WhatsApp Business Account.
• baileys uses the unofficial Baileys WebSocket bridge for self-hosted, one-tenant Message Yourself installs.

Use cloud for production and shared deployments.

Meta Cloud API

Create a Meta app, provision a WhatsApp Business Account and phone number, and create a long-lived system user token with WhatsApp permissions.

Point the Meta app webhook to:

${GATEWAY_BASE_URL}/api/v1/gateway/webhooks/whatsapp

Set the webhook verify token in Meta to the same value as WHATSAPP_WEBHOOK_VERIFY_TOKEN.

For Docker installs, add these to docker/.env. For manual installs, add them to surfsense_backend/.env.

GATEWAY_WHATSAPP_INTAKE_MODE=cloud
WHATSAPP_SHARED_BUSINESS_TOKEN=your-system-user-token
WHATSAPP_SHARED_PHONE_NUMBER_ID=your-meta-phone-number-id
WHATSAPP_SHARED_DISPLAY_PHONE_NUMBER=15551234567
WHATSAPP_SHARED_WABA_ID=your-waba-id
WHATSAPP_GRAPH_API_VERSION=v25.0
WHATSAPP_WEBHOOK_VERIFY_TOKEN=generate-a-long-random-secret
WHATSAPP_WEBHOOK_APP_SECRET=your-meta-app-secret

Users open User Settings > Messaging Channels, click Pair WhatsApp, and open the returned wa.me link. WhatsApp pre-fills /start CODE; the user must press send to bind the chat.

Baileys Self-Hosted Mode

Baileys is unofficial. Use it only for single-tenant self-hosted installs where the operator accepts the risk of a personal WhatsApp session bridge.

GATEWAY_WHATSAPP_INTAKE_MODE=baileys
WHATSAPP_BRIDGE_URL=http://whatsapp-bridge:9929
WHATSAPP_MODE=self-chat
docker compose --profile whatsapp up -d

After pairing, use WhatsApp's Message Yourself chat. The bridge only forwards messages from your own self-chat and ignores groups, other chats, and other people.

The whatsapp-bridge container stores Baileys auth state in the surfsense-whatsapp-sessions Docker volume. That volume contains account takeover material. Treat it like a secret.

To intentionally reset pairing:

docker compose --profile whatsapp down
docker volume rm surfsense-whatsapp-sessions
docker compose --profile whatsapp up -d