Hermes Agent WhatsApp: Bridge Or Cloud API Setup, Step By Step

Hermes Agent WhatsApp setup comes in two flavours, and the one you pick decides how much paperwork you do, how long your bot number survives and what the agent is allowed to send.

Route A is the built-in Baileys bridge: a QR scan, no Meta account, and a real chance of account restrictions.

Route B is Meta's official WhatsApp Business Cloud API: a Meta app, a public webhook and a strict 24-hour reply window, but no ban risk.

Below is exactly how I'd set up each one, the settings I change before anyone messages the bot, and the traps that eat an afternoon.

If you want my team to look at where an agent like this fits your business, book a free SEO strategy session.

Pick Your Route Before You Touch A Terminal

The bridge docs say it plainly: Hermes talks to WhatsApp by emulating a WhatsApp Web session, not through the Business API.

The Cloud API docs call the official route the production-grade path, with no Node.js subprocess and no QR codes.

Question	Route A: Baileys bridge	Route B: Cloud API
Command	`hermes whatsapp`	`hermes whatsapp-cloud`
Account	Personal WhatsApp on a spare number	Meta Business account, dedicated business number
Public URL	Not needed	Required, HTTPS
Ban risk	Yes, unofficial	No, officially supported
Groups	Supported, gated by policy	Direct messages only in v1
Late replies	No 24-hour rule	Free-form only within 24 hours of the user's last message

My rule: the bridge for an owner or a small staff group talking to their own agent, the Cloud API for anything a customer will ever see.

The docs say the two adapters can run side by side on different numbers, so you are not locked in.

Route A Prerequisites: Node 20, A Spare Number, A Phone

The bridge runs as a Node.js process, so you need Node.js v20 or newer plus npm on the machine running Hermes.

You also need a phone with WhatsApp to scan the pairing QR code.

There are two modes: a separate bot number, which the docs recommend, or personal self-chat, where you message yourself.

Self-chat is fine for a ten-minute test on your own phone.

For anything that stays running, register a number that is not your personal one, because that keeps any restriction away from the account your family and suppliers use.

The page lists a few ways to get a second number; check the terms of whichever one you choose, since the docs note WhatsApp blocks some VoIP numbers.

Pair The Bridge With hermes whatsapp

hermes whatsapp

The wizard asks for bot or self-chat mode, installs the bridge dependencies, prints a QR code and waits.

On the bot phone, open WhatsApp, go to Settings, then Linked Devices, tap Link a Device and point the camera at the terminal.

If the code looks broken, widen the terminal to at least 60 columns; the troubleshooting table also says QR codes refresh roughly every 20 seconds.

If WhatsApp asks for a passkey after the scan, rerun setup with the path to an installed Chrome or Edge:

hermes whatsapp --passkey-browser "/absolute/path/to/browser"

That passkey flow needs a graphical desktop on the same machine, so it will not work over a headless SSH session.

Lock Down Access Before The First Message

Add the basics to ~/.hermes/.env:

WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=447700900123,447700900456

Numbers go in with the country code and without the plus sign or spaces.

With no allowlist at all, the gateway refuses every incoming message, which is the safe default the messaging overview describes for a bot with terminal access.

The same overview calls allow-all "NOT recommended for bots with terminal access", so I never set WHATSAPP_ALLOWED_USERS=* on a working agent.

By default a stranger who messages the number gets a pairing code you can approve from the terminal.

On a private bot number I switch that off so strangers get silence:

whatsapp:
  unauthorized_dm_behavior: ignore

That goes in ~/.hermes/config.yaml, and the docs say it is usually the better choice for a private number.

🔥 Want the WhatsApp agent already wired into a working Agent OS? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members comparing gateway setups. → Join the AI Profit Boardroom

Groups On The Bridge: Policy, JIDs And Mentions

Groups ignore the DM allowlist and follow a group policy instead.

The default policy is pairing, which forwards nothing from any group, so adding the bot to a team chat does nothing until you change it.

