AI Agents

Hermes Agent WhatsApp: Setup Step By Step

Julian Goldie — founder, AI Profit Boardroom
By Julian Goldie · 7 min read
Get The AI Profit Stack Join AIPB →
🎯 1,000+ done-for-you AI agent workflows 📅 4 live coaching calls every week 🛡️ 7-day refund + 30-day ROI guarantee 👥 3,400+ AI operators inside

You can connect Hermes Agent WhatsApp two ways: the built-in Baileys bridge, which pairs by QR code like WhatsApp Web, or Meta's official WhatsApp Business Cloud API. The bridge is faster to set up but unofficial, and the Hermes docs warn it carries ban risk. The Cloud API is the stable, Meta-supported path, but it needs a Meta Business account, a public webhook URL, and it only lets the bot reply freely within 24 hours of a user's last message.

📺 Watch: Hermes AI Sales Agent Can Close Leads for You

🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside

This page puts the two side by side, gives the setup commands for each, and covers the access rules that stop random numbers reaching your agent. If you want to see how other business owners put agents to work, the AI Profit Boardroom is where members share their Hermes setups.

Bridge or Cloud API: pick your route

Baileys bridgeWhatsApp Business Cloud API
Setup commandhermes whatsapphermes whatsapp-cloud
Official?No. Emulates a WhatsApp Web sessionYes. Meta's supported path
Ban riskYes, per the Hermes docsNone, per the Hermes docs
AccountPersonal WhatsApp on a phoneMeta Business account and a business number
Public URLNot neededNeeded, HTTPS, for Meta's webhook
Runs onNode.js v20+ bridge processPython webhook server, no Node
GroupsYes, with a group policyNo. Direct messages only in v1
Voice repliesSent as MP3 filesNative voice notes with ffmpeg
24-hour reply windowNoYes. Templates not supported in Hermes yet

The Hermes docs sum it up plainly. Use the bridge for personal projects, quick demos and single-user setups, if you accept the risk to the bot's number. Use the Cloud API for a real business bot. Both adapters can run at the same time on different numbers.

Hermes Agent WhatsApp via the Baileys bridge

The bridge needs Node.js v20 or newer, npm, and a phone with WhatsApp. It has two modes:

Setup:

  1. Run hermes whatsapp. Choose bot or self-chat. The wizard installs the bridge and shows a QR code in your terminal.
  2. On your phone, open WhatsApp, Settings, Linked Devices, Link a Device, and scan the code.
  3. If WhatsApp asks for a passkey, run hermes whatsapp --passkey-browser followed by the path to your Chrome or Edge app.
  4. Add to ~/.hermes/.env: WHATSAPP_ENABLED=true, WHATSAPP_MODE=bot, and WHATSAPP_ALLOWED_USERS with phone numbers in country-code form and no plus sign, for example 15551234567.
  5. Start with hermes gateway, or hermes gateway install to run it as a service. The gateway starts the bridge from the saved session.

The session lives in ~/.hermes/platforms/whatsapp/session. It holds the keys to the WhatsApp account, so never share it or commit it. If the session breaks after a phone reset or a WhatsApp update, run hermes whatsapp again and rescan.

The rules for the bridge, from the docs: use a dedicated number, not your personal one. Don't send bulk or spam messages. Don't automate outbound messages to people who haven't messaged first. WhatsApp also updates its web protocol from time to time, which can break third-party bridges until Hermes updates.

Groups on the bridge. group_policy defaults to pairing, which forwards nothing from groups. Set it to allowlist and list group JIDs (they end in @g.us) to admit specific groups, or open for every group the bot is in. Add require_mention: true so it only answers @mentions, replies to it, or commands.

📺 Watch: This Hermes AI Sales Agent Is SCARY Good

The official route: WhatsApp Business Cloud API

Before you run the wizard, you need:

Then:

  1. Run hermes whatsapp-cloud. It asks for each value and checks it as you paste. It catches the most common mistake: pasting the phone number into the Phone Number ID field. The ID is a 15 to 17 digit number shown below the From dropdown on API Setup.
  2. Paste the access token (it starts with EAA) and the App Secret from Settings, Basic. Without the App Secret, Hermes refuses inbound messages.
  3. Start the gateway with hermes gateway.
  4. In the Meta dashboard, WhatsApp, Configuration, edit the webhook. Set the Callback URL to your tunnel address plus /whatsapp/webhook, and paste the Verify Token the wizard generated. Click Verify and save.
  5. Under Webhook fields, subscribe to messages. Without this, Meta delivers nothing.

Temporary access tokens last 24 hours. For a bot that stays up, the docs walk you through a System User token with expiration set to Never. While your Meta app is in development mode, Meta also limits which numbers the bot can message, up to five, until App Review.

On the Cloud API, the bot can take in text, images, voice notes (transcribed), documents and button taps. It sends text, images, voice notes, video and documents. Questions and command approvals show as tap buttons, and you see blue ticks and "typing…" while it works.

📺 Watch: Hermes Agent Just Made Multi-Device AI Agents INSANE!

Who can reach the bot

The Hermes docs state that by default the gateway denies every user who is not on an allowlist or paired via DM. Both WhatsApp routes follow that.

Cloud API allowlist. WHATSAPP_CLOUD_ALLOWED_USERS=15551234567,15557654321. Without it, the docs say every inbound message is denied.

Bridge allowlist or pairing. Use WHATSAPP_ALLOWED_USERS, or remove it and rely on pairing. An unknown sender gets a one-time code, which you approve with hermes pairing approve whatsapp followed by the code. hermes pairing list shows who is waiting and hermes pairing revoke whatsapp removes someone. Codes expire after an hour. For a private number, the docs suggest whatsapp.unauthorized_dm_behavior: ignore, so strangers get silence instead of a code.

WHATSAPP_ALLOWED_USERS=* or an allow-all flag opens the bot to anyone. Don't do that on a bot that can run commands.

Want help deciding which route fits your business? Book a free AI strategy session.

Limits to plan around

The 24-hour window. Meta only allows free-form messages within 24 hours of the user's last message. Outside that, Meta requires a pre-approved template, and the docs say template support is not built into Hermes yet. So a cron job that delivers to WhatsApp after a quiet day fails with error 131047. The fix is for the user to message the bot again. Normal back-and-forth chat is not affected. Keep that in mind before pointing a Hermes Agent cron job at WhatsApp.

No groups on the Cloud API. Direct messages only for now. Use the bridge if you need groups.

Not a broadcast tool. Neither route is built for mass messaging. The bridge docs warn against bulk sends outright. Hermes on WhatsApp is a conversation with people who message you.

One gateway, every platform

Since v0.23.0, released on 5 November 2026, one gateway per machine owns every session. Nous Research says the CLI, TUI, desktop app, editors, bots and cron all attach as clients, with one queue and one history. Your WhatsApp chat is the same session wherever you open it.

That gateway can also run your other platforms. See Hermes multi-gateway connections for running several, and best messaging app for Hermes Agent to pick a main one. Platform guides in this set: Hermes Agent Telegram, Hermes Agent Slack and Hermes Agent Discord.

The Agent OS guide shows the full agent system. Goldie Bench helps you choose the model.

Members of the AI Profit Boardroom share the agents they run for customer questions and daily admin. If you want a plan built for your own business, take a free AI strategy session.

FAQ

Will my WhatsApp number get banned using Hermes?

On the Baileys bridge there is a risk, because it is not an official API. Use a dedicated number and keep it conversational. The Cloud API has no ban risk, per the Hermes docs.

Why did my scheduled WhatsApp message fail with error 131047?

The 24-hour window closed. On the Cloud API, Hermes can only send free-form messages within 24 hours of the user's last message, and templates are not supported yet.

Can Hermes join WhatsApp groups?

On the bridge, yes, once you set group_policy to allowlist or open. On the Cloud API, no. It handles direct messages only.

Ready to have an agent answering on WhatsApp? Book a free AI strategy session and plan the first jobs it should take on.

