Hermes Agent WhatsApp lets people message your agent like any other contact. Hermes offers two ways to do it: a quick QR-code bridge for personal use, and Meta’s official Cloud API for a real business number. Picking the right one matters, so here’s the difference straight from the docs.
Key takeaways
- Bridge: scan a QR code, no Meta account, but unofficial with ban risk.
- Cloud API: Meta’s official route, no ban risk, needs a business account.
- Use a dedicated number, not your personal one.
- The Cloud API can only reply freely within 24 hours.
- Want WhatsApp handled for your business? Claim a free strategy session.
Why the gateway matters in v0.23
Hermes’ messaging gateway is one background process that connects to every platform you set up, keeps the sessions, runs cron jobs and delivers voice messages. Since v0.23.0 (5 November 2026), one gateway on each machine owns every conversation, and the CLI, TUI, Desktop, editors, bots and cron all attach to it. A chat you start in one place is the same chat everywhere, with one queue and one history.
The latest patch, v0.23.1 (9 November), fixes plugin installs so hermes plugins install sees the live catalog again. Update with hermes update.
1. Pick your route
The WhatsApp docs describe two integrations:
- Baileys bridge: emulates a WhatsApp Web session. It’s quick, needs no Meta account or public URL, and suits personal projects. It is not the official API, so the docs warn of a small risk of account restrictions.
- WhatsApp Business Cloud API: Meta’s official path. There’s no ban risk, but you need a Meta Business account, a dedicated business number and a public HTTPS URL for the webhook (Cloud API docs).
For a business bot that customers rely on, the docs point you to the Cloud API.
Want Hermes answering your customers on WhatsApp? Inside the AI Profit Boardroom you get the Agent OS — Hermes, OpenClaw, OpenCode, Claude and Codex in one place — plus step-by-step Hermes training and four live coaching calls a week.
Want a plan for your business first? Claim your free strategy session.
Join the AI Profit Boardroom →Claim Your Free SEO Strategy Session →
2. Quick setup with the bridge
hermes whatsappThe wizard asks whether you want a separate bot number (recommended) or a personal self-chat, installs the bridge (it needs Node.js 20 or later) and shows a QR code. In WhatsApp go to Settings → Linked Devices → Link a Device and scan it. Then start the gateway with hermes gateway.
To lower the risk, the docs say to use a dedicated number, avoid bulk messages and never message people who haven’t messaged first. If a WhatsApp update breaks the bridge, update Hermes and pair again.
3. The official Cloud API
hermes whatsapp-cloudThis wizard walks you through each Meta credential and checks it as you paste it. You expose the gateway with a tunnel such as Cloudflare Tunnel and register the webhook in Meta’s dashboard. You get images, voice notes that are transcribed, documents, tap-to-answer buttons for questions and approvals, read receipts and a typing indicator.
4. Limits to know before you launch
- 24-hour window: on the Cloud API, free-form replies only work within 24 hours of the customer’s last message. After that Meta needs a pre-approved template, and Hermes doesn’t support templates yet, so late cron messages fail.
- Groups: the Cloud API adapter handles direct messages only. Groups need the bridge.
- Groups on the bridge are off by default (
group_policy: pairing). You allow specific groups or all groups the bot is in.
That makes WhatsApp best for reactive chat: a customer messages, Hermes answers.
Want this set up for you instead of doing it yourself? Claim your free strategy session →
5. Who can message it
Set WHATSAPP_ALLOWED_USERS to the numbers allowed to use it (country code, no plus sign). With nothing set, the gateway denies every message. Strangers get a pairing code unless you set unauthorized_dm_behavior: ignore. Protect the session folder like a password.
Keep it locked down
The gateway’s default is safe: it denies everyone who isn’t on an allowlist or paired. You can list user IDs per platform, or let unknown people DM the bot for a one-time pairing code that you approve with hermes pairing approve. Codes expire after an hour.
The docs call allowing all users “NOT recommended for bots with terminal access”, and that’s the right call for any business. Keep the allowlist short and use /approve and /deny for risky commands.
My verdict
Test with the bridge on a spare number, then move a customer-facing bot to the Cloud API and plan around the 24-hour rule. Used for replies rather than mass messages, Hermes Agent WhatsApp is a strong channel for small businesses.
About Julian Goldie
I’m Julian Goldie — founder of Goldie Agency and the AI Profit Boardroom. I test new AI agents almost every day for 432K+ YouTube subscribers and run Hermes, OpenClaw, OpenCode, Claude and Codex side by side in my own Agent OS. Claim your free strategy session or join the AI Profit Boardroom.
Want another angle? Read the AI Profit Boardroom guide to Hermes Agent WhatsApp.
FAQ: hermes agent whatsapp
How do I connect Hermes Agent to WhatsApp?
Run hermes whatsapp for the QR-code bridge, or hermes whatsapp-cloud for Meta’s official WhatsApp Business Cloud API.
Is the Hermes WhatsApp bridge official?
No. It emulates WhatsApp Web, so the docs warn of a small account-restriction risk. The Cloud API is Meta’s official route.
Can Hermes send bulk WhatsApp messages?
No, and the docs advise against bulk or unsolicited messages. It’s built for conversations people start.
Why do late WhatsApp messages fail on the Cloud API?
Meta only allows free-form replies within 24 hours of the customer’s last message, and Hermes doesn’t support templates yet.
Does Hermes work in WhatsApp groups?
On the bridge, yes, once you allow the groups. The Cloud API adapter handles direct messages only.
Should I use my personal WhatsApp number?
The docs recommend a dedicated number for the bot, which also keeps risk away from your personal account.
Ready to put Hermes to work in your business? Join the AI Profit Boardroom for the Agent OS, setup training and daily updates.
Or claim your free strategy session and we’ll map out your setup.
Starting from zero? Get the free AI course and community.
Join the AI Profit Boardroom →Claim Your Free SEO Strategy Session →Get the FREE AI Course + Community →
Related reading
Last updated November 2026. This page is a living guide to hermes agent whatsapp — the facts here move fast and it is updated as they do.
