How-To Guide
How to Connect WhatsApp to Hermes Agent
Set up Hermes Agent on WhatsApp with the Baileys QR bridge or Meta's official Cloud API, including allowlists, sessions, webhooks, voice notes, cron limits, and troubleshooting.
Quick answer
Run hermes whatsapp for the Baileys QR bridge or hermes whatsapp-cloud for Meta's official Business Cloud API. Baileys is the fast personal/group path but unofficial; Cloud API is the stable business path but needs a Meta account, dedicated number, HTTPS webhook, and compliance with the 24-hour reply window. Set the matching allowlist, start the gateway, and prove one harmless DM before enabling groups, media, cron, or powerful tools.
Hermes has two built-in WhatsApp integrations, and choosing the wrong instructions is the main source of setup confusion. The Baileys bridge is quick and personal but unofficial; Meta's Cloud API is the supported business path but requires a webhook and obeys Meta's messaging rules. This guide gives both exact paths without the obsolete plugin commands found in older tutorials.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed,
hermes doctorpassing, and one successful CLI model response - ☑For Baileys: Node.js 18+, npm, a WhatsApp phone, and preferably a dedicated bot number
- ☑For Cloud API: a Meta Business account, Meta app with WhatsApp enabled, dedicated business number, and public HTTPS tunnel or reverse proxy
- ☑A narrow list of phone numbers allowed to invoke the agent
- ☑A clear profile boundary for the memory, secrets, skills, and tools exposed through WhatsApp
Steps
- 1
Choose Baileys or WhatsApp Cloud API
Use Baileys for a quick personal bot, QR pairing, no public URL, and group support; use Meta's official Cloud API for a production business bot with a dedicated number and public HTTPS webhook.
- 2
Prove Hermes works before adding WhatsApp
Run
hermes doctor, then send one CLI prompt. If the model/provider already fails, fix that before debugging a messaging adapter. - 3
Run the correct setup wizard
Run
hermes whatsappfor Baileys orhermes whatsapp-cloudfor the official Meta path. You do not need to install a separate WhatsApp plugin. - 4
Pair Baileys by QR code
Open WhatsApp → Settings → Linked Devices → Link a Device, scan the terminal QR code, and confirm the session is saved under
~/.hermes/platforms/whatsapp/session. - 5
Or finish the Cloud API webhook
Create the Meta app and business number, use a permanent System User token for production, expose port 8090 through HTTPS, set the callback to
/whatsapp/webhook, verify the token, and subscribe to themessagesfield. - 6
Set an explicit allowlist
Use
WHATSAPP_ALLOWED_USERS=15551234567for Baileys orWHATSAPP_CLOUD_ALLOWED_USERS=15551234567for Cloud API. Store phone IDs with country code and no plus sign, spaces, or dashes. - 7
Start the gateway
Run
hermes gateway runfor foreground testing or install/start the background service withhermes gateway installandhermes gateway start. Then checkhermes gateway status. - 8
Send one end-to-end DM
From the allowlisted number, ask for a harmless reply that takes no external action. Confirm the inbound message and response in
~/.hermes/logs/agent.logand verify the active Hermes profile. - 9
Enable media and delivery deliberately
Configure STT before testing voice notes, verify vision routing before relying on images, set a WhatsApp home channel for cron only when appropriate, and remember that Cloud API free-form sends fail outside Meta's 24-hour window.
- 10
Expand access only after the smoke test
Baileys groups, broader contacts, project tools, and scheduled reports should come after one stable DM. Cloud API currently supports DMs in Hermes v1, not groups.
Pro Tips
- 💡Use
hermes whatsapp, nothermes plugin install whatsapp; WhatsApp is a built-in gateway integration. - 💡For Baileys, use a dedicated number, avoid bulk/cold outbound messaging, and protect the session directory like a credential.
- 💡For Cloud API production, replace Meta's 24-hour temporary token with a System User permanent token and keep the App Secret configured for webhook signature checks.
- 💡Set
whatsapp.unauthorized_dm_behavior: ignorewhen a private Baileys number should not return pairing codes to strangers. - 💡Run
/usageafter an expensive WhatsApp interaction and review group scope, message batching, main model, and auxiliary routes before assuming the channel itself is expensive. - 💡If the objective is reliable phone access rather than infrastructure control, compare the maintenance burden with the managed route on
/pricing.
Troubleshooting
❌ The Baileys QR code will not scan or keeps expiring
✅ Use a terminal at least 60 columns wide, scan the newest QR from the intended WhatsApp account, and rerun hermes whatsapp if pairing times out.
❌ Baileys worked once but stopped after a restart
✅ Confirm ~/.hermes/platforms/whatsapp/session exists and is writable. In Docker, persist it as a volume. Update Hermes and re-pair if WhatsApp invalidated the linked device.
❌ The gateway says WhatsApp connected but no reply arrives
✅ Prove the model works in the CLI, check the active profile and correct allowlist variable, inspect ~/.hermes/logs/agent.log for the inbound event, and verify only one gateway owns the session.
❌ Cloud API webhook verification says the URL could not be validated
✅ Check that the HTTPS tunnel is live, port 8090 reaches the gateway, the callback ends in /whatsapp/webhook, the verify token matches exactly, and the App Secret is configured.
❌ Cloud API returns Graph error 100
✅ Use Meta's 15–17 digit Phone Number ID, not the human phone number shown in WhatsApp.
❌ Cloud API returns Graph error 190
✅ The token is expired, revoked, or missing permissions. Generate a correctly permissioned System User token for production and restart the gateway.
❌ A cron or delayed Cloud API reply returns error 131047
✅ Meta's 24-hour customer-service window expired. Ask the user to message the bot again; Hermes does not yet implement approved template messages for re-engagement.
❌ Voice notes or images arrive but Hermes cannot use them
✅ Configure an STT provider for voice transcription and a vision-capable model or routing for images. Channel delivery alone does not add those model capabilities.
FAQ
What is the current Hermes WhatsApp setup command?
Use hermes whatsapp for the Baileys bridge or hermes whatsapp-cloud for Meta's official Cloud API. Older separate-plugin instructions are obsolete.
Do I need Meta Business to connect Hermes to WhatsApp?
Not for Baileys; it pairs like WhatsApp Web. Meta Business is required for the official Cloud API production path.
Does WhatsApp need a public URL?
Baileys does not. Cloud API does because Meta sends inbound messages to a public HTTPS webhook, normally /whatsapp/webhook on the Hermes gateway.
Can Hermes use WhatsApp groups?
Yes with Baileys. Hermes's Cloud API adapter currently handles direct messages only in v1.
Where does the Baileys session live?
Hermes stores it under ~/.hermes/platforms/whatsapp/session. Protect it like a password and persist it when using containers.
Can WhatsApp deliver Hermes cron reports?
Yes, but use a defined home channel and test delivery. Cloud API free-form delivery can fail when the recipient has not messaged the bot within 24 hours.
Related setup and cost guides
WhatsApp integration overview
Compare Baileys and Cloud API capabilities, risks, and operating models.
Gateway troubleshooting
Debug process, profile, allowlist, provider, and platform failures in order.
Run Hermes from your phone
Choose between chat gateways, browser access, and managed mobile operation.
Pricing and managed cloud
Avoid maintaining bridges, tunnels, webhooks, and gateway uptime yourself.