WhatsApp: chat with Hermes from your phone

What WhatsApp 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.

Set it up

1. 1

   Run hermes whatsapp, choose bot or self-chat mode, let it install the bridge dependencies and display a QR code

2. 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. 3

   Add WHATSAPP_ENABLED=true, WHATSAPP_MODE=bot (or self-chat) and WHATSAPP_ALLOWED_USERS (digits with country code, no +) to ~/.hermes/.env

4. 4

   Start the gateway with hermes gateway, or install it as a service with hermes gateway install

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 and failure points

• 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

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

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