Blog / WhatsApp setup
How to Connect Hermes Agent with a WhatsApp QR Session
WhatsApp setup is different from Telegram and Discord because it uses a QR linked-device session instead of a bot token. Deploy the Hermes Agent runtime first, scan the QR code from the intended WhatsApp account, and verify that the linked session stays healthy.
- 01
Deploy the runtime
Start the Hermes Agent deployment before opening the WhatsApp QR connection flow.
- 02
Scan the QR code
Use the intended WhatsApp account to scan the linked-device QR code before it expires.
- 03
Verify session health
Send a low-risk message and confirm Hermes Agent can receive and reply through the linked session.
- 04
Plan recovery
Keep a simple recovery process for expired QR codes, logged-out devices, and account access changes.
Four-step path
How do you connect a WhatsApp QR session?
The QR flow works best when the runtime is already running and the account owner is ready to scan from the correct phone.
- Step 01
Deploy the runtime
Start the Hermes Agent deployment before opening the WhatsApp QR connection flow.
- Step 02
Scan the QR code
Use the intended WhatsApp account to scan the linked-device QR code before it expires.
- Step 03
Verify session health
Send a low-risk message and confirm Hermes Agent can receive and reply through the linked session.
- Step 04
Plan recovery
Keep a simple recovery process for expired QR codes, logged-out devices, and account access changes.
How is WhatsApp QR setup different from bot tokens?
WhatsApp QR setup authorizes a linked-device session, while Telegram and Discord usually connect through bot tokens. That makes account access and session health the main WhatsApp concerns.
A QR session depends on the account that scanned it. If that account removes the linked device or the session expires, Hermes Agent may need a fresh QR connection even if the deployment itself is healthy.
Who should scan the WhatsApp QR code?
The person responsible for the WhatsApp account used by the assistant should scan the QR code, because the session represents linked-device access to that account.
Avoid scanning from a personal account unless that account is intentionally used for the workflow. Production support or operations flows should use the correct business-controlled account.
How do you know the WhatsApp session is healthy?
A healthy WhatsApp session shows a connected state, receives a test message, sends a reply, and remains linked after the first deployment check.
- Confirm the runtime is running before scanning.
- Send one test message from a known contact.
- Check the deployment dashboard for session state.
- Document who owns session recovery.
What should you do if the QR session disconnects?
If the WhatsApp session disconnects, restart the connection flow, scan a fresh QR code, and verify a new test reply before returning the assistant to live use.
Do not assume a model or prompt problem when WhatsApp stops responding. Check the linked-device session first, then inspect runtime logs and message routing.
Which primary sources support this page?
Product behavior is checked against the current deployment flow. These external links provide the upstream project or channel documentation used for setup details.
Direct answers
Frequently asked questions
Does WhatsApp setup use a bot token?
No. The current WhatsApp flow uses a QR linked-device connection instead of a pasted bot token.
Can the QR code expire?
Yes. If the QR code expires before scanning, restart the connection flow and scan the new code.
Can I scan the QR code before deployment?
No. The managed runtime should be running first so the session can attach to the active deployment.
Why did WhatsApp stop replying after it worked?
Check whether the linked-device session was removed, expired, or disconnected before debugging the model or prompt.
Key takeaways
- WhatsApp setup is different from Telegram and Discord because it uses a QR linked-device session instead of a bot token. Deploy the Hermes Agent runtime first, scan the QR code from the intended WhatsApp account, and verify that the linked session stays healthy.
- Start with one model, one channel, and one controlled test conversation.
- Use managed hosting when deployment speed matters more than operating the server yourself.
Continue the setup
Related Hermes Agent guides
Blog guide
How to Deploy Hermes Agent on WhatsApp
Deploy Hermes Agent on WhatsApp with a managed runtime, guided QR connection, model selection, connection checks, recovery steps, and practical security guidance.
Read nextBlog guide
Why Hermes Agent Is Not Sending or Receiving Messages
Troubleshoot Hermes Agent message failures across Telegram, Discord, and WhatsApp by checking channel access, runtime state, model keys, and logs.
Read nextBlog guide
How to Choose a Hermes Agent Channel
Compare Telegram, Discord, and WhatsApp for Hermes Agent deployment. Choose the best channel for support, daily briefings, and team operations.
Read next