How to set up Hermes Agent on WhatsApp with the Baileys bridge

What you need

Hermes Agent can connect to WhatsApp so you can message your agent from your phone. It uses a built-in bridge based on Baileys, which emulates a WhatsApp Web session. It does not use the official WhatsApp Business API, so no Meta developer account or Business verification is needed.

The official docs warn that this unofficial bridge carries a risk of account restrictions. Use a dedicated number to isolate that risk from your personal account. Business users should read How to set up Hermes Agent on WhatsApp with the Business Cloud API for the separate Meta-supported integration, which needs a business account and a public webhook. A webhook is an HTTP callback carrying an event from another service. This guide covers the Baileys bridge. Compare routes at messaging platforms.

• Hermes Agent installed, with a model provider configured.
• Node.js v18 or newer and npm. The bridge runs as a Node.js process.
• A phone with WhatsApp installed, to scan the QR code.
• A dedicated phone number for the bot, rather than your personal number, to isolate account-restriction risk.

Choose a mode and a number

There are two modes. Bot mode is recommended: give the bot its own phone number and message that number. Self-chat mode links your own WhatsApp so you can message yourself. That also exposes your personal account to the bridge's restriction risk, so the dedicated-number recommendation still matters.

For bot mode, use a dedicated number you control and can keep active. Register it with WhatsApp before linking the bridge. Check current acceptance and inactivity rules with WhatsApp and the number provider.

• The Hermes docs list Google Voice, prepaid SIM and VoIP possibilities. Acceptance of a particular number is not established by this guide.
• Carrier costs and number-expiry rules vary. Do not rely on a blanket 90-day call rule or an assumption that a number is free or accepted.

Install WhatsApp on a phone and register the new number. To lower the ban risk, keep usage conversational, avoid bulk messages, and do not automate outbound messages to people who have not messaged first.

Connect it to Hermes

Run the WhatsApp wizard. It asks for bot or self-chat mode and which phone numbers may message the bot, installs bridge dependencies if needed, then shows a QR code. At the allowed-numbers prompt, enter specific numbers with country code and no +. Do not enter * or leave it blank. You can also run hermes gateway setup and pick WhatsApp for a guided walk-through.

Terminal

hermes whatsapp

On the phone, open WhatsApp, go to Settings → Linked Devices, tap Link a Device and point the camera at the QR code. The wizard confirms the connection and saves the session. If the code looks garbled, make your terminal at least 60 columns wide.

The wizard saves these settings to ~/.hermes/.env. Open the file and confirm they match the example below. Phone numbers include the country code, with no +. Separate several numbers with commas.

Set access and start the gateway

~/.hermes/.env

WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=15551234567

~/.hermes/config.yaml, silence unknown DMs

whatsapp:
  unauthorized_dm_behavior: ignore

Terminal

hermes gateway

An allowlist is the list of people permitted to use the agent. Put specific phone numbers in WHATSAPP_ALLOWED_USERS and keep allow-all disabled on a private bot. Unknown requests cannot run agent work without an explicit grant. Approved pairing can also grant access; an empty allowlist does not revoke it. WHATSAPP_ALLOWED_USERS=* and WHATSAPP_ALLOW_ALL_USERS=true widen access.

By default, WhatsApp still answers unknown DMs with a pairing code, even when WHATSAPP_ALLOWED_USERS is set. For a private number, add the YAML shown above to ~/.hermes/config.yaml so strangers get no reply. A code grants nothing until you approve it. Check the sender before running hermes pairing approve whatsapp <code>.

The gateway starts the WhatsApp bridge automatically using the saved session. Send a message to the bot number from an allowed phone, or message yourself in self-chat mode. Replies carry a "☤ Hermes Agent" header by default, and you can change or remove it with whatsapp.reply_prefix in config.yaml.

What it can do

The overview table lists images, files, typing and streaming for the bridge, but leaves voice unmarked. The WhatsApp and voice documentation describe voice-note paths. Transcription and spoken replies depend on configured speech providers. These are voice notes, not a live voice call.

Local faster-whisper is the normal local transcription engine where supported. Native Windows ARM64 and Intel macOS need a supported hosted or command-based provider instead.

• Text, images and file attachments are documented. Bridge media handling and WhatsApp protocol changes can affect delivery.
• Groups use the separate group policy described below. The overview does not mark threads or reactions as supported for the bridge.

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

A foreground gateway stops when you close the terminal. Install it as a service so it keeps running in the background.

Install as a user service

hermes gateway install

Linux only: boot-time system service

sudo hermes gateway install --system

Start the installed service

hermes gateway start

Check the running service

hermes gateway status

The session is saved under ~/.hermes/platforms/whatsapp/session, so you do not need to scan the QR code after every restart. That folder holds full session credentials. Protect it like a password and never share or commit it.

The gateway reconnects after short network blips on its own. If the session breaks, for example after a phone reset or a WhatsApp update, run hermes whatsapp again and scan a fresh code.

For hosting choices, see How to run Hermes Agent 24/7 on a VPS or home server. For how the gateway handles sessions and platforms, see Hermes Agent messaging gateway explained.

Service installation alone does not prove delivery. Send a harmless message from an allowed phone and check its reply. Both the Hermes host and bridge must remain available. If the computer is off, asleep or disconnected, the agent cannot answer or run jobs. Windows Task Scheduler does not supervise later gateway crashes; check status and start the gateway if needed.

On Unix-like hosts, the docs recommend chmod 700 ~/.hermes/platforms/whatsapp/session. If the session leaks, unlink the device in WhatsApp under Settings → Linked Devices.

Group chats and permissions

In bot mode, groups follow a group policy, not the DM allowlist. The default policy, pairing, forwards nothing from groups.

• allowlist admits only the groups listed in WHATSAPP_GROUP_ALLOWED_USERS, as group JIDs such as 120363001234567890@g.us.
• open admits every group the bot is a member of.
• Set the policy with WHATSAPP_GROUP_POLICY or whatsapp.group_policy.
• If WHATSAPP_ALLOWED_USERS is set, each group participant must also be on it, or paired.
• The bot answers every admitted group message by default. Set WHATSAPP_REQUIRE_MENTION=true to answer only @mentions, replies to the bot and /commands.

If it doesn't answer

For a wider checklist, see Hermes Agent bot not responding in your chat app.

• QR code not scanning: widen the terminal to 60 or more columns, try another terminal, and scan from the bot number's WhatsApp, not your personal one.
• QR code expired: codes refresh about every 20 seconds. Run hermes whatsapp again.
• Messages not received: check that WHATSAPP_ALLOWED_USERS has the sender's number with country code and no + or spaces. Set WHATSAPP_DEBUG=true in .env and restart the gateway to see raw events in bridge.log.
• Logged out unexpectedly: WhatsApp unlinks devices after long inactivity. Keep the phone on and online, then re-pair with hermes whatsapp.
• Stopped working after a WhatsApp update: update Hermes to get the latest bridge, then re-pair.
• macOS says Node.js is not installed: run hermes gateway install to refresh the service PATH, then hermes gateway start.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes WhatsApp with the Baileys bridge docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• How to set up Hermes Agent on WhatsApp with the Business Cloud API
• Hermes Agent bot not responding in your chat app

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher