WhatsApp

Hermes connects to WhatsApp through a built-in bridge based on Baileys. This works by emulating a WhatsApp Web session — not through the official WhatsApp Business API. No Meta developer account or Business verification is required.

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

---

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

Unlike older browser-driven bridges, the current Baileys-based bridge does not require a local Chromium or Puppeteer dependency stack.

---

hermes whatsapp

The wizard will:

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

To scan the QR code:

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

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

---

For bot mode, you need a phone number that isn't already registered with WhatsApp. Three options:

After getting the number:

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

---

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 *)

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, which is usually the better choice for a private number.

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.

---

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

---

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. Scan it again and the session is re-established. The gateway handles temporary disconnections (network blips, phone going offline briefly) automatically with reconnection logic.

---

Hermes supports voice on WhatsApp:

• Incoming: Voice messages (.ogg opus) are automatically transcribed using the configured STT provider: local faster-whisper, Groq Whisper (GROQ_API_KEY), or OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
• Outgoing: TTS responses are sent as MP3 audio file attachments
• Agent responses are prefixed with "⚕ Hermes Agent" by default. You can customize or disable this in config.yaml:

# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # Empty string disables the header
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # Custom prefix (supports \n for newlines)
  send_read_receipts: false                 # Mark accepted inbound messages as read (blue ticks)

When send_read_receipts is true, the adapter marks policy-accepted inbound messages as read after DM/group/mention filtering passes. Rejected messages (e.g., from non-allowlisted senders) are not marked read. Disabled by default for privacy. Changing this setting automatically restarts the bridge subprocess on the next connection.

---

WhatsApp supports streaming (progressive) responses — the bot edits its message in real-time as the AI generates text, just like Discord and Telegram. Internally, WhatsApp is classified as a TIER_MEDIUM platform for delivery capabilities.

Chunking

Long responses are automatically split into multiple messages at 4,096 characters per chunk (WhatsApp's practical display limit). You don't need to configure anything — the gateway handles splitting and sends chunks sequentially.

WhatsApp-Compatible Markdown

Standard Markdown in AI responses is automatically converted to WhatsApp's native formatting:

Code blocks and inline code are preserved as-is since WhatsApp supports triple-backtick formatting natively.

Tool Progress

When the agent calls tools (web search, file operations, etc.), WhatsApp displays real-time progress indicators showing which tool is running. This is enabled by default — no configuration needed.

Native Polls, Clarify-as-Poll, and Locations

The Baileys-bridge adapter (bot mode) supports several native WhatsApp message types:

• Polls — the agent can send a native WhatsApp poll (question + options) via the bridge's /send-poll endpoint. Poll votes flow back into the conversation.
• Clarify questions as polls — when the agent asks a multiple-choice clarify question, it's rendered as a native single-select poll; tapping an option answers the question. If the poll fails to send, the adapter falls back to a plain text question. Approval prompts are never mapped onto polls — polls are only used for genuine multiple-choice clarifies.
• Location pins — the agent can send a native location pin (latitude/longitude, optional name/address) via /send-location, and incoming shared locations (including live locations) are delivered to the agent as location messages.

All of this works out of the box in bot (Baileys) mode; no configuration needed.

Message Batching (Debounce)

WhatsApp delivers each message individually, so a rapid burst (forwarded batches, paste-splits, multi-line text) would otherwise trigger a separate agent invocation per fragment — wasting tokens and producing several disjointed replies. The adapter buffers successive text messages from the same chat and dispatches them as one combined request after a short quiet period (default 5s, extended to 10s for very long fragments). Tune via config.yaml:

# ~/.hermes/config.yaml
gateway:
  platforms:
    whatsapp:
      extra:
        text_batch_delay_seconds: 5.0         # quiet period before flushing a batch
        text_batch_split_delay_seconds: 10.0  # extended delay near the split threshold

Set text_batch_delay_seconds: 0 to dispatch each message immediately (disables batching).

---

---

By default, unauthorized DMs still receive a pairing code reply. If you want a private WhatsApp number to stay completely silent to strangers, set:

whatsapp:
  unauthorized_dm_behavior: ignore

• The ~/.hermes/platforms/whatsapp/session directory contains full session credentials — protect it like a password
• Set file permissions: chmod 700 ~/.hermes/platforms/whatsapp/session
• Use a dedicated phone number for the bot to isolate risk from your personal account
• If you suspect compromise, unlink the device from WhatsApp → Settings → Linked Devices
• Phone numbers in logs are partially redacted, but review your log retention policy