Files

gsxdsm 2c1567c6b8 FN-8418: add WhatsApp QR pairing settings

Add WhatsApp connection pairing guidance directly in plugin settings.

- Display a QR code and phone pairing instructions for WhatsApp Chat connections.
- Expose connection details through the plugin and document the setup flow.
- Add dashboard and plugin regression coverage plus a release changeset.

Files changed:
 .changeset/fn-8418-whatsapp-settings-pairing.md    |   7 +
 docs/plugin-management.md                          |   2 +-
 .../dashboard/app/components/PluginManager.tsx     |   4 +
 .../app/components/WhatsAppChatPairingPanel.css    | 115 ++++++++++++++
 .../app/components/WhatsAppChatPairingPanel.tsx    | 165 +++++++++++++++++++++
 .../components/__tests__/PluginManager.test.tsx    |  21 +++
 .../__tests__/WhatsAppChatPairingPanel.test.tsx    |  78 ++++++++++
 plugins/fusion-plugin-whatsapp-chat/README.md      |  19 +--
 .../src/__tests__/connection.test.ts               |  16 +-
 .../src/__tests__/index.test.ts                    |  33 +++++
 .../fusion-plugin-whatsapp-chat/src/connection.ts  |  21 ++-
 plugins/fusion-plugin-whatsapp-chat/src/index.ts   |  15 +-
 12 files changed, 479 insertions(+), 17 deletions(-)

Fusion-Task-Id: FN-8418

Fusion-Task-Lineage: a16b7d25-422d-4612-83d4-d5ac9c049aec

Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>

2026-07-20 00:54:01 -07:00

src

FN-8418: add WhatsApp QR pairing settings

2026-07-20 00:54:01 -07:00

CHANGELOG.md

chore(release): v0.72.0

2026-07-18 00:52:59 -07:00

manifest.json

feat(FN-3713): migrate WhatsApp plugin to Baileys pairing flow

2026-05-07 18:26:14 -07:00

package.json

chore(release): v0.72.0

2026-07-18 00:52:59 -07:00

README.md

FN-8418: add WhatsApp QR pairing settings

2026-07-20 00:54:01 -07:00

tsconfig.json

Restore PostgreSQL integration parity (#2089 )

2026-07-14 08:17:36 -07:00

vitest.config.ts

FN-6042: raise dependency security floors

2026-06-08 15:19:27 -07:00

README.md

WhatsApp Chat Plugin

WhatsApp Web (Baileys) bridge for Fusion. It pairs with your phone (QR or pairing code), keeps a background connection alive, forwards inbound direct text messages to a Fusion AI session, and sends the assistant reply back to WhatsApp.

No Meta Cloud app, webhook URL, verify token, or Graph API credentials are required.

Setup

Enable/install the plugin, then open Settings → Plugins → Fusion Plugins → WhatsApp Chat.
Use the pairing panel at the top of the plugin settings. It shows live connection status and, in QR mode, a QR code to scan from WhatsApp Linked devices.
Configure allowedSenders (empty means nobody is allowed).
Choose pairingMode:
- qr (default): scan the in-settings QR code in WhatsApp.
- code: set pairingPhoneNumber (E.164 digits without +) and use Request pairing code in the settings panel.
Wait for the panel to report connected. Use Logout / re-pair to start a fresh pairing session; if a QR is still pending, refresh or wait for a new one.

Settings

pairingMode: qr or code.
pairingPhoneNumber: E.164 digits without + (used for code mode).
allowedSenders: allowed WhatsApp JIDs or E.164 digits.
agentSystemPrompt: system prompt for replies.
historyTurnLimit: persisted turn window (default 40).
dedupeRetentionDays: replay-protection retention window for inbound message IDs (default 7 days). Rows older than this are pruned lazily whenever a new inbound message is processed.

Routes

GET /api/plugins/fusion-plugin-whatsapp-chat/status
GET /api/plugins/fusion-plugin-whatsapp-chat/qr
POST /api/plugins/fusion-plugin-whatsapp-chat/pair-code
POST /api/plugins/fusion-plugin-whatsapp-chat/logout

Storage and lifecycle

Starts socket on onLoad, stops on onUnload.
Persists transcript and dedupe state in:
- whatsapp_chat_sessions
- whatsapp_chat_dedupe
Persists Baileys auth state in:
- whatsapp_auth_creds
- whatsapp_auth_keys
After restart, plugin reconnects automatically when auth is valid.

Troubleshooting

Stuck awaiting-qr: use Refresh status in the plugin settings panel and scan the newly displayed QR promptly.
Need to re-pair: use Logout / re-pair in plugin settings; it starts a fresh QR or code pairing session.
Pair code not generated: ensure pairingPhoneNumber is E.164 digits without +, then use Request pairing code in the settings panel.
No replies: check allowedSenders; empty list blocks all inbound messages by design.

Compliance warning

Baileys is an unofficial WhatsApp Web protocol client. Use may violate WhatsApp Terms of Service. This plugin is intended for self-hosted, single-user use at your own risk.