WhatsApp Integration

This document explains how to complete WhatsApp integration, permission control, and verification in the Flocks WebUI through WhatsApp Linked Devices QR-code pairing.

Use Cases

• Trigger Rex or a specified Agent through WhatsApp direct messages.
• Receive questions in WhatsApp groups and reply with analysis results in the original conversation.
• Push Task Center, Workflow, or conversation results to fixed WhatsApp contacts or groups.
• Quickly integrate through WhatsApp Web pairing when you do not have a Meta Business account or public Webhook capability.

Prerequisites

• The server running Flocks has Node.js 18+ and npm installed. WhatsApp connects through Linked Devices QR-code pairing.
• WhatsApp is installed and logged in on the phone, which is used to scan the Linked Devices QR code.
• The deployment environment can access WhatsApp Web HTTPS / WebSocket services.
• Prepare a dedicated WhatsApp number as the bot account. Using a personal daily-use number directly is not recommended.

The WhatsApp channel relies on the WhatsApp Web protocol for authentication rather than the official Meta WhatsApp Business Cloud API. Therefore, no Meta developer account or public callback URL is required. However, WhatsApp Web protocol updates or account risk-control policy changes may interrupt the connection or require re-pairing.

Procedure

1. Open the WhatsApp Integration Page

Go to "Messaging Integrations -> WhatsApp" in the Flocks WebUI.

During first-time configuration, the "Account Connection" area shows Scan QR Code to Connect WhatsApp. If the account has already been paired, it shows the paired status and provides Rescan QR Code / Change Account.

2. Select the Running Mode

The WhatsApp channel supports two modes:

Mode	Description	Recommended Scenario
Bot mode (dedicated account)	Use a dedicated WhatsApp account as the bot account. Other users send messages to this account.	Team usage, multi-user direct messages, group chats, production environments
Personal chat	Use your own WhatsApp account and process only messages you send to yourself.	Personal testing, single-user verification

For production environments, use Bot mode (dedicated account). This reduces the risk of accidental operations and mixed account permissions, and makes allowlist, group chat, and delivery-target management easier.

3. Pair by QR Code

1. Click Scan QR Code to Connect WhatsApp.
2. The WebUI starts the local WhatsApp bridge and opens a QR code.
3. Open WhatsApp on your phone.
4. Go to Settings -> Linked Devices.
5. Tap Link a Device and scan the QR code shown in the WebUI.
6. After the WebUI shows that the connection is complete, Flocks saves the session credentials and enables or restarts the channel.

If the QR code expires, scanning fails, or you need to change accounts, click Rescan QR Code / Change Account and pair again.

4. Configure Direct Message Policy

The direct message policy controls which WhatsApp users can trigger an Agent.

Policy	Description
Open (everyone allowed)	Any user who sends a direct message to this WhatsApp account can trigger Flocks.
Allowlist (only allowed users)	Only numbers or JIDs in the Allowed users list can trigger Flocks.
Disabled (no direct messages)	WhatsApp direct messages are not processed.

Allowlist mode is recommended for production. Allowed users supports these formats:

15551234567
15551234567@s.whatsapp.net
123456789@lid

When entering phone numbers, include the country or region code and do not use spaces. Flocks normalizes them to WhatsApp JIDs at runtime.

5. Configure Group Chat Policy

The group chat policy controls whether WhatsApp group messages can trigger an Agent.

Policy	Description
Open (all groups allowed)	All WhatsApp groups that the bot has joined can trigger Flocks.
Allowlist (only allowed groups)	Only groups in the Allowed group JID list can trigger Flocks.
Disabled (no group chats)	WhatsApp group chat messages are not processed.

Group JIDs usually end with @g.us, for example:

120363000000000000@g.us

Keep group trigger mode set to trigger only on @ mention or bot reply. Change it to trigger on all messages only when you clearly need to process every group message; otherwise, a large number of irrelevant messages can trigger the Agent.

6. Adjust Advanced Settings

The default configuration usually works as is. Advanced settings are needed only when there is a port conflict, long-message experience issue, or slow network.

