Hermes Agent WhatsApp setup: connect your agent step by step

Before you start: how it connects, and the two modes

The built-in WhatsApp support in Hermes uses a small Node.js program, the bridge, built on the open-source Baileys library. It behaves like a WhatsApp Web session on a linked device. It is not the official WhatsApp Business API, and that has a cost worth knowing up front: WhatsApp does not officially support third-party bots outside its Business API, so the Hermes documentation warns of a small risk that the account gets restricted. Upstream’s advice to keep that risk low:

• use a separate phone number for the agent rather than your personal one;
• keep it to normal conversations, and avoid sending the same message to many people at once;
• do not have the agent start chats with people who have not written to it first.

WhatsApp also changes its web protocol from time to time, which can break third-party bridges for a while. When that happens the fix is to update Hermes, which brings a newer bridge, and pair again.

You choose one of two modes:

• Separate bot number (bot, the one upstream recommends). The agent has its own number and people message that number directly. It suits several users, and it keeps your personal account out of the risk above. It needs its own WhatsApp account: if you get a new number for it, register it on WhatsApp first. The setup wizard suggests the free WhatsApp Business app with a second SIM, which can run next to your personal WhatsApp on the same phone.
• Personal self-chat (self-chat). Hermes uses your own WhatsApp and you talk to it in the chat with yourself (“Message yourself”). In this mode the bridge answers only that one chat and ignores every message from anyone else, so strangers and groups never reach the agent. It is quick to set up and fine for one person, but it is your own account that is linked.

You need Node.js 20.9 or newer with npm on the machine that runs Hermes, and a phone with WhatsApp to scan the code. New to Hermes? Begin with how to install Hermes Agent.

The official alternative. Hermes also ships a separate adapter for Meta’s WhatsApp Business Cloud API, set up with hermes whatsapp-cloud. It is the route upstream points to for a real business bot that has to be stable: it uses Meta’s supported interface instead of a linked device, so there is no QR code and no ban risk from an unofficial client. In return you need a Meta Business account, a Meta app with WhatsApp added, a dedicated business number, and a public HTTPS address so Meta can deliver incoming messages to Hermes by webhook (Hermes listens on local port 8090 at /whatsapp/webhook by default; the docs suggest a tunnel such as Cloudflare Tunnel). The two adapters can run side by side on different numbers. The rest of this page covers the QR-code bridge.

Step 1: run the wizard and scan the QR code

Run the WhatsApp wizard in a terminal:

hermes whatsapp

It goes through four things in order:

1. Asks which mode you want: separate bot number or personal self-chat.
2. Asks who may message the agent. In bot mode you give the allowed phone numbers, or * for anyone; in self-chat mode you give your own number.
3. Installs the bridge’s dependencies the first time, which can take a few minutes.
4. Shows a QR code in the terminal and waits for you to scan it.

To scan it, take the phone that holds the account the agent should use:

1. Open WhatsApp (or WhatsApp Business, if that is where the bot’s number lives).
2. Go to Settings, then Linked Devices.
3. Tap Link a Device and point the camera at the code in the terminal.

The code is replaced roughly every 20 seconds; if it times out, run hermes whatsapp again. A garbled code usually means the terminal is too narrow: the Hermes docs ask for at least 60 columns and Unicode support. In bot mode, make sure you scan from the bot’s account, not your personal one.

On a first setup, the wizard switches WhatsApp on only after pairing has actually worked, so an interrupted run does not leave Hermes trying to start a bridge that has no login. WhatsApp also appears in hermes gateway setup, but that only records settings; the QR pairing itself still happens in hermes whatsapp.

Step 2: check the settings and start the gateway

The wizard writes its answers to ~/.hermes/.env. If you prefer to set them yourself, or want to check what it wrote, these are the lines that matter:

WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=15551234567,447700900123

WHATSAPP_MODE is either bot or self-chat. If it is missing, the bridge falls back to self-chat, so set it explicitly when you use a separate number.

