← A WhatsApp number for your AI agent

Set up Hermes Agent on WhatsApp with a separate bot number

Get the number, register it in WhatsApp Business, pair Hermes in bot mode, and decide who may message it. One phone, no SIM.

Checked against Hermes Agent’s documentation on 17 November 2026.

What you need

  • Hermes Agent, installed on the computer or server that will run it. If it isn’t yet, follow Hermes’s installation page first.
  • Node.js 20 or newer. Hermes talks to WhatsApp through a small bridge that runs on Node.js.
  • A terminal at least 60 columns wide, so the QR code fits.
  • Your phone. The one you already use is enough: the bot’s number lives in WhatsApp Business, next to your personal WhatsApp.
  • A Wabi number for the bot. Step 1 gets it.
  • Your own WhatsApp number, to write to the bot and to put on its allowlist.

Bot mode or self-chat? Hermes has two WhatsApp modes. This guide uses the one its docs recommend, a separate bot number: people message the bot directly, and your own chats stay out of it.

1. Get a number from Wabi

Hermes’s docs say the number must not be registered with WhatsApp already, and warn that some virtual numbers are blocked. Every Wabi number is tested with WhatsApp Business before you get it.

  1. Open Wabi in your browser or in the app, and sign in.
  2. Pick a country. Choose the one the people who will message your bot expect to see; a US number works from anywhere, and there you also pick the area code.
  3. Subscribe. The number then shows in Wabi as Active or Trial.

In the browser, keep the Wabi tab open for the next step: that is where the verification code will show.

2. Register it in WhatsApp Business

  1. Install WhatsApp Business on your phone, from the App Store or Google Play. Your personal WhatsApp stays as it is.
  2. Open it and enter the Wabi number, with its country code.
  3. When WhatsApp asks how to verify the number, choose Call me.
  4. The code appears on Wabi’s main screen, usually within a minute or two. Type it into WhatsApp Business.
  5. Give the account a name. This is what people see when the bot writes to them, so name it after the bot.

Use WhatsApp Business, not WhatsApp. Wabi numbers are tested with WhatsApp Business.

Stuck? See the code never arrives and “Please try again in 1 hour” in our FAQ.

3. Pair Hermes with the number

Run Hermes’s WhatsApp wizard:

hermes whatsapp
  1. When it asks for the mode, choose the separate bot number.
  2. It installs what the bridge needs, then shows a QR code in the terminal.
  3. On the phone, open WhatsApp Business, the bot’s account, not your personal WhatsApp.
  4. Go to Settings → Linked Devices → Link a Device and scan the QR code. On Android, Linked devices is in the ⋮ menu.

The wizard confirms the connection and exits. The QR code refreshes about every 20 seconds; if it times out, run hermes whatsapp again.

Hermes keeps the session in ~/.hermes/platforms/whatsapp/session. Whoever holds that folder holds the WhatsApp account: don’t share or commit it.

If the account uses a passkey, pair with hermes whatsapp --passkey-browser and the path to Chrome or Edge. Hermes’s WhatsApp page explains that route.

4. Decide who may message it

Hermes answers nobody until you say whom. The settings are in ~/.hermes/.env:

WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=14155550123

Put your own number in WHATSAPP_ALLOWED_USERS: country code first, no + and no spaces. Several numbers are separated by commas.

People who are not on the list

By default, someone new who writes to the bot gets a pairing code in reply. You see the waiting requests with hermes pairing list and approve one with hermes pairing approve; a code expires after an hour.

To have the bot stay silent to strangers instead, add this to ~/.hermes/config.yaml:

whatsapp:
  unauthorized_dm_behavior: ignore

Groups

The bot ignores groups until you allow them: WHATSAPP_GROUP_POLICY starts as pairing, which passes nothing on from groups. Leave groups for later: Hermes’s WhatsApp page has the settings, among them WHATSAPP_REQUIRE_MENTION.

5. Start the gateway and say hello

The gateway is the part of Hermes that listens for messages. It starts the WhatsApp bridge with the session you just saved. To try it, run it in the terminal:

hermes gateway

To keep it running after you close the terminal, install it as a service:

hermes gateway install
hermes gateway start

Now take your phone, open your personal WhatsApp and send a message to the bot’s number. The reply is your agent. hermes gateway status shows whether the service is up.

After a change to .env or config.yaml, restart the gateway: hermes gateway stop, then hermes gateway start.

6. Keep it running

  • Keep the Wabi number. It is the key to the bot’s WhatsApp account: WhatsApp asks for it again when you move to a new phone or reinstall. If the subscription ends, the number may later go to someone else.
  • Open WhatsApp Business now and then. WhatsApp logs linked devices out when the account has not been used on the phone for 14 days. If that happens, pair again with hermes whatsapp.
  • Keep it to conversations. Hermes’s own advice: use a number that is not your personal one, send no bulk messages, and don’t have the bot write first to people who never messaged it.
  • After a WhatsApp update, if the bot stops, update Hermes and pair again.

An agent reaches WhatsApp as a third-party client. That generally works, but WhatsApp does not guarantee it. Wabi’s guarantee covers the number’s activation: see what the guarantee covers.

If something goes wrong

The QR code won’t scan
Widen the terminal to at least 60 columns, or try another terminal. Scan from WhatsApp Business, the bot’s account, not from your personal WhatsApp.
The bot doesn’t answer
Check that the sender’s number is in WHATSAPP_ALLOWED_USERS, with the country code and without + or spaces, then restart the gateway. To see what arrives, set WHATSAPP_DEBUG=true in .env and read bridge.log.
Strangers get a pairing code from the bot
Set unauthorized_dm_behavior: ignore under whatsapp: in config.yaml, as in step 4.
It was logged out
WhatsApp unlinks devices after long inactivity. Open WhatsApp Business on the phone, then run hermes whatsapp for a new QR code.
The session is gone after a restart
Check that ~/.hermes/platforms/whatsapp/session exists and can be written to. In a container, mount it as a persistent volume.
The bridge crashes, or keeps reconnecting
Restart the gateway and update Hermes. If the session no longer works, pair again. hermes doctor checks the installation.
WhatsApp’s verification code never arrived
That is the number’s side, not Hermes’s: see our FAQ, or write to wabi@applaud-software.com.

Hermes Agent is an open-source project by Nous Research, and Wabi is not affiliated with it. Its commands and settings change: where this page and Hermes’s docs differ, the docs are right.

Your bot’s number is two minutes away.

Tested with WhatsApp Business before you get it.