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

> Connect Hermes Agent to WhatsApp: link a number with a QR code, set your allowlist, start the gateway and message your agent from your phone.

Canonical: https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## 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](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md) 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](https://hermeswatcher.com/messaging.md).

- 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](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). For how the gateway handles sessions and platforms, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md).

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](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md).

- 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](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [How to set up Hermes Agent on WhatsApp with the Business Cloud API](https://hermeswatcher.com/learn/hermes-agent-whatsapp-business-cloud-api-setup.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)

## Related tools

- [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md)
- [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md)
- [WhatsApp: chat with Hermes from your phone](https://hermeswatcher.com/tools/whatsapp.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)

## Sources

- [WhatsApp](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp)
- [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)
- [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773)
- [WhatsApp Business Cloud API](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud)
- [Voice mode](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode)
- [hermes_cli/main_platform_setup.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/hermes_cli/main_platform_setup.py)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt