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.

Multiple Profiles

If you use Hermes profiles, each one can have its own paired WhatsApp session. Pair a secondary profile with:

hermes -p work whatsapp

Then enable WhatsApp for that profile. A profile that is enabled but has no creds.json is skipped with the whatsapp_unpaired status and its pairing command.

Ports: An explicit platforms.whatsapp.extra.bridge_port takes precedence. Otherwise, the launch profile uses port 3000 unless it already has that file (from serving as a secondary), in which case its gateway and hermes send --to whatsapp:<chat_id> both keep using the recorded port. A secondary profile picks the first free port in 3001–3999 that no other profile’s record claims, and saves it in its own platforms/whatsapp/bridge_port file so it keeps the same port on later starts. You can pre-create that file with a port number, or delete it to get a new port.

If you run a separate gateway per profile instead of one multiplexed gateway, they all default to port 3000 — give each one a distinct port in that profile’s config.yaml:

platforms:
  whatsapp:
    extra:
      bridge_port: 3001        # one distinct port per profile

Safety checks: A gateway identifies a running bridge by the session directory the bridge reports in /health. A bridge serving another profile’s session is never adopted and never stopped: the second profile’s WhatsApp fails to start with whatsapp_bridge_foreign_session, naming the port and the other session. A process that holds the port but doesn’t answer /health in time is left running too, and WhatsApp fails with the retryable whatsapp_bridge_unresponsive. hermes send --to whatsapp:<chat_id> and cron delivery check the same field and send nothing through another profile’s bridge or through one whose /health fails. If you override session_path, keep it distinct per profile — otherwise the profiles share one WhatsApp login. hermes gateway status --profile work reports the profile’s own WhatsApp adapter rather than shared ingress. A secondary adopts a bridge already running on its port only when its own session pidfile identifies that process (pid, kernel start time, and the port it was started on), which is what a gateway crash leaves behind; an unhealthy one is reaped by that same identity and restarted. Any other process bound on the port is a fatal error for that profile only — set platforms.whatsapp.extra.bridge_port to a distinct free port, or stop the process holding it. Other profiles continue running. Bridges started by an older Hermes report no session directory and are restarted once, as after a bridge update.

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.