WhatsApp channel

Module id: whatsapp · Kind: channel · Configured by: WHATSAPP_ENABLED=true + WHATSAPP_ACCESS_TOKEN · Healthy when: WHATSAPP_WEBHOOK_VERIFY_TOKEN is set too · Capability: channel_whatsapp

The same assistant, the same knowledge base, the same model policy — on WhatsApp. This module connects Synaplan to the WhatsApp Business API (Meta Cloud API): messages sent to your business number are answered by the assistant you choose, with media, voice notes and up to twenty numbers on one installation. Off by default.

Full setup guide with tokens, user tiers and troubleshooting: docs/WHATSAPP.md in the main repository; the channel overview is on Channels. This page is the module view.

What it adds

  • The inbound webhook POST /api/v1/webhooks/whatsapp and Meta's verification handshake on the same URL.
  • Channels → WhatsApp Channel(s) in the web app: pick the published assistant that answers incoming messages ("No assistant — use the usual chat" keeps default routing), and let users verify their phone number for higher limits.
  • Bidirectional messaging, multiple numbers without extra configuration (the response goes back through the number that received the message), images / audio / video / documents, voice-note transcription through Whisper, and anonymous use — people writing in do not need an account.

Without it

The Channels page replaces the WhatsApp card and the phone-verification block with a short "WhatsApp channel is not available on this installation" notice and a How to enable it link to this page; admins also get Open feature status. E-mail, the widget, Synamail, Desktop and MCP are independent and unaffected.

When the module is absent and its gate is on, the inbound POST webhook, the assistant-binding routes and the phone-verification request/confirm/remove routes answer 404 feature_not_configured. Meta's GET verification handshake is never gated — it is the very step that makes the channel configured — and the read-only phone-verification status used by the profile page stays available.

How to enable

1. WhatsApp Business account at Meta

In Meta Business Suite create or select a business, add WhatsApp, and copy a permanent access token from the API settings (a temporary token expires after 24 hours). Note the phone number you will use.

2. Environment

Add to the backend environment (backend/.env, or deploy/.env for the production contract) and restart backend + worker:

WHATSAPP_ENABLED=true
WHATSAPP_ACCESS_TOKEN=EAAB…                  # Meta access token
WHATSAPP_WEBHOOK_VERIFY_TOKEN=pick-a-long-random-string
# WHATSAPP_GRAPH_API_BASE_URL=              # only to pin a Graph API version or a proxy

3. Webhook at Meta

Meta Business Settings → WhatsApp → Configuration:

Setting Value
Callback URL https://<your-domain>/api/v1/webhooks/whatsapp
Verify token the value of WHATSAPP_WEBHOOK_VERIFY_TOKEN
Subscribe to messages

Meta calls the URL with hub.verify_token; Synaplan compares it with yours and echoes the challenge. The server must be reachable from the internet over HTTPS.

4. Choose the assistant

Web app → Channels → WhatsApp Channel(s) → Assistant for WhatsApp: pick a published assistant, or leave it on the usual chat. Send "hello" to your business number.

Check it works

  • Operate → Feature Status → WhatsApp channel:
    • Available / WhatsApp channel enabled.
    • Needs setup / WhatsApp enabled but webhook verify token missing — Meta cannot complete the handshake. Set WHATSAPP_WEBHOOK_VERIFY_TOKEN.
    • Not installed / Missing: WHATSAPP_ENABLED, WHATSAPP_ACCESS_TOKEN, … — the module is off. The message names the keys, never their values.
  • Meta's Configuration page shows the webhook as verified.
  • A message to the number gets an answer; docker compose logs -f backend worker shows the inbound event.

Configuration reference

Variable Default Meaning
WHATSAPP_ENABLED false Master switch.
WHATSAPP_ACCESS_TOKEN empty Meta access token. Required for configured.
WHATSAPP_WEBHOOK_VERIFY_TOKEN empty Shared secret for Meta's verification handshake. Required for healthy.
WHATSAPP_GRAPH_API_BASE_URL empty (library default) Override the Graph API base URL — version pinning or an egress proxy.

Per-user settings (assistant binding, phone verification) are stored in the database and edited on the Channels page.

Troubleshooting

  • Meta says the callback URL could not be verified. The GET handshake did not reach the backend or the tokens differ: check HTTPS, the reverse proxy path /api/v1/webhooks/whatsapp, and that the verify token matches exactly.
  • Handshake works, messages do not arrive. The messages field is not subscribed, or the module is absent while its gate is on (the POST then answers 404 — Feature Status shows why).
  • Answers stop after a day. You used a temporary token. Create a permanent one for a system user in Meta Business Settings.
  • Voice notes are not understood. Transcription needs a speech-to-text model: local Whisper (in the production contract it comes with the local-ai profile) or a cloud speech-to-text model from one of your providers.

Related

  • Channels — WhatsApp and e-mail overview, other ways to connect
  • Assistants — publishing the assistant that answers on WhatsApp
  • Feature modules — states, gates, the CLI