WHATSAPP_GROUP_POLICY=allowlist
WHATSAPP_GROUP_ALLOWED_USERS=120363001234567890@g.us
WHATSAPP_REQUIRE_MENTION=true

The allowlist takes group JIDs, the long IDs ending in @g.us, not group names.

The third policy, open, admits every group the bot belongs to, and I skip it.

If WHATSAPP_ALLOWED_USERS is also set, each person in the group must be on it or paired, which is the tight setup I prefer.

With require-mention on, the agent answers only @mentions, replies to its own messages and slash commands, so it stays quiet during normal chatter.

Keep The Bridge Alive: Sessions, Re-Pairing, Service Mode

hermes gateway install

That installs the gateway as a user service, and on Linux sudo hermes gateway install --system makes it start at boot.

The bridge stores its login under ~/.hermes/platforms/whatsapp/session, so restarts do not need a new scan.

That folder holds full session credentials, and the docs say to protect it like a password and lock it with chmod 700.

WhatsApp updates its Web protocol from time to time, which can break third-party bridges for a while.

When that happens, update Hermes and run hermes whatsapp again to re-pair.

On macOS, if the service says Node.js is missing while it works in your shell, rerun hermes gateway install so launchd picks up your current PATH.

Route B: Build The Meta App

You need a Meta Business account first.

At developers.facebook.com/apps, create an app with the use case "Connect with customers through WhatsApp", pick or create a business portfolio, and open the API Setup page.

Check a WhatsApp Business Account is linked, then collect the values the wizard will ask for.

Phone Number ID: the 15 to 17 digit ID under the From dropdown, not the phone number itself.
Access Token: starts with EAA; the temporary one expires after 24 hours.
App Secret: from Settings, then Basic; without it Hermes refuses inbound delivery with a 503.
WABA ID: optional, and when set, inbound webhooks must match that business account.

Run hermes whatsapp-cloud And Wire The Webhook

hermes whatsapp-cloud

The wizard checks every credential as you paste it, and it catches the classic mistake of putting the phone number in the Phone Number ID field.

Meta delivers inbound messages by HTTPS POST, so the gateway has to be reachable from the internet; the docs recommend Cloudflare Tunnel.

cloudflared tunnel --url http://localhost:8090

A quick tunnel URL changes every time cloudflared restarts, so set up a named tunnel before you rely on it.

In the Meta dashboard, open WhatsApp, then Configuration, edit the webhook, and enter your tunnel address followed by /whatsapp/webhook plus the verify token the wizard generated.

Click Verify and save, then under Webhook fields subscribe to messages, or nothing will arrive.

Finally set WHATSAPP_CLOUD_ALLOWED_USERS; without it every inbound message is denied, on purpose.

In development mode Meta only lets the bot message up to five numbers you add yourself, and App Review lifts that limit.

Swap The 24-Hour Token For A Permanent One

A temporary token generated today stops working tomorrow, and the error you will see is Graph error 190 with subcode 463.

For anything long-lived, create a System User in Business settings with the Admin role and assign it your app and WhatsApp account.

Generate a token with business_management, whatsapp_business_messaging and whatsapp_business_management, set expiry to Never, and paste it into WHATSAPP_CLOUD_ACCESS_TOKEN.

Restart the gateway after the swap.

Treat that token and the App Secret like passwords, because the docs say the secret lets anyone forge webhook payloads.

📞 Want a second pair of eyes on how an agent fits your marketing? Book a free SEO strategy session and my team will walk through your site, your content and where automation helps. → Grab a free call with my team

The 24-Hour Window Will Break Your Cron Jobs

This is the limit that catches people on Route B.

Meta accepts free-form messages only within 24 hours of the user's last inbound message, and outside it only pre-approved message templates.

The Cloud API page states that template support "is not yet implemented in Hermes".

So a morning briefing delivered to WhatsApp works while you keep chatting with the bot, then fails with Graph error 131047 after a quiet day.

The fix is boring: send the bot a message each day, or point long-gap cron jobs at a different platform.

The bridge has no such window, which is one reason I keep internal briefings there.

