Menu

Utiliser Hermes Agent avec WhatsApp

Utiliser Hermes Agent avec WhatsApp

Cette page fait partie du guide pratique francophone consacré à Hermes Agent. Elle répond à l'intention de recherche : connecter WhatsApp.

Le contenu s'appuie sur la documentation officielle Hermes Agent associée à cette page. L'objectif n'est pas de remplacer la documentation de Nous Research, mais de fournir une lecture claire en français, structurée pour aller vite, avec un maillage logique vers les pages complémentaires du même site.

À retenir

  • Sujet principal : hermes agent whatsapp.
  • Type de page : spoke.
  • Cluster : messagerie.
  • Source canonique : documentation officielle Hermes Agent.
  • Aucun lien vers l'autre domaine n'est utilisé dans cette page.

Quand utiliser cette page

Utilisez cette page quand vous voulez connecter WhatsApp. Elle part du principe que Hermes Agent est déjà identifié comme l'outil à mettre en place ou à comprendre, puis détaille les points importants issus de la documentation officielle.

Si vous découvrez seulement l'outil, revenez d'abord au hub parent puis suivez les liens internes proposés en fin de page.

Base officielle

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.

This page is for the Baileys bridge — quick to set up, personal accounts, no public URL needed, ban risk.

If you're running a real business bot and want stability, see 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.

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

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.

Two Modes

  • 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

---

Prerequisites

  • 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.

---

Step 1: Run the Setup Wizard

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.

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 phone number that isn't already registered with WhatsApp. Three 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:

  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

---

Step 3: Configure Hermes

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

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

WHATSAPP_ALLOWED_USERS=15551234567         # Comma-separated phone numbers (with country code, no +)

Setting WHATSAPP_ALLOWED_USERS=* allows all senders (equivalent to WHATSAPP_ALLOW_ALL_USERS=true).

This is consistent with Signal group allowlists.

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, 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.

---

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. Scan it again and the session is re-established. The gateway

handles temporary disconnections (network blips, phone going offline briefly) automatically

with reconnection logic.

---

Voice Messages

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:
whatsapp:
  reply_prefix: ""                          # Empty string disables the header
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # Custom prefix (supports \n for newlines)

---

Message Formatting & Delivery

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:

  • Markdown — WhatsApp — Renders as
  • bold — *bold* — bold
  • ~~strikethrough~~ — ~strikethrough~ — ~~strikethrough~~
  • # Heading — *Heading* — Bold text (no native headings)
  • link text — link text (url) — Inline URL

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.

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:

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

---

Troubleshooting

  • Problem — Solution
  • QR code not scanning — Ensure terminal is wide enough (60+ columns). Try a different terminal. Make sure you're scanning from the correct WhatsApp account (bot number, not personal).
  • QR code expires — QR codes refresh every ~20 seco

Points de vigilance

  • Vérifiez toujours la version active de Hermes Agent avant d'appliquer une commande ou une configuration.
  • Ne collez pas de clé API dans un chat public ou dans une page visible.
  • Gardez les secrets dans les fichiers ou gestionnaires prévus pour cela.
  • Si une fonctionnalité dépend d'un provider, d'un plugin ou d'une plateforme de messagerie, vérifiez que le composant est bien activé dans votre profil.
  • Pour une installation de production, testez d'abord le flux complet sur une machine ou un profil isolé.

Exemple de parcours logique

  1. Lire la page courante pour comprendre hermes agent whatsapp.
  2. Ouvrir le hub parent du cluster messagerie.
  3. Passer ensuite aux pages complémentaires proposées dans « À lire ensuite ».
  4. Revenir à la documentation officielle si vous avez besoin du détail exact ou d'une commande récemment modifiée.

FAQ rapide

Cette page remplace-t-elle la documentation officielle ?

Non. Elle sert de guide francophone structuré. Le lien vers la source officielle est disponible en bas de page.

Les commandes sont-elles garanties à jour ?

Elles sont basées sur la documentation officielle récupérée au moment de la génération. Pour un usage critique, vérifiez toujours la page officielle liée en bas.

Pourquoi autant de liens internes ?

Hermes Agent est un système modulaire. L'installation, les providers, les outils, la mémoire, les skills, la sécurité et les plateformes se répondent. Le maillage interne aide à suivre ce chemin sans tomber sur des pages orphelines.

À lire ensuite