Hermes WhatsApp group chat support is built in, but it’s switched off by default. Out of the box, Hermes Agent ignores every WhatsApp group, because the default group policy forwards nothing. Here’s exactly what to change so your agent answers in the groups you choose, only when it’s mentioned, straight from the Hermes docs.
Key takeaways
- Groups need the Baileys bridge in bot mode. The Cloud API is DMs only.
- Default
WHATSAPP_GROUP_POLICY=pairingforwards nothing from groups. - Use
allowlistwith group JIDs, oropenfor every group. WHATSAPP_REQUIRE_MENTION=truestops it answering every message.- Want an AI agent answering your customers on WhatsApp? Claim a free strategy session.
How Hermes connects to WhatsApp
The WhatsApp docs explain that Hermes’ main WhatsApp integration is a built-in bridge based on Baileys. It acts like a WhatsApp Web session, so you don’t need a Meta developer account. There are two modes:
| Mode | What it is |
|---|---|
| bot (recommended) | A separate, dedicated number. Built for multiple users, lower ban risk. Groups are documented here. |
| self-chat | You message yourself on your own WhatsApp. |
Be honest with yourself about the risk. WhatsApp doesn’t officially support third-party bots outside the Business API, so the docs warn of a small risk of the account being restricted. They say to use a dedicated number, avoid bulk messages, and never message people who haven’t messaged first.
1. Pair the bot number
- Install Node.js v20+ and npm, because the bridge is a Node.js process.
- Register a dedicated number with WhatsApp on a phone.
- Run
hermes whatsapp, choose bot mode and scan the QR code via Settings → Linked Devices → Link a Device. QR codes refresh about every 20 seconds, and the terminal needs to be at least 60 columns wide.
# ~/.hermes/.env
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=447700900123,15551234567Allowed users are phone numbers with the country code, no + and no spaces. With no access control set at all, the gateway denies every incoming message.
Want an AI agent working inside your WhatsApp groups? 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. Turn groups on with group policy
Here’s the key line from the docs: “Groups are gated by group policy, not by the DM allowlist.” The setting is WHATSAPP_GROUP_POLICY in .env, or whatsapp.group_policy in config.yaml.
| Value | What happens |
|---|---|
pairing (default) |
Nothing from groups is forwarded |
allowlist |
Only the groups you list |
open |
Every group the bot is a member of |
disabled |
Groups off |
WHATSAPP_GROUP_POLICY=allowlist
WHATSAPP_GROUP_ALLOWED_USERS=120363001234567890@g.usThe allowlist takes comma-separated group JIDs, which look like 120363001234567890@g.us. The WhatsApp page doesn’t document a way to look one up, but WHATSAPP_DEBUG=true shows raw events in bridge.log. Then add the bot’s number to the group from a phone.
3. Stop it answering every message
By default the bot answers every admitted group message, which gets noisy fast. Set WHATSAPP_REQUIRE_MENTION=true (or whatsapp.require_mention: true) and it only answers @mentions, replies to the bot and /commands. Groups listed in free_response_chats are exempt.
Sender checks still apply inside groups. If WHATSAPP_ALLOWED_USERS is set, a participant has to be on it or paired. Without a sender allowlist, allowlist trusts the group list alone and admits everyone in a listed group. open still needs the participant paired, or WHATSAPP_ALLOW_ALL_USERS=true.
4. Shared or private conversations
The configuration docs cover group_sessions_per_user. It’s true by default, so each person in a group gets their own session. Set it to false for one shared session per group, where everyone shares context, token costs and interrupt state. DMs aren’t affected.
whatsapp.unauthorized_dm_behavior: ignorekeeps the bot silent to unknown DMs (the default sends a pairing code).- Replies start with “☤ Hermes Agent”. Set
whatsapp.reply_prefix: ""to remove it. - Changing any of these restarts the bridge on the next connection without re-pairing.
Want this set up for you instead of doing it yourself? Claim your free strategy session →
5. Start it and post to groups on a schedule
Run hermes gateway in the foreground, or hermes gateway install as a user service. Cron jobs can deliver to a group with whatsapp:<jid>, and WHATSAPP_HOME_CHANNEL sets a default chat. Bot mode also supports native polls, location pins and quoted replies.
What about the WhatsApp Cloud API?
Hermes also has hermes whatsapp-cloud, which uses Meta’s official WhatsApp Business Cloud API. It has no ban risk and no Node bridge, but its adapter handles direct messages only (v1), and the docs say to use the Baileys bridge if you need groups. Both adapters can run at the same time on different numbers.
Limits worth knowing
- One WhatsApp number is one Baileys session. You can’t bind several Hermes profiles to different groups on the same number. The FAQ suggests one profile, a separate number per profile, or Telegram/Discord.
- Session data lives in
~/.hermes/platforms/whatsapp/sessionand grants full account access. Don’t share or commit it. - If the session breaks after a phone reset or unlinking, re-pair with
hermes whatsapp.
My verdict
Use a dedicated number in bot mode, set the group policy to allowlist with your group JIDs, and turn on require-mention from day one. Done that way, Hermes WhatsApp group chat gives your team an AI agent in the groups where work already happens.
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 WhatsApp Group Chat.
FAQ: hermes whatsapp group chat
Can Hermes Agent reply in WhatsApp group chats?
Yes, with the Baileys bridge in bot mode. Change WHATSAPP_GROUP_POLICY from its default pairing, which forwards nothing from groups, to allowlist or open.
How do I make Hermes reply only when mentioned in a WhatsApp group?
Set WHATSAPP_REQUIRE_MENTION=true. The bot then answers only @mentions, replies to it, or /commands, except in groups listed in free_response_chats.
How do I allow only specific WhatsApp groups?
Set WHATSAPP_GROUP_POLICY=allowlist and list the group JIDs, like 120363001234567890@g.us, in WHATSAPP_GROUP_ALLOWED_USERS.
Does the WhatsApp Business Cloud API support group chats in Hermes?
No. The whatsapp_cloud adapter handles direct messages only in v1. The docs say to use the Baileys bridge for groups.
Can my WhatsApp number get banned using Hermes?
The docs say the Baileys bridge carries a small risk of restrictions because it’s unofficial. Use a dedicated number and avoid bulk or unsolicited messages.
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.
Ready to put AI agents 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 whatsapp group chat — the facts here move fast and it is updated as they do.
