Integration
Hermes Agent WhatsApp Integration: Baileys vs Cloud API
Connect Hermes Agent to WhatsApp with the quick Baileys bridge or Meta's official Cloud API. Compare setup, ban risk, webhooks, groups, voice notes, access control, cron delivery, and gateway recovery.
Quick answer
Hermes Agent supports two WhatsApp paths. Use hermes whatsapp for the quick Baileys bridge: it pairs by QR code, needs no public webhook, and supports personal accounts and groups, but it is unofficial and carries account-ban risk. Use hermes whatsapp-cloud for Meta's official Business Cloud API: it is the production path for customer-facing bots, but it needs a Meta Business account, a dedicated number, a public HTTPS webhook, and compliance with Meta's 24-hour conversation window. In either case, allowlist one sender and prove one DM before enabling groups, cron delivery, or powerful tools.
Managed cloud · API costs included · No gateway maintenance
Best for
Personal mobile agents that use a dedicated WhatsApp number or self-chat.
Customer-facing business bots that need Meta's official Cloud API and signed webhooks.
Mobile approvals, voice/image handoffs, incident summaries, and short operational requests.
Teams comparing self-hosted gateway maintenance with managed FlyHermes access.
Features
- ✓Two supported paths: the Baileys WhatsApp Web bridge and Meta's official WhatsApp Business Cloud API
- ✓QR-code setup for personal projects with
hermes whatsapp - ✓Production business setup with
hermes whatsapp-cloud, signed webhooks, and a dedicated number - ✓Inbound images, voice notes, documents, and reply context when the selected adapter supports them
- ✓Phone-number allowlists, DM pairing, and profile-level tool boundaries
- ✓WhatsApp delivery targets for cron reports and agent notifications
- ✓Gateway health checks, persistent sessions, reconnection, and re-pairing guidance
- ✓A managed FlyHermes path for teams that do not want to maintain Node bridges, tunnels, webhooks, or uptime
Setup path
- 1Choose Baileys for a personal or small-group bot, or WhatsApp Cloud API for a production business bot.
- 2Run
hermes whatsappfor Baileys orhermes whatsapp-cloudfor the official Cloud API wizard. - 3For Baileys, scan the QR code from WhatsApp Settings → Linked Devices; for Cloud API, complete the Meta app, token, and webhook flow.
- 4Set a narrow sender allowlist:
WHATSAPP_ALLOWED_USERSfor Baileys orWHATSAPP_CLOUD_ALLOWED_USERSfor Cloud API. - 5Start or restart the Hermes gateway and verify
hermes gateway status. - 6Send one harmless DM, inspect
~/.hermes/logs/agent.log, and prove the reply came from the intended profile. - 7Only after the DM works, enable groups, voice/media, cron delivery, customer workflows, or broader tools.
Choose the right WhatsApp path first
The setup differs completely depending on whether you need a personal agent or a customer-facing business bot. The step-by-step WhatsApp guide covers both paths, while this page explains the operating decision.
- •Baileys bridge: fastest personal setup, QR pairing, no Meta developer account, no public URL, group support, and an unofficial-protocol ban risk.
- •WhatsApp Cloud API: Meta-supported production path, dedicated business number, public signed webhook, stable credentials, direct messages in Hermes v1, and Meta's 24-hour customer-service window.
- •Both adapters can run at the same time against different numbers, but each needs its own allowlist and delivery target.
Baileys bridge: the quick personal-agent path
Run hermes whatsapp, choose a separate bot number or self-chat mode, and scan the terminal QR code from WhatsApp's Linked Devices screen. Hermes saves the encrypted session under ~/.hermes/platforms/whatsapp/session; protect that directory like a password and persist it when using Docker. The bridge requires Node.js and npm, but it does not require Chromium or Puppeteer.
- •Use a dedicated number rather than your personal account when possible.
- •Keep usage conversational; do not bulk-message or automate cold outbound sends.
- •If WhatsApp changes its Web protocol, update Hermes and re-pair before changing providers or prompts.
Cloud API: the production business path
Run hermes whatsapp-cloud when stability and Meta support matter more than setup speed. The wizard validates the Phone Number ID, access token, App Secret, verify token, allowlist, and webhook settings. You still need a public HTTPS route to the gateway—commonly a Cloudflare Tunnel, ngrok, or your own reverse proxy—and you must subscribe Meta's webhook to the messages field.
- •Use a System User permanent token for production; Meta's temporary setup token expires after 24 hours.
- •Keep
WHATSAPP_CLOUD_APP_SECRETconfigured so Hermes verifies webhook signatures. - •Cloud API in Hermes currently handles DMs, not group chats; use Baileys when groups are required.
- •Free-form outbound replies are limited to 24 hours after the user's last message; delayed cron sends outside that window need Meta templates, which Hermes does not yet implement.
Fail closed before connecting tools
A WhatsApp message can reach the same terminal, files, browser, MCP servers, and integrations available to the active Hermes profile. Set WHATSAPP_ALLOWED_USERS or WHATSAPP_CLOUD_ALLOWED_USERS before the first live test. If a private Baileys number should stay silent to strangers, set whatsapp.unauthorized_dm_behavior: ignore rather than returning pairing codes.
- •Start with one sender and one read-only prompt.
- •Use a dedicated Hermes profile when the channel owns project-specific secrets, memory, or tools.
- •Keep irreversible commands behind approvals and run the gateway troubleshooting checklist before expanding access.
Voice, images, documents, and long replies
Both modern WhatsApp adapters can pass useful media into Hermes. Voice notes require a configured speech-to-text provider; image understanding requires a vision-capable model or routing; and Cloud API documents can be downloaded for tool access. Long replies are split into 4,096-character chunks, and Markdown is converted to WhatsApp-friendly formatting.
- •Baileys batches rapid message fragments by default so paste-splits do not trigger several expensive agent runs.
- •Cloud API can show native buttons for clarifications and dangerous-command approvals.
- •Check provider costs and rate limits before enabling busy groups, voice, or frequent scheduled reports.
Self-hosted WhatsApp vs managed mobile access
Self-hosting is a good fit when you want full control and are willing to maintain the gateway. Baileys adds a Node subprocess, pairing state, and protocol updates; Cloud API adds Meta credentials, a public HTTPS webhook, token rotation, and the 24-hour window. If your actual goal is simply an always-on Hermes agent from your phone, FlyHermes is the managed route without owning that operations stack.
- •Choose self-hosting for custom infrastructure, private profiles, and deep tool control.
- •Choose managed hosting when uptime, mobile access, and fewer bridge/webhook failures matter more than server control.
- •Use the dedicated phone access guide to compare WhatsApp with Telegram, Discord, and browser access without mixing their setup instructions.
The setup is now a two-path decision
Older instructions that say to install a WhatsApp plugin or use generic allowedNumbers config are obsolete. Current Hermes ships two built-in adapters: Baileys via hermes whatsapp, and the official Meta Cloud API via hermes whatsapp-cloud.
A connected gateway is not an end-to-end test
After setup, send a real message from an allowlisted number, confirm the inbound event in the gateway log, verify the active profile, and wait for the reply. A saved QR session, green webhook check, or gateway status result alone does not prove the provider and delivery path work.
Common setup issues
- Baileys QR code will not scan — widen the terminal, use the latest refreshed code, and verify you are linking the intended WhatsApp account.
- Baileys session disappears after restart — persist and protect
~/.hermes/platforms/whatsapp/session; mount it as a volume in Docker. - Bridge reconnect loop after an update — update Hermes, fully restart the gateway, and re-pair if WhatsApp invalidated the linked session.
- No inbound message — verify the correct allowlist variable, country code with no
+for Baileys/Cloud IDs, active profile, and inbound event in~/.hermes/logs/agent.log. - Cloud webhook validation fails — check the live HTTPS tunnel, exact verify token, running gateway, App Secret,
/whatsapp/webhookpath, andmessagessubscription. - Cloud error 190 — replace an expired/invalid Meta access token; production should use a correctly permissioned System User token.
- Cloud error 131047 — the 24-hour service window expired; the user must message again or an approved template is required.
- High token usage — send
/usagein the same chat, reduce group/free-response scope, tune batching, and review model plus auxiliary-provider routes.
Keep building the workflow
WhatsApp setup guide
Follow the exact Baileys and Cloud API setup paths with commands and smoke tests.
Gateway troubleshooting
Diagnose profile, process, provider, allowlist, bridge, and delivery failures in order.
Run Hermes from your phone
Compare WhatsApp with Telegram, Discord, and browser access by operating model.
Pricing and managed cloud
Choose managed hosting when mobile uptime matters more than maintaining a bridge or webhook.
FAQ
Does Hermes Agent support WhatsApp?
Yes. Hermes supports the Baileys WhatsApp Web bridge for personal/small-group use and Meta's official WhatsApp Business Cloud API for production business bots.
Should I use Baileys or WhatsApp Cloud API?
Use Baileys when you want QR setup, personal accounts, no public webhook, or groups and accept unofficial-protocol risk. Use Cloud API for a customer-facing business bot where Meta support and stability justify the business account, dedicated number, webhook, and 24-hour messaging rule.
What commands start WhatsApp setup?
Run hermes whatsapp for the Baileys bridge or hermes whatsapp-cloud for Meta's official Cloud API. Then run or restart the Hermes gateway and test one allowlisted DM.
Can Hermes receive WhatsApp voice notes and images?
Yes. Voice notes can be transcribed when STT is configured, and images can be passed to vision-capable routing. Adapter capabilities and model/provider setup still determine the final behavior.
Why did a scheduled WhatsApp Cloud message fail?
Meta blocks free-form outbound messages more than 24 hours after the user's last inbound message. Hermes does not yet implement the approved-template workaround, so ask the user to message the bot again or choose another delivery channel for unattended reports.
Can I use WhatsApp groups?
The Baileys bridge supports groups. Hermes's WhatsApp Cloud API adapter currently handles direct messages only, so choose the adapter based on that requirement before setup.