apunkt/SurfSense
1
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2026-06-06 20:15:17 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(messaging): introduce comprehensive setup docs for Telegram, WhatsApp, Slack, and Discord messaging channels

Browse source
This commit is contained in:
Anish Sarkar 2026-06-02 00:25:49 +05:30
parent 20994671bc
commit ebddf4506a
14 changed files with 530 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

75
surfsense_web/content/docs/messaging-channels/whatsapp.mdx Normal file
View file

@ -0,0 +1,75 @@
---
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
```