Configure the WhatsApp plugin in Settings → Plugins → WhatsApp. It links one WhatsApp account to Elowen; pair the account, then set sender policies.
For shared identity and conversation rules, see Channels.
Pair an account
- Enable the plugin and open its Pairing panel.
- Select Pair device.
- Scan the QR code from WhatsApp Linked devices → Link a device. To use a phone pairing code instead, set Pairing phone number to the bot's international number using digits only. The plugin shows an 8-character code to enter under Linked devices → Link with phone number.
- Add at least one sender policy.
The panel shows the current code and connection status. Use New code to get a fresh code. Credentials are kept for reconnects. Unpair device logs the linked device out and removes its local credentials; pair it again to reconnect.
Decide who can use the bot
Set policies in Settings → Plugins → WhatsApp → Sender policies. The first matching policy wins; unmatched senders are ignored. A policy can match a phone number, a personal JID ending in @s.whatsapp.net, a whole group JID ending in @g.us, or * as a final catch-all. Put * last. Number matching ignores formatting, so 420777123456, +420 777 123 456, and its personal JID match the same sender.
WhatsApp may identify someone with an internal @lid JID. If Baileys provides the corresponding phone JID, the plugin uses it; otherwise the LID is a separate identity and does not count as a phone-number link.
Turn on Administrator access for a policy to allow shared-chat controls. It does not grant project access or tools: those follow the sender's linked Elowen account and tool grants. Group-management tools are also limited by the paired WhatsApp account's rights, such as its role in a group.
Direct chats and groups
Direct chats are one-person conversations and need no mention. In groups, the bot matches each sender by their personal identifier; a group-wide policy can admit everyone in that group.
Respond without mention is on by default, so the bot answers every message from an admitted sender in a group. Turn it off to require an @mention or reply to the bot. Allowed groups can restrict replies to listed group JIDs; empty allows every group where an admitted sender writes. Direct chats remain available.
Commands and questions
WhatsApp uses numbered text prompts instead of native buttons. An AskUserQuestion can contain up to four questions, each with two to four options. Each reply answers the first unanswered question. A number picks that option, and comma-separated numbers pick several on a multi-select question. Other text is taken as your own answer unless the question disables it. Answers are sent once every question has one; if delivery is refused, reply submit to retry. Only the person who was asked can answer. Questions remain answerable until Elowen accepts an answer or resolves the waiting question. Menu timeout controls numbered command menus only: six minutes by default, configurable from 30 seconds to 30 minutes. Cancelled questions and expired menus cannot consume a later number reply.
| Command | Purpose |
|---|---|
/model, /reasoning, /context |
Open numbered pickers. |
/new, /stop, /stats, /compact |
Manage the conversation. |
/fast |
Turn Fast on or off for the chat's selected model in the linked account's own choice: on, off, or status. |
/project |
Switch this conversation into one of your projects. |
/plan, /build, /workflow |
Switch the conversation's work mode; admin only. |
/restart |
Restart the daemon; admin only. |
/help |
Show commands available to the sender. |
Model, reasoning, and context pickers, and /plan, /build, and /workflow, require an administrator policy. /stop, /stats, and /compact also require one. /fast requires a linked account. WhatsApp has no /display command.
Live progress, notifications, and images
Live progress trace is on by default: the plugin updates one progress message while the agent works, then sends the final answer separately. Turn it off to show only the answer. Replace progress with answer is off by default; when enabled, the progress message is replaced by the answer, not deleted.
Processing reactions (👀, ✅, ❌) are on by default; turn Processing reactions off to disable them. Notification chat chooses the destination for proactive cron and tick results, escalations, and restart notices. It accepts a phone number, personal JID, or group JID; bare numbers are converted to @s.whatsapp.net. An explicit destination supplied by the host takes precedence. Leave it empty to disable these messages; notifications bypass sender policies, but the account must be paired.
Voice messages are transcribed when voice is enabled in Elowen and the sender has a linked account with voice permission and room under its spending limit. Elowen answers with text plus an OGG/Opus voice note. Incoming audio is limited to 25 MiB. Larger audio, refused transcription, and download or transcription errors leave an untranscribed-attachment note. If speech is refused or fails, the text reply remains. Voice settings are managed in Elowen; the WhatsApp plugin has no separate voice provider settings.
For image processing, set Vision model to a vision-capable model or leave it empty to use the chat's model. Each incoming message carries at most one image. Max inbound image size limits its download size and defaults to 5 MiB; oversized images become an attachment note. Max images per reply limits shared images in an outgoing reply and defaults to 4, configurable from 1 to 10.