Field notes · AI agents, Hermes & Claude Code By Julian Goldie

Hermes WhatsApp Group Chat: Set Up A Group Bot In 8 Steps (2026)

Groups are off until you change one setting. Here is the operator order: pair in bot mode, set the group policy, gate senders, then go mention-only.

Get The AI Profit Stack Join AIPB →
  • 01 1,000+ done-for-you AI agent workflows
  • 02 5 live coaching calls / week with me
  • 03 7-day refund, cancel anytime
  • 04 3,400+ AI operators inside

A Hermes WhatsApp group chat bot needs one change most people miss: the group policy, which ships set to pairing and forwards nothing from groups.

Fix that, pick who may talk, and decide whether the bot speaks only when called, and you have a working group agent.

Below is the exact order I'd set it up in, using the Baileys bridge in bot mode, with every setting taken from the Hermes WhatsApp docs.

If you'd rather have my team look at your setup with you, book a free SEO strategy session and bring your config.

What You're Building, And The Default That Blocks It

The goal is a dedicated WhatsApp number running Hermes Agent, sitting in one or more groups, answering the right people.

Out of the box it won't answer anyone in a group.

The docs spell it out: the group policy is the gate for groups, and the DM allowlist is a separate list.

So a long DM allowlist does nothing for a group until the group policy admits that group.

Keep that in mind and the rest of the steps make sense.

Pick The Right Adapter: Baileys Bridge, Not Cloud API

Hermes ships two WhatsApp adapters, and only one of them handles groups.

The Baileys bridge emulates a WhatsApp Web session. No Meta developer account, no public URL, quick to pair.

The Business Cloud API adapter is Meta's official path with no ban risk, but its own page says it handles direct messages only in v1 and tells you to use the Baileys bridge for groups.

The comparison table on that page lists groups as full support on Baileys and DMs only on Cloud.

For a group bot, the choice is made for you: Baileys, bot mode.

The two adapters can run side by side on different numbers, so you can keep a Cloud number for customer DMs and a Baileys number for groups.

Step 1: Get Node.js 20 And A Spare Number

The bridge runs as a Node.js process, so install Node.js v20 or newer with npm first.

Next, get a phone number that isn't registered with WhatsApp yet, install WhatsApp on a phone, and register that number.

Bot mode is the docs' recommended mode: a separate number people message directly, built for multiple users and lower ban risk.

Self-chat mode, where you message yourself, is for single-user testing. Groups are documented under bot mode, so skip self-chat here.

Step 2: Pair The Bot Number In Bot Mode

hermes whatsapp

The wizard asks for a mode. Choose bot.

It installs the bridge dependencies if needed and prints a QR code in the terminal.

On the bot's phone: WhatsApp, Settings, Linked Devices, Link a Device, then point the camera at the terminal.

Two gotchas from the troubleshooting table: the terminal needs 60+ columns, and the QR code refreshes about every 20 seconds, so restart the wizard if it times out.

Accounts that ask for a passkey need hermes whatsapp --passkey-browser with a path to Chrome or Edge, and that only works in an interactive terminal with a graphical browser, not a headless SSH session.

Prefer a guided flow? hermes gateway setup and pick WhatsApp does the same walk-through.

Step 3: Write The Access Block In .env

Open ~/.hermes/.env and add the required lines.

WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=15551234567,447700900123

Numbers go in with the country code, no plus sign and no spaces.

WHATSAPP_ALLOWED_USERS=* or WHATSAPP_ALLOW_ALL_USERS=true lets everyone in.

Leave all three unset and the gateway denies every incoming message, which the docs describe as a safety measure.

🔥 Want every Hermes setup walked through on video? 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 wiring up agents like this. → Join the AI Profit Boardroom

Step 4: Choose A Group Policy

The key is WHATSAPP_GROUP_POLICY in the env file or whatsapp.group_policy in config.yaml.

