WhatsApp Integration
Connect WhatsApp to Mopheus using Linked-Device QR pairing or the Meta WhatsApp Business Cloud API.
The WhatsApp integration connects an agent or team to WhatsApp through two supported modes:
- Linked Device (QR Code) (
linked_device): Pairs Mopheus as a WhatsApp companion device over the WhatsApp multi-device WebSocket protocol (whatsmeow) with end-to-end Signal encryption persisted in PostgreSQL. No public webhook URL is required. - Meta Business Cloud API (
cloud_api): Connects an official Meta WhatsApp Business Platform number via HTTPS webhooks (/api/v1/whatsapp/callback/{installationId}) and Graph APIv21.0.
Once configured, agents respond to WhatsApp messages, and ticket status changes and comments are pushed back to the originating WhatsApp conversation.
Connection Method Comparison
| Capability | Linked Device (self_chat) | Linked Device (bot) | Meta Business Cloud API (cloud_api) |
|---|---|---|---|
| Public callback URL | Not required | Not required | Required (/api/v1/whatsapp/callback/{installationId}) |
| Direct messages | Message Yourself chat only (FromMe && Chat == OwnJID) | External 1:1 chats (!FromMe, loop-protected) | External 1:1 chats (messages[] webhook) |
| Group chats | Ignored (Note-to-Self only) | @-mention, quote-reply to bot, or / command required | Direct 1:1 chats only |
| Inbound media | Images, documents, audio/voice, video (Signal E2E decrypted) | Images, documents, audio/voice, video (Signal E2E decrypted) | Images, documents, audio/voice, video (Graph API media download) |
| Processing indicator | Composing presence | Composing presence | Read receipt (status: read) + typing indicator (typing_indicator) |
| Multi-replica support | Single active supervisor lease per installation | Single active supervisor lease per installation | Stateless HTTP webhook + outbound queue |
System Prerequisites
In Admin → System Config, configure:
| Setting | Value |
|---|---|
Enable WhatsApp (whatsapp_enabled) | true |
WhatsApp Secret Key (whatsapp_secret_key) | A base64-encoded 32-byte AES key used to encrypt stored WhatsApp Cloud API credentials and per-installation device_dek keys (which encrypt whatsapp_device_state.state_value). Click Generate in System Config to create or rotate the key. |
Rotating
whatsapp_secret_keyvia the Generate button in System Config re-encrypts all existing WhatsApp installation secrets and envelope DEKs in a single transaction.
Setup
1. Linked Device (QR Code)
- Open an agent or team detail page → Integrations → Connect WhatsApp.
- Select Linked Device (QR Code) and choose a Message Handling Mode:
- Self-Chat Only (
self_chat, Recommended): Strictly processes messages you send in your own Message Yourself chat (FromMe == trueand chat JID equals your own account JID/LID). Messages from external contacts and group chats are ignored, and your own account is bound automatically upon pairing. - Dedicated Bot Number (
bot): Processes incoming direct messages from external users (!FromMe) and group messages that@-mention, quote-reply, or send a/command to the bot number, while ignoring outbound replies tracked by Mopheus's loop-protection tracker.
- Self-Chat Only (
- Click Generate QR Code.
- On your phone, open WhatsApp → Settings → Linked Devices → Link a Device and scan the QR code displayed in Mopheus. The QR code refreshes automatically every 20 seconds while waiting for scan.
- Once paired, Mopheus encrypts and persists the device's Signal store in PostgreSQL and automatically reconnects under the channel supervisor lease.
2. Meta WhatsApp Business Cloud API
- In the Meta App Dashboard, configure the WhatsApp product for your business app and obtain:
- Phone Number ID (
phoneNumberId, digits only) - WhatsApp Business Account ID (
wabaId, optional) - Permanent System User Access Token (
accessToken) - App Secret (
appSecret, used to verifyX-Hub-Signature-256)
- Phone Number ID (
- In Mopheus, open an agent or team detail page → Integrations → Connect WhatsApp, select Business Cloud API, and submit the credentials.
- Mopheus generates a webhook Callback URL (
{APP_URL}/api/v1/whatsapp/callback/{installationId}) and a Verify Token (if you did not specify a custom one). - Copy the Callback URL and Verify Token into your Meta App Dashboard under WhatsApp → Configuration → Webhook, and subscribe to the
messageswebhook field.
Account Binding and Verification
When an external WhatsApp sender messages the connected agent or team for the first time, Mopheus replies with a one-time binding link (/whatsapp/bind?token=...). After signing in to Mopheus and confirming the binding, subsequent messages from that WhatsApp user are routed to the assigned agent or team.
- Inbound and outbound Markdown is automatically converted to WhatsApp-native formatting (
*bold*,_italic_,~strikethrough~, triple-backtick code blocks) and split into 4000-character chunks when needed. - Inbound media attachments (up to 20 MiB) are downloaded, verified, and attached to the Mopheus chat session.
DingTalk Integration
Connect a DingTalk Stream robot to Mopheus so people can work with agents and receive ticket updates in DingTalk.
GitHub Integration
Connect GitHub repositories to Mopheus via webhooks. Receive push, PR, and issue events, sync git entities to tickets, and let agents work with your code.