Configuration Item	Default / Description
Session directory	Default ~/.flocks/workspace/channels/whatsapp/session; stores WhatsApp login credentials.
Bridge port	Default 3100; the local bridge listens only on 127.0.0.1. Change it if the port conflicts.
Reply prefix	Text prefix appended before sending to WhatsApp. Can be left empty.
Text merge wait	Wait time for merging consecutive text messages before triggering the Agent, avoiding one paragraph being split into multiple calls.
Chunk send interval	Interval between segments when a long reply is split into multiple WhatsApp messages.
Send timeout	Per-call timeout for bridge calls to WhatsApp sendMessage.
Media cache directory	Directory where inbound media is downloaded locally. Leave empty to use the default workspace directory.

Verify the Connection

After saving and enabling the channel, verify it as follows:

1. Use a WhatsApp user in the allowed list to send a direct message to the bot account.
2. If group chat is enabled, @ the bot or reply to a bot message in an allowed group.
3. Send /status in WhatsApp to view the currently bound Session, Agent, model, and channel information.
4. If Flocks replies normally, the WhatsApp channel is connected successfully.

Result Delivery and Session ID

To proactively send results to WhatsApp from a Flocks page, Task Center, or Workflow, first establish a conversation binding and obtain the target Session ID.

To obtain the Session ID:

1. Ask Rex in the target WhatsApp direct message or group chat: What is your session_id?
2. Or send /status to view the currently bound Session, Agent, model, and WhatsApp conversation information.
3. Use this Session ID in the WebUI, another conversation, Task Center, or Workflow:

Send to session_id: <session_id>: Today's inspection is complete. Two high-risk alerts were found.

Flocks automatically finds the bound WhatsApp conversation based on the Session ID and sends the message. If /new has been executed in the target WhatsApp conversation, a new Session is rebound, and subsequent pushes should use the new Session ID.

Session Credentials and Security Notes

After WhatsApp pairing is complete, session credentials are stored under the Session directory. The default path is:

~/.flocks/workspace/channels/whatsapp/session

Protect this directory as sensitive credential storage:

• Do not commit the session directory to Git, copy it to others, or include it in public backups.
• Restrict directory permissions, for example allowing only the Flocks runtime user to read it.
• If you suspect credential leakage, remove the corresponding device in Linked Devices on the phone WhatsApp, then rescan the QR code in Flocks.
• Use a dedicated number in production to avoid mixing personal chats, contacts, and business bot usage.
• Do not perform bulk marketing, spam messaging, or outbound automated messaging to users who have not contacted you first.

FAQ

Node.js or npm Not Found or Not Installed

The WhatsApp bridge depends on local node and npm. Install Node.js 18+ first and confirm that the Flocks service process can find them:

node --version
npm --version

If node can be found in the terminal but not by Flocks when started as a system service, the service process PATH is usually different from the current shell. Adjust the service environment variables and restart Flocks.

The QR Code Keeps Loading or Times Out

Verify the following:

• Whether the deployment environment can access WhatsApp Web HTTPS / WebSocket services.
• Whether npm ci or npm install can run normally to install bridge dependencies.
• Whether an enterprise proxy, firewall, or DNS blocks WebSocket.
• Whether ~/.flocks/workspace/channels/whatsapp/bridge.log contains TLS, network, login, or pairing errors.

Flocks uses Node's built-in CA in the WhatsApp bridge Node subprocess to reduce TLS connection failures caused by some system CA chain issues. If the enterprise environment must use a self-signed CA or proxy CA, also check the certificate and proxy configuration for the Node process.

Messages Do Not Respond After Successful QR Scan

Verify the following:

• Whether the channel is enabled and running.
• Whether the direct message policy is allowlist mode but the current user is not in Allowed users.
• Whether group chat policy is disabled, or the current group is not in Allowed group JID.
• Whether group trigger mode requires @ mention or bot reply.
• Whether the current account is still listed under Linked Devices in the phone WhatsApp.

Need to Re-pair or Change Accounts

Click Rescan QR Code / Change Account on the WhatsApp integration page. After the new QR code is paired successfully, Flocks saves the new session credentials and restarts the channel.

If the Linked Device was manually removed on the phone, or the old session becomes invalid after a WhatsApp update, you also need to rescan the QR code.

Bridge Port Conflict

The default bridge port is 3100, and it listens only on 127.0.0.1. If multiple Flocks instances run on the same machine or another program occupies the port, change Bridge port in advanced settings, then save and restart the channel.

---

Related Resources: Messaging and alerting integrations overview | DingTalk integration | Feishu integration | WeCom integration | Slack integration | Telegram integration | WeChat integration | Email integration configuration