Enable SurfSense chat from WhatsApp
WhatsApp Messaging Channel
WhatsApp supports two intake modes:
clouduses the official Meta WhatsApp Cloud API with a SurfSense-owned system WhatsApp Business Account.baileysuses 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/whatsappSet 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-secretUsers 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 -dAfter 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