WhatsApp — AI for the World's Most-Used Chat | Easy Understand Hermes Agent

WhatsApp — AI for the World’s Most-Used Chat

WhatsApp is everywhere. Over two billion people use it daily, and now you can plug Hermes right into it. No Meta developer account. No business verification. No complicated API setup. Just a QR code scan and you’re talking to your AI agent from the same app you use to text your friends.

How It Works

Hermes connects to WhatsApp through a built-in bridge based on Baileys. Think of it as emulating a WhatsApp Web session — the same way you’d link a browser to your phone. It’s not the official WhatsApp Business API, which means you don’t need any special approvals to get started.

Run hermes gateway setup and pick WhatsApp for a guided walk-through.

Two Ways to Use It

Mode	How it works	Best for
Separate bot number (recommended)	Dedicate a phone number to the bot. People message that number directly.	Clean UX, multiple users, lower ban risk
Personal self-chat	Use your own WhatsApp. You message yourself to talk to the agent.	Quick setup, single user, testing

The separate bot number approach is cleaner — your AI has its own identity, and you don’t mix personal chats with bot conversations. The self-chat mode is perfect for a quick test run.

Before You Start

You’ll need:

Node.js v18+ and npm — the WhatsApp bridge runs as a Node.js process
A phone with WhatsApp installed (for scanning the QR code)

Good news: unlike older browser-driven bridges, you don’t need Chromium or Puppeteer installed. The setup is much lighter.

Step 1: Run the Setup Wizard

hermes whatsapp

The wizard will:

Ask which mode you want (bot or self-chat)
Install bridge dependencies if needed
Display a QR code in your terminal
Wait for you to scan it

To scan the QR code:

Open WhatsApp on your phone
Go to Settings → Linked Devices
Tap Link a Device
Point your camera at the terminal QR code

Once paired, the wizard confirms the connection and exits. Your session is saved automatically.

Tip: If the QR code looks garbled, make sure your terminal is at least 60 columns wide and supports Unicode. You can also try a different terminal emulator.

Step 2: Getting a Second Phone Number (Bot Mode)

For bot mode, you need a number that isn’t already registered with WhatsApp. Here are your options:

Option	Cost	Notes
Google Voice	Free	US only. Get a number at voice.google.com. Verify WhatsApp via SMS through the Google Voice app.
Prepaid SIM	$5–15 one-time	Any carrier. Activate, verify WhatsApp, then the SIM can sit in a drawer. Number must stay active (make a call every 90 days).
VoIP services	Free–$5/month	TextNow, TextFree, or similar. Some VoIP numbers are blocked by WhatsApp — try a few if the first doesn’t work.

After getting the number:

Install WhatsApp on a phone (or use WhatsApp Business app with dual-SIM)
Register the new number with WhatsApp
Run hermes whatsapp and scan the QR code from that WhatsApp account

Step 3: Configure Hermes

Add the following to your ~/.hermes/.env file:

# Required
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" or "self-chat"

# Access control — pick ONE of these options:
WHATSAPP_ALLOWED_USERS=15551234567         # Comma-separated phone numbers (with country code, no +)
# WHATSAPP_ALLOWED_USERS=*                 # OR use * to allow everyone
# WHATSAPP_ALLOW_ALL_USERS=true            # OR set this flag instead (same effect as *)

Allow-all shorthand: Setting WHATSAPP_ALLOWED_USERS=* allows all senders (same effect as WHATSAPP_ALLOW_ALL_USERS=true). To use the pairing flow instead, remove both variables and rely on the DM pairing system.

Optional behavior settings in ~/.hermes/config.yaml:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

unauthorized_dm_behavior: pair is the global default. Unknown DM senders get a pairing code.
whatsapp.unauthorized_dm_behavior: ignore makes WhatsApp stay silent for unauthorized DMs — usually the better choice for a private number.

Group chats (bot mode): Groups are gated by a separate group policy, not the DM allowlist. WHATSAPP_GROUP_POLICY / whatsapp.group_policy defaults to pairing, which forwards nothing from groups. Set it to allowlist and list the group JIDs in WHATSAPP_GROUP_ALLOWED_USERS / whatsapp.group_allow_from (comma-separated, e.g. 120363001234567890@g.us) to admit specific groups, or open to admit every group the bot is in. Senders are still checked like any other gateway principal: with WHATSAPP_ALLOWED_USERS set, a participant must be on it (or paired); with no sender allowlist, allowlist trusts the group-JID list alone, while open still needs the participant paired or WHATSAPP_ALLOW_ALL_USERS=true. By default the bot answers every admitted group message — set require_mention: true / WHATSAPP_REQUIRE_MENTION=true to answer only @mentions, replies to the bot, or /commands.

Then start the gateway:

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

The gateway starts the WhatsApp bridge automatically using the saved session.

Session Persistence

The Baileys bridge saves its session under ~/.hermes/platforms/whatsapp/session. This means:

Sessions survive restarts — you don’t need to re-scan the QR code every time
The session data includes encryption keys and device credentials
Do not share or commit this session directory — it grants full access to the WhatsApp account

Re-pairing

If the session breaks (phone reset, WhatsApp update, manually unlinked), you’ll see connection errors in the gateway logs. To fix it:

hermes whatsapp

This generates a fresh QR code for re-pairing. The gateway handles temporary disconnections (network blips, phone going offline briefly) automatically with reconnection logic.

A Word of Caution

WhatsApp does not officially support third-party bots outside the Business API. Using a third-party bridge carries a small risk of account restrictions. To minimize risk:

Use a dedicated phone number for the bot (not your personal number)
Don’t send bulk/spam messages — keep usage conversational
Don’t automate outbound messaging to people who haven’t messaged first

Also, WhatsApp periodically updates their Web protocol, which can temporarily break compatibility with third-party bridges. When this happens, Hermes will update the bridge dependency. If the bot stops working after a WhatsApp update, pull the latest Hermes version and re-pair.

Want Something More Official?

If you’re running a real business bot and want stability, check out the WhatsApp Business Cloud API guide instead. It’s the official Meta-supported path: no account ban risk, but requires a Meta Business account and a public webhook URL. The two adapters can also run in parallel against different phone numbers if you have a reason to.

For most personal projects and experiments, though, the Baileys bridge is the fastest way to get AI into your WhatsApp. Scan, configure, and start chatting.