mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-06-02 19:55:18 +02:00
75 lines
2.3 KiB
Text
75 lines
2.3 KiB
Text
---
|
|
title: WhatsApp
|
|
description: Enable SurfSense chat from WhatsApp
|
|
---
|
|
|
|
# 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:
|
|
|
|
```text
|
|
${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`.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
docker compose --profile whatsapp down
|
|
docker volume rm surfsense-whatsapp-sessions
|
|
docker compose --profile whatsapp up -d
|
|
```
|