WhatsApp channel user guide
This document is for Agentic Engine platform admins and regular users. It describes how to enable the WhatsApp channel in the platform, bind personal accounts, and use Agents and Teams in WhatsApp direct messages or group chats. If a page entry or the channel status is abnormal, contact your system admin.
Compliance reminder: Baileys is a web automation solution that isn't officially supported by WhatsApp, and it may carry risks of account rate limiting, restrictions, or bans. Complete a compliance assessment before production use, use a dedicated test account where possible, and don't link your personal primary account.
1. Before you begin
- Platform admins: Have the System Admin > Channels permission, and prepare a WhatsApp account dedicated to serving as the company's shared bot.
- Regular users: Have an Agentic Engine account that can log in normally, and be able to send direct messages to the shared bot from your own WhatsApp.
- Group chat use: The shared bot must first join the target WhatsApp group chat, and group members must bind their personal accounts.
Don't confuse the two identities: The admin scans the QR code to connect the company's shared bot to the platform. Regular users don't need to scan a code. They only need to generate a one-time binding code in the workbench and then send it to the bot in a direct message from their own WhatsApp to complete binding.
2. Add a WhatsApp channel as an admin
An admin with channel management permissions logs in to Agentic Engine and goes to System Admin > Channels.
- Click New Channel and select WhatsApp as the channel type.
- Enter the channel name, select a default model and enter a system prompt as needed, and then save.
- Turn on the channel's Enable switch. When the channel is enabled for the first time but the QR code hasn't been scanned yet, it shows Offline, which is normal.
- Return to the channel list and click Link by QR code.
- On the shared bot's phone, open WhatsApp, go to Settings/Menu > Linked devices > Link a device, and scan the QR code on the page.
- The QR code expires in about 2 minutes. After it expires, click Generate a new QR code on the page.
- After the scan succeeds, refresh the channel list and make sure the status changes to Online.
| Config items | Required | Operations |
|---|---|---|
| Channel Name | Required | Used to identify the channel in the channel list and on the user binding page, for example, "WhatsApp Bot". |
| Channel type | Required | Select WhatsApp. |
| Default Model | Optional | If none is selected, the platform's global default model is used. |
| System Prompt | Optional | Affects only Agent conversations started through this WhatsApp channel. |
Users can see the binding entry for this WhatsApp channel in the workbench only after the channel shows Online.
3. Bind and unbind user accounts
Bind a WhatsApp account
- Log in to Agentic Engine and open Channel Accounts in the workbench sidebar.
- Select the WhatsApp channel you want to use and click Bind.
- Copy the complete binding command in the dialog. The binding code is valid for 10 minutes and can be used only once.
- Use your own WhatsApp account to send the complete command, such as
+bind ABC234, to the shared bot in a direct message. - After you see "Your WhatsApp account is now bound. You can start chatting.", return to the workbench and confirm that the status has refreshed to Bound.
The binding command can be sent only in a direct message. Commands sent in group chats are rejected. The same WhatsApp identity can't be bound to multiple Agentic Engine users at the same time.
Unbind or switch platform accounts
- Open Channel Accounts in the workbench sidebar.
- Find the WhatsApp channel, click Unbind, and confirm.
- To bind a different Agentic Engine account, log in to the new account and generate a new binding code.
4. Use Agents in WhatsApp
Use in direct messages
- After binding, send questions directly to the shared bot in a direct message. Replies are returned to the current direct message.
- When the bot asks for more information or for confirmation to continue, just reply directly as the text prompt says.
- WhatsApp doesn't support conversation threads, so all replies stay in the original direct message.
| Action | Syntax | Description |
|---|---|---|
| Ask directly | Analyze this week's data for me | Uses the channel's default Agent. |
| Start a new conversation | +new | Supported only in direct messages. |
| Specify an Agent | +agent AgentName question | For example, +agent rhea Analyze the data for me. |
| Cancel the current task | +cancel | Must be sent exactly, as the entire message. |
Use in group chats
- First make sure the shared bot has joined the target group chat and that the member sending messages has bound a personal account.
- When you send a message, you must use WhatsApp's native @ mention feature to select the shared bot. Manually typing a similar name doesn't trigger it.
- Regular group messages that don't @mention the bot are ignored and don't enter Agent conversations.
- Group chats don't support
+new. To cancel a task, send@Bot +cancel.
Configure group chat routing as an admin
- Go to System Admin > Channels, and open Message Routing for the WhatsApp channel.
- Select a default Agent or Team. You must configure the default before you enable group chat routing.
- Add commands and keyword rules as needed, and then save.
- Send
@Bot +helpin a test group to check which Agents/Teams are available to the current user.
| Purpose | Example | Description |
|---|---|---|
| View available capabilities | @Bot +help | Shows the Agents/Teams available to the current user. |
| Specify a capability | @Bot +analysis Analyze this week's data | Routes by the command configured by the admin. |
| Route by keyword | @机器人 帮我检查埋点方案 | Uses the matching capability when a rule is matched, and the default otherwise. |
Group chat context: The system only refers to recent public group chat rounds that explicitly @mentioned the bot and were actually processed. Regular group messages without an @mention, other group chats, and personal direct messages aren't mixed in.
5. Attachments and task notifications
Send and receive attachments
- You can send JPEG/PNG images and TXT, Markdown, CSV, JSON, PDF, Word, Excel, and PowerPoint documents to the bot.
- Audio, video, and stickers currently aren't passed to the Agent, and the bot tells you why they can't be processed.
- By default, each file can be up to 2 MiB, and up to 5 attachments are processed per message. If you exceed these limits, compress the files or send them separately.
- Images or supported documents generated by the Agent are sent directly back to the original direct message or group chat.
Agent Team task notifications
- When you create an immediate or scheduled Agent Team task, select WhatsApp as the notification channel.
- After the task ends, the shared bot sends a direct message to the WhatsApp account bound by the task creator.
- Long results are automatically split into multiple messages.
If you don't receive a notification, check whether your personal account is still Bound, whether the WhatsApp channel is online, and whether WhatsApp notification was selected for the task. Notification delivery failures don't change the final status of the task itself.
6. Connection management and FAQ
Manage the connection as an admin
- After the channel is linked successfully, Link by QR code in the channel list changes to Manage link.
- When the channel shows Relink required or WhatsApp is disconnected, scan the QR code again in Manage link as prompted.
- Before you change the shared bot account, disable the channel first, then run Reset link and scan with the new account.
- Resetting the link removes existing user bindings and invalidates unused binding codes. Notify users before you do this, and have them bind again afterward.
- Deleting a channel stops it from sending and receiving messages. Delete it only after you confirm it's no longer needed.
FAQ
| Symptom | Solution |
|---|---|
| No WhatsApp binding entry in the workbench | Ask the admin to confirm that the channel is enabled, the QR code was scanned successfully, and the channel shows Online. |
| Binding code is invalid or expired | Return to the workbench to generate a new one, and within 10 minutes send the complete command to the correct shared bot in a direct message. |
| Direct messages work, but group chats get no response | Make sure the bot has joined the group chat, the sender is bound, and WhatsApp's native @ mention is used to select the bot. If group chat routing is enabled, a default Agent/Team must also be configured. |
| QR code expired or failed to load | Click Generate a new QR code. If it still can't be generated, contact your system admin. |
| Still offline after scanning | Wait a moment and refresh the channel list. If it's still not online, go to Manage link to relink, or contact your system admin. |
| Text works, but attachments can't be processed | Check the file type, size, and number. Try compressing the files or sending them separately. |
| No Team task notification received | Check the account binding status, the channel's online status, and whether WhatsApp notification was selected for the task. |
| Need to switch the bound platform account | First unbind in Channel Accounts of the original Agentic Engine account, and then log in to the new account and generate a new binding code. |
If the shared bot's entry is removed from Linked devices on the phone, the channel disconnects, and an admin needs to scan the QR code again in the platform to relink it.
Related pages and next steps
- See the setup instructions for other platforms: Channel management.
- Learn about the overall flow of channel connection and binding: Channel overview and binding.
- Configure the Agent to use: Agent.
- See how to use conversations in the platform: Conversations.