Neither route is a way to message people who have not contacted you, and the bridge docs say outright not to automate outbound messages to anyone who has not messaged first.

Voice Notes, Files And Buttons On Each Route

Both routes transcribe incoming voice notes with your configured speech-to-text provider, such as local faster-whisper.

On the bridge, spoken replies go out as MP3 attachments.

On the Cloud API, install ffmpeg and replies arrive as real green voice-note bubbles; without it you get MP3 files.

The Cloud API also turns clarify questions, dangerous-command approvals and slash-command confirms into tap buttons, and shows read ticks and typing.

The bridge renders multiple-choice clarify questions as native polls, never approvals, and can send location pins.

Long replies split at 4,096 characters per message on both.

One note: the overview's capability table shows a dash for voice on the bridge, while the bridge page documents voice in and MP3 out, so trust the dedicated page.

Five Gotchas I'd Check First

Messages vanish: the sender's number is missing from the allowlist, or has a plus sign in it.
Webhook will not verify: stale tunnel URL, mismatched verify token, gateway not running, or no App Secret.
Graph error 100: you pasted the phone number into the Phone Number ID field.
Bridge logged out: WhatsApp unlinks devices after long inactivity, so keep the phone online and re-pair.
Group stays silent: the group policy is still pairing.

Set WHATSAPP_DEBUG=true and restart the gateway to see raw bridge events in bridge.log.

Three Small-Business Setups, Step By Step

A plumber logging jobs from the van

Bridge in bot mode on a spare number, allowlist set to the plumber's own number.
After each visit, he sends a voice note: address, work done, parts used.
Hermes transcribes it and adds a line to a job log file on the machine.
At 6pm a cron job sends him the day's list to check, and the job text says "draft only, send nothing to customers".

A salon owner's daily rundown

Bridge again, because a daily briefing would hit the 24-hour wall on the Cloud API.
She forwards supplier price lists and stock photos to the bot during the week.
Each morning she asks what to reorder, and the agent answers from the files she sent.

An agency team chat

Bridge with group_policy set to allowlist and the team group's JID added.
Staff numbers on WHATSAPP_ALLOWED_USERS and require-mention switched on.
Someone @mentions the bot with a client brief, and it replies in the group with an outline for a person to edit.

For more customer-facing ideas, my Hermes customer support walkthrough covers the wider workflow; on WhatsApp, keep anything customers see on the Cloud API, staff-checked and inside the window.

The gateway itself is one process per machine since v0.23.0, so the chat you start on WhatsApp is the same session you see in the CLI or desktop app.

Want help planning the rest of your stack? Join the AI Profit Boardroom for the trainings and calls.

Also On Our Network

FAQ: Hermes Agent WhatsApp

Which command sets up the Hermes WhatsApp bridge?

Run hermes whatsapp, choose bot or self-chat mode, and scan the QR code from WhatsApp under Settings, Linked Devices.

Why does my Hermes WhatsApp bot ignore messages?

Usually the sender is not on WHATSAPP_ALLOWED_USERS, or the number was entered with a plus sign. Without an allowlist the gateway denies everything.

Why do my WhatsApp cron messages fail on the Cloud API?

Meta only allows free-form messages within 24 hours of the user's last message. After that it needs templates, which Hermes does not support yet, so you get error 131047.

Can the Cloud API route join WhatsApp groups?

Not yet. The Hermes Cloud adapter handles direct messages only in v1, and the docs point to the bridge for groups.

Do I need a public URL for the bridge?

No. Only the Cloud API needs a public HTTPS webhook, which the docs suggest exposing with Cloudflare Tunnel.

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

About Julian

I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.

I help business owners scale with AI agents, automation and SEO.

I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
I've grown a YouTube channel to 400,000+ subscribers.
I wrote "Link Building Mastery".
My Udemy courses have taught over 29,000 students.

→ Get my best AI training inside the AI Profit Boardroom

Pair the spare number tonight, set the allowlist before anyone texts it, and book a free SEO strategy session or join the AI Profit Boardroom if you want help planning your Hermes Agent WhatsApp setup.