# WhatsApp: chat with Hermes from your phone

> Link Hermes to WhatsApp as a linked device through a bundled Node.js bridge, in bot or self-chat mode.

Canonical: https://hermeswatcher.com/tools/whatsapp  
Kind: Messaging platform · 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 it is for

The WhatsApp adapter runs a small Node.js bridge that pairs with WhatsApp the same way WhatsApp Web does: you scan a QR code from your phone's Linked Devices screen. You can run it in bot mode on a dedicated number, or in self-chat mode on your own account. Once linked, allowlisted numbers can message Hermes and get replies, including in groups if you opt in. It provides a familiar phone interface through an unofficial linked-device bridge; setup effort and reliability depend on pairing, host availability and account policy. It is also unofficial, so the docs recommend a dedicated number and point business users to the separate WhatsApp Business Cloud API adapter for stability.

## What you need

- Node.js v18+ and npm for the bridge process
- A phone with WhatsApp to scan the pairing QR code
- A phone number for the linked WhatsApp account. The official docs recommend a dedicated number for a bot.

## Setting it up

1. Run `hermes whatsapp`, choose bot or self-chat mode, let it install the bridge dependencies and display a QR code
2. On your phone open Settings, Linked Devices, Link a Device, and scan the QR code (the terminal should be at least 60 columns wide)
3. Add WHATSAPP_ENABLED=true, WHATSAPP_MODE=bot (or self-chat) and WHATSAPP_ALLOWED_USERS (digits with country code, no +) to ~/.hermes/.env
4. Start the gateway with `hermes gateway`, or install it as a service with `hermes gateway install`

## How to check it works

- The wizard confirms the connection after pairing and exits
- Send a message from an allowed number and confirm Hermes replies
- Set WHATSAPP_DEBUG=true, restart the gateway and inspect raw events in bridge.log

## Limits

- WhatsApp does not officially support third-party bots outside the Business API, so there is a ban risk; use a dedicated number and avoid unsolicited or bulk messages
- WhatsApp protocol changes or long inactivity can break or unlink the bridge, requiring an update and re-pair
- The session folder under ~/.hermes/platforms/whatsapp/session grants full account access and must be protected

## Messaging setup

[All messaging platforms](https://hermeswatcher.com/messaging)
- [Setup guide](https://hermeswatcher.com/learn/hermes-agent-whatsapp-setup)

## Sources

- [Hermes Agent docs: WhatsApp](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp)
- [Hermes Agent docs: Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)
- [Official Hermes Agent source: website/docs/user-guide/messaging/whatsapp.md](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/whatsapp.md#L9-L31)
- [Official Hermes Agent source: website/docs/user-guide/messaging/whatsapp.md](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/whatsapp.md#L92-L121)

---

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