.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
WhatsApp is a frustrating channel to integrate with. The official Business API is gate-kept, expensive and oriented toward bulk-message use cases agentic chat doesn't fit. The unofficial path (Baileys, the open-source library that emulates a WhatsApp Web session) works fine technically, but it's running against Meta's terms of service in spirit if not always in letter and your number can get banned if Meta's heuristics decide your bot looks like spam.
This guide covers the Baileys path, which is what Hermes ships with by default. It also covers the things you can do to keep your number alive longer (a dedicated bot number, conservative reply patterns, sensible rate limits) and the things to know before you try to put your personal WhatsApp number behind an agent (please don't).
Why Baileys and what the alternatives look like
Baileys is a TypeScript library that pretends to be a WhatsApp Web client. It pairs to your phone via QR code, then relays messages to and from your phone over WhatsApp's encrypted protocol. From WhatsApp's perspective it's an ordinary mobile-app session.
From your perspective, it gives you a programmatic interface to send and receive messages, read groups, react to messages, etc., without paying for the Business API. The downsides: it's against WhatsApp's terms in some interpretations, the session can break when WhatsApp updates its protocol and Meta does ban accounts that use it for bulk send patterns.
The two alternatives are: the official WhatsApp Business API, which Hermes can also use if you have access; and just not using WhatsApp at all and steering users to Telegram or Signal. For most personal-use Hermes setups, Baileys is the path that works, with the precautions in this article.
Step 1: get a dedicated WhatsApp number
Don't use your personal WhatsApp number for the bot. Don't. Three reasons.
If Meta bans the bot's WhatsApp account, you lose all your normal WhatsApp messages too. People who do this and get banned end up with a lot of "wait, how do I message my mum" angst.
The bot will reply to messages, leak that it's a bot through subtle response timing patterns and feel weird to people you message normally. Mixing personal and bot use through one number degrades both.
The bot will see all your personal messages, which means they go through your LLM provider. Even if the provider is reputable, that's a privacy posture you don't want.
The fix: get a separate phone number. Cheap pay-as-you-go SIMs work fine for receiving the WhatsApp registration SMS. Once registered, you don't need the number for anything else; the WhatsApp account stays linked to the SIM but doesn't actively use it. Some VPS providers offer "VoIP for SMS" services that work too. The Twilio number trick is unreliable because Meta sometimes flags VoIP-registered accounts as suspicious.
Step 2: install the Baileys backend
Hermes ships the WhatsApp adapter as part of its base install when you're on Linux or macOS (it's skipped on Termux because Baileys doesn't work reliably on Android). The adapter needs Node.js v22, which the install script already brought down.
Verify:
node --version
# Should print v22.x.xIf you got a different version somehow, install Node 22 explicitly:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejsStep 3: pair to your dedicated number
Run the WhatsApp gateway setup wizard:
hermes gateway setup
# Pick "WhatsApp" when the wizard asks which channel to addThe wizard prints a QR code in your terminal. On your dedicated phone (the one with the bot SIM), open WhatsApp, tap the menu, "Linked Devices", "Link a Device", scan the QR code on your terminal screen.
The pairing takes about ten seconds. The wizard reports success and Hermes saves the session to ~/.hermes/whatsapp/. From here, the gateway can send and receive messages on that number's behalf.
Test:
hermes gateway startSend the bot's WhatsApp number a message from a different account. The bot should reply within a few seconds. If it doesn't, check journalctl -u hermes -f for connection-lifecycle messages from the WhatsApp adapter.
Allowed users on WhatsApp
WhatsApp doesn't expose user IDs the same way Telegram does; it uses phone numbers. The allowlist works on E.164 numbers:
hermes config set messaging.whatsapp.allowed_users '["+447700900123", "+15555550100"]'The phone numbers must include the country code with a leading +. Tested format is "+44" not "44 7700 900 123" or any local-style format. The bot will respond only to messages from numbers on this list.
For groups, the equivalent is allowed-groups, configured by group ID rather than member numbers. Hermes logs incoming group messages with the group ID; copy it from the logs and add to messaging.whatsapp.allowed_groups.
Things that get you banned and how to avoid them
Meta's ban heuristics for unofficial WhatsApp clients are opaque, but the patterns that correlate with bans are well-known. Avoid the following:
Sending many messages to people who haven't messaged you first. The most reliable ban trigger. Make your bot reactive, not proactive; it should respond to incoming messages but rarely or never initiate. If you absolutely need outbound messages (a daily briefing), keep them targeted at users who've explicitly opted in.
Sending messages too fast. Real users send messages over seconds and minutes; bots that fire ten replies in two seconds look like bots. Hermes has a per-message delay you can tune:
hermes config set messaging.whatsapp.send_delay_ms 15001500 ms (1.5 seconds) is enough to look human-paced without being annoying. Increase to 2500 if you want extra caution.
Sending bulk identical messages. The agent should respond conversationally to each user, not blast the same template to many users. The variation in agentic responses is your friend here; ironically, the same thing that makes LLM responses feel human-like also helps avoid bot-detection patterns.
Linking and unlinking the device frequently. Each Linked Devices session leaves a fingerprint. Stable, long-lived sessions look like legitimate use. If your gateway crashes and reconnects every five minutes, that pattern is suspicious. Fix the underlying instability before WhatsApp notices.
Pretending to be a regular human user via the bot. Set up a clear bot persona via SOUL.md, name the WhatsApp profile something obviously bot-like ("MyService Assistant" rather than "Alex Smith") and don't pretend the bot is a person. WhatsApp doesn't ban accounts for being honest about being bots; it bans accounts for behaving like spammers.
Voice notes
WhatsApp voice notes work the same way they do on Telegram: the gateway downloads the OPUS file, transcribes via your STT provider, treats the transcript as the user's message. Make sure your STT config is set:
hermes config set tts_stt.stt_provider whisperIf you're using local Whisper (via the Hermes whisper backend), the transcription happens on your VPS without any cloud round-trip. If you're using OpenAI's hosted Whisper, audio gets uploaded to OpenAI for transcription. Pick your privacy posture.
For replies, Hermes can also send voice notes via TTS:
hermes config set messaging.whatsapp.reply_voice_messages true
hermes config set tts_stt.tts_provider elevenlabsThis is delightful in moderation and creepy in volume. Default off.
Group chats
WhatsApp group support is more limited than Telegram's because Baileys' group APIs are less stable. The basics work: the bot can be added to a group, can read messages and can reply when @-mentioned. More advanced patterns (reading message reactions, polls, threaded replies) are sometimes flaky.
For groups, Hermes defaults to mentions-only response (the bot only replies when you tag it). This is the right default; otherwise the bot would respond to every group message, which is unbearable. Override only if you have a specific use case.
Session management
The Baileys session lives in ~/.hermes/whatsapp/. If something goes wrong (the session breaks, your phone says "device removed", you want to start fresh), delete the session and re-pair:
hermes gateway stop
rm -rf ~/.hermes/whatsapp/
hermes gateway setup
# Re-scan the QR codeA re-pair is invisible to your conversation history (Hermes keeps that separately in state.db), but WhatsApp users will see "your phone connected to WhatsApp Web" notifications. Don't do this often; rare re-pairs are fine, frequent ones are a ban risk.
When the gateway becomes unstable
Baileys' upstream protocol changes occasionally trigger connection-stability issues. Symptoms: the bot replies to the first message after a restart, then stops; or the connection drops every few hours and reconnects automatically (look for "ws disconnect" log entries).
The fixes, in order of cost:
Update Hermes. Connection-stability fixes land in most major releases. hermes update often resolves the issue.
Update Baileys. Hermes pins a specific Baileys version; if you're hitting a known issue, the fix may already be in the upstream library but not yet picked up by the Hermes version you're running. Subscribe to Baileys' GitHub releases atom feed to know.
If neither works, fall back to the official Business API. Hermes supports it as an alternative WhatsApp backend; the setup is more involved (you need a Meta business account, a verified Facebook Business profile and an approved use case) but the connection is stable and the ban risk goes to zero.
Cross-link to other channels
WhatsApp is rarely the only channel you'll wire up. The multi-platform gateway article covers the patterns for running WhatsApp alongside Telegram, Discord and others on one Hermes install.
If you've previously run WhatsApp through OpenClaw, our OpenClaw multi-channel guide covers the equivalent on that side; useful for migration comparisons.
The 1-click route
The LumaDock Hermes Agent VPS template ships Node.js v22 pre-installed and the WhatsApp adapter ready to pair, on Ubuntu 24.04. The dedicated-number recommendation still applies regardless of where you host; the VPS is happy to pair with whichever WhatsApp account you bring.