Your WhatsApp “user ID” is just the phone number. In WHATSAPP_ALLOWED_USERS write each number in international form with the country code, digits only: no +, no spaces, no leading zero for the local area code. A UK mobile such as 07700 900123 becomes 447700900123. Separate several numbers with commas. WhatsApp sometimes identifies a sender by an internal linked-device ID instead of the phone number; the bridge matches those back to the phone number for you, so the allowlist still uses plain numbers.

Then start the gateway, which launches the bridge with the saved login:

hermes gateway

That runs in the foreground and stops when the terminal closes. hermes gateway install sets it up as a background service for your user, and on Linux sudo hermes gateway install --system installs a service that starts at boot. In bot mode, send the bot’s number a message from an allowed phone; in self-chat mode, open your chat with yourself and type.

Who can message your agent

Your agent can use tools, run commands and read files, so who reaches it matters. Hermes starts from “nobody”: unless a sender is on the allowlist or has been approved through pairing, the gateway does not hand their message to the agent. Your options in bot mode:

• An allowlist. WHATSAPP_ALLOWED_USERS with specific numbers, as above. This is the sensible choice for most people.
• Everyone. WHATSAPP_ALLOWED_USERS=*, or the equivalent WHATSAPP_ALLOW_ALL_USERS=true, lets any WhatsApp user who messages the number talk to the agent. Think hard before doing this with an agent that has access to your files or accounts.
• Pairing. By default, an unknown person who sends the bot a direct message gets an eight-character pairing code back, even when an allowlist is set. You approve them on the machine running Hermes with hermes pairing approve whatsapp <code>, and they stay approved. Codes expire after one hour.

For a private number you will usually not want strangers receiving codes at all. Add this to ~/.hermes/config.yaml and Hermes stays silent to anyone not allowed:

whatsapp:
  unauthorized_dm_behavior: ignore

A third value, decline, sends one short polite refusal instead and then ignores that sender for 24 hours. In self-chat mode none of this comes up: messages from other people never get past the bridge.

Group chats

Groups only apply in bot mode, and they are controlled separately from direct messages by the group policy, WHATSAPP_GROUP_POLICY in .env or group_policy under whatsapp: in config.yaml. Its default passes nothing from groups to the agent, so adding the bot to a group does nothing until you change it:

• allowlist together with WHATSAPP_GROUP_ALLOWED_USERS admits only the groups you list. Despite the name, that variable takes group IDs (JIDs), which look like 120363001234567890@g.us, separated by commas.
• open admits every group the bot’s number belongs to.
• disabled switches groups off explicitly.

Getting a group through does not admit everyone in it. If WHATSAPP_ALLOWED_USERS is set, each participant must be on it or paired. With no sender allowlist, allowlist trusts every member of a listed group, while open still requires each member to be paired or allow-all to be on.

By default the bot answers every admitted group message, which gets noisy. Set require_mention: true under whatsapp: (or WHATSAPP_REQUIRE_MENTION=true) and it replies only when someone @mentions it, replies to one of its messages, or sends a slash command. Groups listed in free_response_chats are exempt from that rule.

Voice notes, files and formatting

• Voice notes you send are transcribed with the speech-to-text provider Hermes is configured with, such as local faster-whisper, Groq Whisper or OpenAI Whisper. When the agent answers with speech, the bridge sends it as a real WhatsApp voice note. If the audio has to be converted first and ffmpeg is missing or the conversion fails, it arrives as an ordinary audio file instead.
• Photos, videos and documents reach the agent as attachments. Small text-type files (for example .txt, .md, .csv and .json, up to 100 KB) are also read straight into the message. Quoting an earlier message gives the agent that message as context.
• Long answers are split into several messages of up to 4,096 characters each.
• Formatting: the Markdown the model writes is converted to WhatsApp’s own style, so double-asterisk bold becomes single-asterisk bold, headings become bold lines, and links become the text followed by the address in brackets. Code blocks are left as they are.
• The “Hermes Agent” header: in self-chat mode, where your messages and the agent’s come from the same number, each reply starts with a “☤ Hermes Agent” header so you can tell them apart. Set reply_prefix: "" under whatsapp: to remove it, or put your own text there. In bot mode replies have no header.
• Read receipts (blue ticks) are off by default; send_read_receipts: true under whatsapp: turns them on. They are sent once a message gets through the WhatsApp adapter’s own filters (mode, group policy, mention rule) but before Hermes checks the sender against the allowlist, so a stranger’s direct message can show as read even when Hermes then ignores it.

Several quick messages in a row are gathered into one request after a short pause, so pasting a long text in pieces gets one answer rather than several.

Staying connected and fixing common errors

The login is saved in a session folder inside ~/.hermes, so restarts do not need a new scan. That folder holds the keys to the WhatsApp account: anyone who copies it can use the account, so never share it or commit it to a repository. If you suspect it has leaked, remove the device on the phone under Settings, Linked Devices.

Short drops, such as a network blip or the phone going offline for a moment, are reconnected automatically. If the session is gone for good (the phone was reset, the device was unlinked, or a WhatsApp update invalidated it), run hermes whatsapp again and answer yes when it asks to re-pair; it clears the old session and shows a fresh QR code.

• It does not answer anyone. Check that WHATSAPP_ALLOWED_USERS holds the sender’s number in the digits-only format above. With nothing set and no pairing approved, every sender is refused. To see what the bridge receives, set WHATSAPP_DEBUG=true in .env, restart the gateway, and read bridge.log.
• It ignores other people. You are probably in self-chat mode, which only answers your own chat with yourself. Set WHATSAPP_MODE=bot and use a separate number.
• Strangers get pairing codes. That is the default; set whatsapp.unauthorized_dm_behavior: ignore as shown above.
• It is silent in a group. The group policy is still on its default. Use allowlist with the group’s ID, or open, and check the mention rule.
• Logged out after a while. The Hermes troubleshooting notes say WhatsApp unlinks devices after long inactivity. Keep the phone switched on and connected, and re-pair if needed.
• It stopped after a WhatsApp update, or the bridge keeps reconnecting. Restart the gateway, update Hermes to get the newer bridge, and re-pair.
• macOS service says Node.js is not installed although it works in your terminal. Background services do not inherit your shell’s PATH; run hermes gateway install --force to record the current one, then hermes gateway start.

The underlying limit is the same as for any self-run chat bot: the agent answers only while the machine running the gateway is on and online. If you also use Telegram, the Hermes Agent Telegram setup works the same way, and our comparison of self-hosting and managed hosting covers keeping an agent online around the clock.

WhatsApp on ReadyHermes

On ReadyHermes your own Hermes Agent runs on our servers and stays on, so it keeps answering WhatsApp and running scheduled jobs while your computer is off. There is no gateway or bridge for you to run. To connect:

1. In the workspace, open Channels, choose WhatsApp and click Connect.
2. The assistant restarts, which takes about a minute, and then a QR code appears.
3. On your phone, open WhatsApp, go to Settings, Linked devices, Link a device, and scan the code. The panel confirms when it is connected.

This links your WhatsApp account as a linked device, the same mechanism described above rather than the Business Cloud API, so the advice about a separate number applies here too. Keep that phone online.

The panel offers three choices for who can message the assistant:

• Only me (the default): just your own number. You talk to the assistant in your chat with yourself, “Message yourself” in WhatsApp.
• Specific numbers: you plus up to 50 numbers you list, one per line, with country code.
• Anyone: any number that messages yours. You have to tick a box confirming you understand that strangers can then reach anything the agent is connected to.

Changing the choice restarts the assistant for about a minute. People who are not allowed get no reply at all, not even a pairing code. Replies arrive without the “Hermes Agent” header line. Voice notes are transcribed automatically, with the language detected for you, and photos and documents you send reach the assistant. Groups are not supported on ReadyHermes yet: the assistant answers direct chats only.

You can disconnect from the same Channels panel at any time, after which the assistant stops replying on WhatsApp; to be thorough, also remove the linked device on your phone under Settings, Linked devices. Channels needs an active trial or paid plan, and the same panel connects Telegram, Discord, WeChat and Lark. To see what else is included, read about managed Hermes Agent hosting.