Guide
Hermes Agent + WhatsApp: Run Your Hermes Bot on WhatsApp
Hermes Agent has built-in WhatsApp support. Connect it to your WhatsApp account via QR code pairing and get an AI agent running in your WhatsApp DMs and group chats — powered by any model you choose.
What Is a Hermes WhatsApp Bot?
A Hermes WhatsApp bot is a full AI agent that operates through your WhatsApp account. It responds to natural language messages in DMs or group chats, uses tools, remembers context across conversations, and can be paired to multiple messaging platforms simultaneously alongside your WhatsApp connection.
Hermes Agent has WhatsApp support built-in — unlike OpenClaw, which requires a separately installed plugin. This means WhatsApp is available from the first deploy with no additional installation steps.
How WhatsApp Pairing Works
WhatsApp's API uses a QR code pairing flow to link a WhatsApp account to the Hermes agent. The process is similar to WhatsApp Web:
- Deploy your Hermes instance on OpenClaw Launch or self-hosted with WhatsApp enabled.
- Open the Hermes web dashboard (available on the instance's port 9119 or via the OpenClaw Launch dashboard link).
- Navigate to the WhatsApp section and click Connect.
- A QR code is displayed. Open WhatsApp on your phone, go to Settings → Linked Devices → Link a Device and scan the QR code.
- After scanning, WhatsApp links to Hermes. The agent can now send and receive messages through your WhatsApp account.
Option 1: WhatsApp on OpenClaw Launch (Easiest)
On OpenClaw Launch, WhatsApp is available in the channel selector during Hermes deploy. No plugin installation needed — it's built in.
- Go to openclawlaunch.com/hermes-hosting and start a Hermes deploy.
- Select WhatsApp as one of your channels.
- Pick your AI model and click Deploy.
- After deploy, open the Connect Platforms section in your dashboard and complete the QR pairing flow.
Option 2: Self-Hosted Hermes + WhatsApp
For self-hosted Hermes, enable the WhatsApp channel in /opt/data/config.yaml. WhatsApp is a bundled channel in Hermes and does not require a separate npm install. Refer to the upstream README for the exact config field names in your installed version.
# /opt/data/config.yaml
platforms:
whatsapp:
# No bot token — pairing is QR-based.
# Refer to upstream README for current optional fields.After enabling and restarting, access the Hermes dashboard to complete QR pairing. The pairing session stores credentials in the Hermes data directory, so they persist across container restarts.
WhatsApp vs Telegram for Hermes
| Feature | Telegram | |
|---|---|---|
| Setup method | QR code pairing (WhatsApp Web protocol) | Bot token from @BotFather |
| Account type | Personal phone number | Bot account (separate from personal) |
| Discovery | Users contact you by phone number | Bot is searchable by username |
| Group support | Yes — bot can participate in group chats | Yes — add bot to groups |
| Access control | Anyone who has your number can message | DM pairing required |
WhatsApp is the better choice if your users already know your phone number and you want them to reach you through a familiar interface. Telegram is better for public-facing bots where users find you by username or for communities that already use Telegram.
Keeping the WhatsApp Session Alive
WhatsApp sessions can expire if the linked device is inactive for an extended period. Hermes persists the session credentials in the data directory at /opt/data, which survives container restarts when using a persistent volume. If the session expires (usually after weeks of inactivity), repeat the QR pairing step.
On OpenClaw Launch, the data directory is mounted as a persistent volume automatically — your WhatsApp session survives deploys, restarts, and model changes.
What's Next?
- Hermes Agent + Telegram — Set up Hermes on Telegram with DM pairing security
- Hermes Agent + Discord — Connect Hermes to Discord for community use
- Hermes Agent + WeChat — Connect Hermes to WeChat for China-based users
- Hermes Agent + Claude — Choose the best AI model for your WhatsApp bot