Hermes WhatsApp group chat support runs through the Baileys bridge in bot mode, and it is off until you turn it on: the default group policy is pairing, which forwards nothing from groups. To get Hermes Agent answering inside a WhatsApp group, you switch the group policy to allowlist (with the group's JID) or open, decide which participants may talk to it, and, if you want a quiet bot, make it reply only when someone mentions it.
📺 Watch: New Hermes Agent Mobile App Is Absolutely INSANE!
🔥 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
That is the whole job in one paragraph. The rest of this page walks through each setting from the Hermes WhatsApp docs, the order to do them in, and the traps that make a group bot stay silent.
If you want the step-by-step video trainings, the installable Agent OS and four coaching calls a week while you set this up, join the AI Profit Boardroom. Over 3,400 members are building agents like this one right now.
How Hermes WhatsApp Group Chat Works
Hermes has two WhatsApp integrations. The main one is a built-in bridge based on Baileys, which emulates a WhatsApp Web session. It does not use the official Business API, and you don't need a Meta developer account.
The second is the WhatsApp Business Cloud API adapter. It is the official Meta path, but the docs say it handles direct messages only in v1. If you need group chats, the docs point you back to the Baileys bridge.
So every group setup on this page uses the Baileys bridge, in bot mode, on a dedicated phone number.
The key rule, in the docs' own words: "Groups are gated by group policy, not by the DM allowlist." Adding numbers to your DM allowlist does nothing for groups until the group policy lets them in.
Before You Start: Bot Mode and a Dedicated Number
The bridge has two modes. Bot mode uses a separate number that people message directly, and the docs recommend it for multiple users and lower ban risk. Self-chat mode is you messaging yourself on your own WhatsApp. Groups are documented under bot mode.
You need three things:
- Node.js v20 or newer and npm, because the bridge runs as a Node.js process.
- A phone with WhatsApp to scan the pairing QR code.
- A number for the bot that isn't already registered with WhatsApp, registered on a phone first.
The docs also carry a clear warning. WhatsApp doesn't officially support third-party bots outside the Business API, so the bridge carries a small risk of account restrictions. Use a dedicated number, keep usage conversational, and don't automate outbound messages to people who haven't messaged first.
Set It Up Step by Step
- Run hermes whatsapp and choose bot mode. You can also run hermes gateway setup and pick WhatsApp.
- On the bot's phone, open WhatsApp, go to Settings, Linked Devices, Link a Device, and scan the QR code in your terminal. QR codes refresh about every 20 seconds, and the terminal should be at least 60 columns wide.
- In ~/.hermes/.env, set WHATSAPP_ENABLED=true, WHATSAPP_MODE=bot and WHATSAPP_ALLOWED_USERS with phone numbers in country-code format, no plus sign and no spaces.
- Set the group policy: WHATSAPP_GROUP_POLICY=allowlist plus WHATSAPP_GROUP_ALLOWED_USERS with the group JID, or WHATSAPP_GROUP_POLICY=open.
- Optional: set WHATSAPP_REQUIRE_MENTION=true so the bot only answers mentions, replies and slash commands.
- Start the gateway with hermes gateway in the foreground, or hermes gateway install to run it as a user service. It starts the bridge from the saved session.
- Add the bot's number to the WhatsApp group from a phone. The docs describe open as admitting every group the bot "is a member of", so the number has to be in the group.
Changing any bridge setting later, such as the group policy, allowlists or mention settings, restarts the bridge on the next connection without re-pairing.
📺 Watch: How to Run Hermes Agent OS on a VPS
The Four Group Policies
The setting is WHATSAPP_GROUP_POLICY in the env file, or whatsapp.group_policy in config.yaml. The environment variables reference lists four values.
| Policy | What reaches Hermes from groups | When to use it |
|---|---|---|
| pairing (default) | Nothing | You only want DMs |
| allowlist | Only the groups whose JIDs you list | A team group or one customer group |
| open | Every group the bot is a member of | A bot number that only joins groups you control |
| disabled | Nothing | Group intake switched off on purpose |
For allowlist, list the groups as comma-separated group JIDs in WHATSAPP_GROUP_ALLOWED_USERS or whatsapp.group_allow_from. The docs show the format as 120363001234567890@g.us.
The WhatsApp page doesn't document a dedicated command for finding a group's JID. What it does document is debug mode: set WHATSAPP_DEBUG=true, restart the gateway, and raw message events show up in bridge.log.
Who Inside the Group Gets Through
Letting a group in is step one. Each sender is then checked like any other gateway user.
- If WHATSAPP_ALLOWED_USERS is set, a participant must be on that list or paired.
- With no sender allowlist, allowlist mode trusts the group list alone and admits every participant of a listed group.
- Open mode still needs the participant paired, or WHATSAPP_ALLOW_ALL_USERS=true.
That last point catches people. Open does not mean anyone in any group can talk to the bot.
And if you set no access control at all, the docs say the gateway denies all incoming messages as a safety measure.
For a private number, also set whatsapp.unauthorized_dm_behavior to ignore. The global default is pair, which sends unknown DM senders a pairing code.
📺 Watch: NEW Hermes Agent Cloud Update is INSANE!
Make It Reply Only When Mentioned
By default, the bot answers every admitted group message. In a busy group that gets noisy fast.
Set require_mention: true in config, or WHATSAPP_REQUIRE_MENTION=true in the env file. The bot then answers only @mentions, replies to the bot, or slash commands.
Groups you list in free_response_chats are exempt, so you can keep one small working group fully chatty and every other group mention-only.
One more detail from the docs: blue ticks are off by default. When you switch that bridge option on, only messages that pass the DM, group and mention filters get marked as read.
One Shared Brain or One Session Per Person
Group memory is controlled by group_sessions_per_user, documented on the configuration page.
The default is true. Each sender in a group gets their own session when the platform provides a user ID, so one person's long task doesn't fill another person's context.
Set it to false and the whole group shares one session. Everyone sees the same context, but they also share token costs, interrupt state and context growth. DMs aren't affected either way.
The session lifecycle docs add that WhatsApp IDs are canonicalized, so a JID and LID alias flip doesn't split a person into two sessions.
Post Scheduled Updates Into a Group
Hermes cron jobs can deliver into a WhatsApp chat with a whatsapp: target followed by the JID. The docs example is whatsapp:123456@g.us. WHATSAPP_HOME_CHANNEL sets a default chat for cron and notification delivery.
A simple small-business use: a morning summary posted into your staff group, while the same group can still mention the bot with questions during the day.
If you want help mapping which jobs belong in a group and which belong in DMs, book a free AI strategy session and we'll map it with you.
Limits Worth Knowing
- Cloud API is DMs only. The whatsapp_cloud adapter handles direct messages only in v1. Groups need the Baileys bridge.
- One number, one session. The Hermes FAQ says you can't bind several profiles to different chats on the same number. Its workarounds: one profile with personality switching, cron jobs, a separate number per profile, or Telegram and Discord.
- Protect the session folder. ~/.hermes/platforms/whatsapp/session grants full access to the WhatsApp account. Don't share or commit it.
- Desktop group chats are a different feature. The Hermes group chat rooms in Bot Mode are Desktop rooms for your Bots, not WhatsApp groups.
For the full DM setup and voice notes, read the Hermes Agent WhatsApp guide. To see how this fits a full agent setup, the Agent OS guide shows how Hermes sits next to your other agents, and Goldie Bench shows how the models you might plug in compare on the same tasks.
Troubleshooting a Silent Group Bot
- Nothing from any group: the group policy is still pairing. Change it to allowlist or open.
- One group works, another doesn't: under allowlist, the second group's JID is missing from the list.
- Some people get answers, others don't: WHATSAPP_ALLOWED_USERS is set and the silent people aren't on it or paired.
- Bot ignores normal messages: mention mode is on. Mention it, reply to it, or add the group to free_response_chats.
- Logged out: re-pair with hermes whatsapp. The v0.23.0 release notes also say the dashboard can now re-pair WhatsApp after a logout.
Stuck on a step? Get a free AI strategy session and bring your config.
FAQ
Can Hermes Agent reply in WhatsApp group chats?
Yes, through the Baileys bridge in bot mode. Change WHATSAPP_GROUP_POLICY from its default pairing, which forwards nothing from groups, to allowlist with group JIDs, or to open.
How do I make Hermes reply only when mentioned in a WhatsApp group?
Set WHATSAPP_REQUIRE_MENTION=true, or require_mention: true in config. The bot then answers only @mentions, replies to it, or slash commands, except in groups listed in free_response_chats.
Does the WhatsApp Business Cloud API support group chats in Hermes?
No. The docs say the whatsapp_cloud adapter handles direct messages only in v1, and to use the Baileys bridge if you need groups.
Does everyone in a WhatsApp group share one Hermes conversation?
Not by default. group_sessions_per_user is true, so each sender gets their own session. Set it to false for one shared session per group.
Set the group policy, add the bot to one test group, and mention it. Then get the trainings and the Agent OS inside the AI Profit Boardroom, or book a free AI strategy session to plan your Hermes WhatsApp group chat setup with us.