ValueEffect on groupsPick it when
pairingDefault. Forwards nothing from groups.The bot is DM-only
allowlistAdmits only the group JIDs you listYou know exactly which groups
openAdmits every group the bot is a member ofThe bot only ever joins groups you control
disabledGroup intake offYou want groups shut explicitly

The values come from the environment variables reference.

My default for a first group bot is allowlist. It is the narrowest setting that still works.

Step 5: Get The Group JID Into The Allowlist

WHATSAPP_GROUP_POLICY=allowlist
WHATSAPP_GROUP_ALLOWED_USERS=120363001234567890@g.us

Group JIDs end in @g.us. List several with commas.

The config.yaml twin of that variable is whatsapp.group_allow_from.

The WhatsApp page doesn't document a lookup command for a group's JID.

What it does give you is debug output: set WHATSAPP_DEBUG=true, restart the gateway, and raw message events land in bridge.log.

Step 6: Lock Down Who Can Talk Inside The Group

After a group is admitted, each sender is checked like any other gateway principal.

  • With WHATSAPP_ALLOWED_USERS set, a participant must be on it or paired.
  • With no sender list, allowlist trusts the group JID list alone, so every member of a listed group gets through.
  • open still requires the participant to be paired, or WHATSAPP_ALLOW_ALL_USERS=true.

A sender WhatsApp addresses by LID is matched through the phone number Baileys passes along with it, so a first message isn't dropped for lack of a mapping file.

For a private bot number, add this to config.yaml so strangers who DM it get silence instead of a pairing code:

whatsapp:
  unauthorized_dm_behavior: ignore

Step 7: Switch On Mention-Only Replies

An admitted group gets an answer to every message by default.

In a group of more than a few people, I'd turn on mention gating before the bot joins.

WHATSAPP_REQUIRE_MENTION=true

With that on, Hermes only responds to an @mention, a reply to one of its own messages, or a slash command.

Chats listed in free_response_chats skip the gate, which suits a two-person ops group where you want every line answered.

Two group-friendly behaviours work without any config in bot mode.

First, message batching. When someone pastes a burst of lines, the adapter waits for a short quiet period, 0.3 seconds by default, and sends them to the agent as one request. You can tune it with text_batch_delay_seconds (max 2.0) or set it to 0 to switch batching off.

Second, polls. When Hermes asks a multiple-choice clarifying question, it goes out as a native single-select WhatsApp poll, and a tap answers it. Approval prompts are never sent as polls.

Any bridge change like this restarts the bridge subprocess on the next connection. You don't have to scan the QR code again.

Step 8: Start The Gateway And Add The Bot To The Group

hermes gateway              # foreground
hermes gateway install      # user service

The gateway starts the WhatsApp bridge from the saved session.

Then, from a phone that can add people to the group, add the bot's number. The docs describe open as covering groups the bot "is a member of", so membership comes first.

Then run this first-test checklist in order:

  1. Mention the bot from an allowed number. It should answer.
  2. Post a normal message without a mention. With mention gating on, it should stay quiet.
  3. Reply to one of its messages. That counts as a trigger, so it should answer.
  4. Ask a colleague who isn't on the sender list to mention it. It should ignore them.
  5. Quote an earlier image and ask what it shows. Quoting media attaches it to the turn.

If all five behave, the access rules are doing their job.

Long answers split into chunks of up to 4,096 characters, and Markdown is converted to WhatsApp formatting, so bold text and links still read cleanly in the group.

Replies carry a "Hermes Agent" header by default. Set whatsapp.reply_prefix to an empty string to drop it.

📞 Want a second pair of eyes on your agent stack? Book a free SEO strategy session and my team will go through where a WhatsApp group bot fits your business. → Book your free session

Session Isolation: The Setting I'd Decide Before Launch

group_sessions_per_user lives in config.yaml and is documented on the configuration page.

Left at true, each person in the group gets a separate session whenever WhatsApp supplies a user ID.

