How-To Guide
Connect WhatsApp to Hermes Agent
Connect Hermes Agent to WhatsApp for AI assistance through the world's most popular messaging app.
Quick answer
Connect WhatsApp by enabling the WhatsApp messaging gateway in Hermes config and linking it to your number, so you reach the agent from the app you already use. As with any gateway, confirm the CLI agent works first; channel issues are usually provider or config problems surfacing through WhatsApp.
WhatsApp has over 2 billion users — connecting Hermes to it means your AI assistant is accessible from the app most people already use daily, without needing anyone to install anything new.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed and running
- ☑A dedicated phone number for the WhatsApp bot (Web bridge) OR a Meta Business account for the production API
- ☑A smartphone with WhatsApp installed for QR code scanning (Web bridge method)
Steps
- 1
Choose your bridge
Use the WhatsApp Web bridge (whatsapp-web.js) or Meta Business API for production
- 2
Install the WhatsApp plugin
hermes plugin install whatsapp or add whatsapp to your config.yaml plugins section
- 3
Authenticate
Scan the QR code with your WhatsApp mobile app to link the session
- 4
Configure allowed contacts
Set whatsapp: allowedNumbers: in config.yaml to restrict who can message Hermes
- 5
Restart and test
hermes restart — send a message from your phone to verify the connection
Pro Tips
- 💡Use the WhatsApp Web bridge for personal use — it's free and works immediately. Use Meta Business API only if you need to reach users who haven't messaged you first.
- 💡Set 'whatsapp: allowedNumbers' to your personal number only — bots that respond to everyone can get the account flagged by Meta
- 💡The WhatsApp Web session can expire after phone restarts — keep your phone charged and online
Troubleshooting
❌ QR code expires before scanning
✅ The QR code refreshes every 20 seconds. If you're too slow, a new one generates automatically. Check terminal output for the latest QR code.
❌ Bot stops responding after phone restart
✅ The WhatsApp Web session is tied to your phone being online. Ensure your phone stays powered and connected. Hermes will reconnect when the phone comes back online.
❌ Messages delivered but Hermes doesn't process them
✅ Check 'whatsapp: allowedNumbers' in config.yaml — if set, only numbers in this list are processed. Your number must be in international format (e.g. +14155552671).
FAQ
Do the people I message need to install anything?
No. WhatsApp connects Hermes to an app over two billion people already use, so you and anyone you authorize message the agent normally without installing new software.
Why are my WhatsApp replies delayed or missing?
Almost always the agent isn't running, the provider is rate-limited, or the gateway lost its session. Confirm Hermes responds in the CLI, then check the gateway and provider before blaming WhatsApp.
Is WhatsApp through Hermes private?
Messages route through your self-hosted Hermes and your model provider. Keep the host private and review which provider you send conversation content to if privacy is a concern.