Connect WhatsApp to Hermes Agent
Connect Hermes Agent to WhatsApp for AI assistance through the world's most popular messaging app.
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.
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).