What members say about the AI Profit Boardroom

Read all 114 reviews on Skool →

★ 4.9 out of 5 from 114 member reviews on Skool

Yosuke Sato, AI Profit Boardroom member review (5 stars, paying member for 17 months): The best Skool course you get for AI! I have attended a few Skool courses before, but AI Profit Boardroom is the most active community and has great support from the management team, including Julian! You can get the most up-to-date information and practical implementations in this community. I highly recommend this!Mazzie T, AI Profit Boardroom member review (5 stars, paying member for 10 months): My mind is blown everyday with all the content and the incredible information. So much support and I love the personalised attention and quick responses. The community is great and people are very responsive and helpful.Rene Clayton, AI Profit Boardroom member review (5 stars, paying member for 9 months): The AI Profit Boardroom is a GAME CHANGER people. I could not be more thrilled that I joined!! So much support, more information than you can even consume, a huge value for what the small fee was. I have grown my business, my knowledge and my FUN!. SUCH a fantastic leader and group of humans. I am incredibly honored to be a part of this fantastic group of intelligent humans :-) THANK YOU!Arpiet Malpani, AI Profit Boardroom member review (5 stars, paying member for 8 months): Incredible learning from Julian and team. I started out in march and was able to build end to end SAAS with the help and learning from this group. I am incredibly thankful to Julian for crazy support and prompt response.James Grimm, AI Profit Boardroom member review (5 stars, paying member for 7 months): I asked Julian for help finding local business websites with little to no traffic. Julian was gracious in providing me my personal "how-to" video instruction. Wow, this is the pinnacle of customer service! I am just one of 3,400 subscribers and Julian took the time to help me personally. Thank you Julian for your assistance and outstanding custoemr support and care. James (Jim) GrimmNick Good, AI Profit Boardroom member review (5 stars, paying member for 4 months): I’m part of many AI groups and hands down, what Julian Goldie, has built here…the classroom trainings are amazing, but the community he has created is second to none (the community is worth the cost of joining!). If you’re looking to become the AI expert and build/create something meaningful, then AI Profit Boardroom is for YOU!Steven Gray, AI Profit Boardroom member review (5 stars, paying member for 4 months): Been in awhile. I’m a dad on a factory shift, not a tech bloke. Julian’s lot showed me how to use AI without drowning in tools. Avatar, voice, the workflow thinking — that’s what I needed. If you’re stuck on “where do I start,” this group’s worth it. I always read them.Steve Erickson, AI Profit Boardroom member review (5 stars, paying member for 4 months): I asked Julian a simple question, and he ended up creating a 10-minute video and a guide breaking down in extreme detail what I had asked. Amazing response!Rod Martin, AI Profit Boardroom member review (5 stars, paying member for 3 months): Julian is brilliant, and more prolific than I can keep up with (which is a great thing). His AgentOS is remarkable, and he is THE go-to guy for what you can really do (and not do) with the ever-increasing deluge of new AI upgrades and tools. HIGHLY recommend.Daniel Shulman, AI Profit Boardroom member review (5 stars, paying member for 4 months): Julian is very helpful. He doesn't try sell stuff you dont need and will give you a straight answer to your questions.Rj Herzog, AI Profit Boardroom member review (5 stars, paying member for 5 months): Top notch. If you are searching & searching thinking there is always something better out there.... You just found it. No need to look any further. Goldie covers it all & is super helpful. Can't beat the group either. Really can't recommend this group enough.Jermey Matthews, AI Profit Boardroom member review (5 stars, paying member for 6 months): While he has the capacity to do it, Julian is definitely doing the unscalable things to support his community.

Ready To Join The #1 AI Community?

Join 3,400+ entrepreneurs inside the AI Profit Boardroom. Get the Agent OS, 1,000+ plug-and-play AI agent workflows, daily Q&A with Julian and 4 live coaching calls every week.

Join The AI Profit Boardroom →

7-Day No-Questions Refund • 30-Day ROI Guarantee

← Back to all posts