🏠 Главная › Документация › Мессенджеры

Настройка WhatsApp

Hermes подключается к WhatsApp через встроенный мост на основе Baileys. Он работает путём эмуляции сессии WhatsApp Web — не через официальный WhatsApp Business API. Ни аккаунт разработчика Meta, ни верификация Business не требуются.

warning Неофициальный API — риск блокировки WhatsApp не поддерживает официально сторонних ботов вне Business API. Использование стороннего моста несёт небольшой риск ограничения аккаунта. Чтобы минимизировать риск:

warning Обновления протокола WhatsApp Web WhatsApp периодически обновляет свой Web-протокол, что может временно нарушить совместимость со сторонними мостами. В этом случае Hermes обновит зависимость моста. Если бот перестанет работать после обновления WhatsApp, установите последнюю версию Hermes и выполните повторное сопряжение.

Два режима

Режим Как работает Для чего подходит
Отдельный номер бота (рекомендуется) Выделите номер телефона для бота. Люди пишут на этот номер напрямую. Чистый UX, несколько пользователей, меньший риск блокировки
Личный self-чат Используйте свой WhatsApp. Вы пишете себе, чтобы общаться с агентом. Быстрая настройка, один пользователь, тестирование

Предварительные требования

В отличие от старых браузерных мостов, текущий мост на основе Baileys не требует локального Chromium или стека зависимостей Puppeteer.

Шаг 1: Запустите мастер настройки

hermes whatsapp

Мастер сделает следующее:

  1. Спросит, какой режим вы хотите (bot или self-chat)

  2. Установит зависимости моста при необходимости

  3. Отобразит QR-код в вашем терминале

  4. Будет ждать, пока вы его отсканируете

Чтобы отсканировать QR-код:

  1. Откройте WhatsApp на телефоне

  2. Перейдите в Настройки → Связанные устройства

  3. Нажмите Привязать устройство

  4. Направьте камеру на QR-код в терминале

После сопряжения мастер подтверждает соединение и завершает работу. Ваша сессия сохраняется автоматически.

Если QR-код выглядит искажённым, убедитесь, что ваш терминал имеет ширину не менее 60 колонок и поддерживает Unicode. Также можно попробовать другой терминал.

Шаг 2: Получение второго номера телефона (режим бота)

Для режима бота вам нужен номер телефона, который ещё не зарегистрирован в WhatsApp. Три варианта:

Вариант Стоимость Примечания
Google Voice Бесплатно Только США. Получите номер на voice.google.com. Подтвердите WhatsApp через SMS в приложении Google Voice.
Prepaid SIM-карта $5–15 единоразово Любой оператор. Активируйте, подтвердите WhatsApp, затем SIM может лежать в ящике. Номер должен оставаться активным (совершите звонок каждые 90 дней).
VoIP-сервисы Бесплатно – $5/месяц TextNow, TextFree или аналогичные. Некоторые VoIP-номера блокируются WhatsApp — попробуйте несколько, если первый не работает.

После получения номера:

  1. Установите WhatsApp на телефон (или используйте WhatsApp Business с dual-SIM)

  2. Зарегистрируйте новый номер в WhatsApp

  3. Запустите hermes whatsapp и отсканируйте QR-код из этого аккаунта WhatsApp

Шаг 3: Настройка Hermes

Добавьте следующее в ваш файл ~/.hermes/.env:

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

tip Сокращение для разрешения всех Установка WHATSAPP_ALLOWED_USERS=* разрешает всех отправителей (эквивалентно WHATSAPP_ALLOW_ALL_USERS=true). Это согласуется с белыми списками групп Signal. Чтобы использовать поток сопряжения вместо этого, удалите обе переменные и полагайтесь на систему DM-сопряжения.

Дополнительные настройки поведения в ~/.hermes/config.yaml:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

Затем запустите шлюз:

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

Шлюз автоматически запускает мост WhatsApp, используя сохранённую сессию.

Сохранение сессии

Мост Baileys сохраняет свою сессию в ~/.hermes/platforms/whatsapp/session. Это означает:

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:

# ~/.hermes/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](url) 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.

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 seconds. If it times out, restart hermes whatsapp.
Session not persisting Check that ~/.hermes/platforms/whatsapp/session exists and is writable. If containerized, mount it as a persistent volume.
Logged out unexpectedly WhatsApp unlinks devices after long inactivity. Keep the phone on and connected to the network, then re-pair with hermes whatsapp if needed.
Bridge crashes or reconnect loops Restart the gateway, update Hermes, and re-pair if the session was invalidated by a WhatsApp protocol change.
Bot stops working after WhatsApp update Update Hermes to get the latest bridge version, then re-pair.
macOS: "Node.js not installed" but node works in terminal launchd services don't inherit your shell PATH. Run hermes gateway install to re-snapshot your current PATH into the plist, then hermes gateway start. See the Gateway Service docs for details.
Messages not being received Verify WHATSAPP_ALLOWED_USERS includes the sender's number (with country code, no + or spaces), or set it to * to allow everyone. Set WHATSAPP_DEBUG=true in .env and restart the gateway to see raw message events in bridge.log.
Bot replies to strangers with a pairing code Set whatsapp.unauthorized_dm_behavior: ignore in ~/.hermes/config.yaml if you want unauthorized DMs to be silently ignored instead.

Security

**Configure access control** before going live. Set `WHATSAPP_ALLOWED_USERS` with specific phone numbers (including country code, without the `+`), use `*` to allow everyone, or set `WHATSAPP_ALLOW_ALL_USERS=true`. Without any of these, the gateway **denies all incoming messages** as a safety measure.

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