Set to false, the group shares one session. Shared context, but also shared token costs, interrupt state and context growth.

The session lifecycle page shows WhatsApp group keys carry both the group and the participant, and WhatsApp IDs are canonicalized so JID and LID flips don't split a person in two.

For a staff group where each person runs their own tasks, keep the default. For a group planning one shared project, flip it.

Profiles, Ports And The One-Number Rule

One WhatsApp number is one Baileys session.

The Hermes FAQ is direct about it: you can't bind several profiles to different chats on the same number.

Its workarounds are one profile with personality switching, cron jobs, a separate number per profile, or Telegram and Discord.

If you do run a second profile on its own number, pair it with hermes -p work whatsapp.

Profiles that each run their own gateway need a distinct platforms.whatsapp.extra.bridge_port in their config.yaml. Under one multiplexed gateway, a secondary picks a free port between 3001 and 3999.

Scheduled Posts Into The Group

Cron output can go straight into a group. The delivery target format in the cron internals docs is whatsapp: plus the JID, for example whatsapp:123456@g.us.

WHATSAPP_HOME_CHANNEL sets the default chat for cron and notification delivery.

A pattern I like: a short morning digest posted into the team group, while the same group keeps mention-only replies for questions.

Gotchas I'd Check When The Bot Stays Silent

  • Policy still on pairing. Nothing from any group gets in.
  • Group JID missing or mistyped under allowlist.
  • Sender not on WHATSAPP_ALLOWED_USERS, or not paired, under open.
  • Mention mode on and nobody mentioned the bot.
  • Session invalidated after a phone reset or WhatsApp update. Re-pair with hermes whatsapp.
  • On macOS, a launchd service can't find Node. Run hermes gateway install again to re-snapshot your PATH, then hermes gateway start.

The v0.23.0 release notes also add that the dashboard can re-pair WhatsApp after a logout.

Keep ~/.hermes/platforms/whatsapp/session private. It holds full account credentials, so never share or commit it.

For the DM side of the same bridge, see the Hermes Agent WhatsApp setup.

If you want to turn agents like this into a working system, the AI Profit Boardroom has the trainings and the coaching calls to get you there.

Also On Our Network

FAQ: Hermes WhatsApp Group Chat

Why does my Hermes bot ignore every WhatsApp group?

The default group policy is pairing, which forwards nothing from groups. Set WHATSAPP_GROUP_POLICY to allowlist with group JIDs, or to open.

Where do I put the group JIDs?

In WHATSAPP_GROUP_ALLOWED_USERS in ~/.hermes/.env, or whatsapp.group_allow_from in config.yaml, comma-separated, each ending in @g.us.

Do I need to re-scan the QR code after changing group settings?

No. Changing a bridge setting such as the group policy or mention mode restarts the bridge on the next connection without re-pairing.

Can I run the group bot through the WhatsApp Cloud API instead?

No. The Hermes Cloud API adapter handles direct messages only in v1, so group chats need the Baileys bridge.

Can two Hermes profiles share one number for different groups?

No. One number is one Baileys session, so each profile needs its own number, or you use one profile with personality switching.

📺 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 number, set allowlist, mention the bot once to prove it works, and if you want help planning the rest of your agent stack, book a free strategy session or learn it step by step inside the AI Profit Boardroom for your next Hermes WhatsApp group chat.

§ Field reports

Real wins from inside the AI Profit Boardroom

See all 3,400+ members →
AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot

Scroll sideways →

⚑ Next step

Ready to run AI agents that actually do the work?

Join 3,400+ operators inside the AI Profit Boardroom. Get 1,000+ plug-and-play AI agent workflows, 5 coaching calls a week, and a community that holds you accountable.

Join The AI Agent Community →

7-day no-questions refund · Cancel anytime

Found this useful? Get more of this site in your Google.

One tap adds us as a preferred source — Google then shows you our posts more often in Search, Top Stories, and AI Overviews.

← Back to all posts