На этой странице Hermes подключается к WhatsApp через встроенный мост на основе Baileys. Он работает путём эмуляции сессии WhatsApp Web — не через официальный WhatsApp Business API. Не требуется ни аккаунта разработчика Meta, ни верификации Business.
Неофициальный API — риск блокировки WhatsApp официально не поддерживает сторонних ботов вне Business API. Использование стороннего моста несёт небольшой риск ограничения аккаунта. Чтобы минимизировать риск: * Используйте выделенный номер телефона для бота (не ваш личный номер) * Не отправляйте массовые/спам-сообщения — используйте в режиме переписки * Не автоматизируйте исходящие сообщения тем, кто не написал первым
Обновления протокола WhatsApp Web WhatsApp периодически обновляет свой Web-протокол, что может временно нарушить совместимость со сторонними мостами. Когда это происходит, Hermes обновляет зависимость моста. Если бот перестал работать после обновления WhatsApp, загрузите последнюю версию Hermes и выполните повторное сопряжение.
Два режима¶
Режим| Как работает| Для чего лучше всего |---|---|--- Отдельный номер бота (рекомендуется)| Выделите номер телефона для бота. Люди пишут на этот номер напрямую.| Чистый UX, несколько пользователей, меньший риск блокировки Личный self-chat| Используйте свой WhatsApp. Вы пишете сами себе, чтобы общаться с агентом.| Быстрая настройка, один пользователь, тестирование
Предварительные требования¶
- Node.js v18+ и npm — мост WhatsApp работает как Node.js процесс
- Телефон с WhatsApp (для сканирования QR-кода)
В отличие от старых браузерных мостов, текущий мост на Baileys не требует локального стека зависимостей Chromium или Puppeteer.
Шаг 1: Запустите мастер настройки¶
[code] hermes whatsapp
[/code] Мастер выполнит: 1. Спросит, какой режим вам нужен (bot или self-chat) 2. Установит зависимости моста, если необходимо 3. Покажет QR-код в вашем терминале 4. Будет ждать, пока вы его отсканируете
Чтобы отсканировать QR-код: 1. Откройте WhatsApp на телефоне 2. Перейдите в Настройки → Связанные устройства 3. Нажмите Привязать устройство 4. Направьте камеру на QR-код в терминале
После сопряжения мастер подтверждает подключение и завершает работу. Ваша сессия сохраняется автоматически. tip Если 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:
[code]
# Обязательно
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot # "bot" или "self-chat"
# Контроль доступа — выберите ОДИН из этих вариантов:
WHATSAPP_ALLOWED_USERS=15551234567 # Номера телефонов через запятую (с кодом страны, без +)
# WHATSAPP_ALLOWED_USERS=* # ИЛИ используйте *, чтобы разрешить всем
# WHATSAPP_ALLOW_ALL_USERS=true # ИЛИ установите этот флаг вместо (аналогично *)
[/code]
Сокращение «разрешить всем»
Установка WHATSAPP_ALLOWED_USERS=* разрешает всех отправителей (эквивалентно WHATSAPP_ALLOW_ALL_USERS=true). Это соответствует спискам разрешённых в Signal. Чтобы вместо этого использовать поток сопряжения, удалите обе переменные и положитесь на систему DM-сопряжения.
Необязательные настройки поведения в ~/.hermes/config.yaml:
[code]
unauthorized_dm_behavior: pair
whatsapp:
unauthorized_dm_behavior: ignore
[/code]
* unauthorized_dm_behavior: pair — глобальное значение по умолчанию. Неизвестные отправители DM получают код сопряжения.
* whatsapp.unauthorized_dm_behavior: ignore — WhatsApp остаётся молчаливым для неавторизованных DM, что обычно лучше для личного номера.
Затем запустите шлюз:
[code]
hermes gateway # На переднем плане
hermes gateway install # Установить как пользовательский сервис
sudo hermes gateway install --system # Только Linux: системный сервис для автозагрузки
[/code] Шлюз автоматически запускает мост WhatsApp, используя сохранённую сессию.
Сохранение сессии¶
Мост Baileys сохраняет свою сессию в ~/.hermes/platforms/whatsapp/session. Это означает:
* Сессии переживают перезагрузки — вам не нужно повторно сканировать QR-код каждый раз
* Данные сессии включают ключи шифрования и учётные данные устройства
* Не распространяйте и не коммитьте эту директорию сессии — она предоставляет полный доступ к аккаунту WhatsApp
Повторное сопряжение¶
Если сессия нарушена (сброс телефона, обновление WhatsApp, ручное отключение), вы увидите ошибки подключения в логах шлюза. Чтобы исправить: [code] hermes whatsapp
[/code] Это генерирует новый QR-код. Отсканируйте его снова, и сессия будет восстановлена. Шлюз обрабатывает временные отключения (сбои сети, временное отключение телефона) автоматически с помощью логики переподключения.
Голосовые сообщения¶
Hermes поддерживает голос в WhatsApp:
* Входящие: Голосовые сообщения (.ogg opus) автоматически транскрибируются с использованием настроенного STT-провайдера: локальный faster-whisper, Groq Whisper (GROQ_API_KEY) или OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
* Исходящие: TTS-ответы отправляются как вложения в формате MP3
* Ответы агента по умолчанию имеют префикс «⚕ Hermes Agent ». Вы можете настроить или отключить это в config.yaml:
[code]
# ~/.hermes/config.yaml
whatsapp:
reply_prefix: "" # Пустая строка отключает заголовок
# reply_prefix: "🤖 Мой бот\n──────\n" # Пользовательский префикс (поддерживается \n для переносов)
[/code]
Форматирование и доставка сообщений¶
WhatsApp поддерживает потоковые (прогрессивные) ответы — бот редактирует своё сообщение в реальном времени по мере генерации текста ИИ, так же как Discord и Telegram. Внутренне WhatsApp классифицируется как платформа TIER_MEDIUM по возможностям доставки.
Разбивка на части¶
Длинные ответы автоматически разбиваются на несколько сообщений по 4 096 символов на часть (практический лимит отображения WhatsApp). Вам не нужно ничего настраивать — шлюз обрабатывает разбивку и отправляет части последовательно.
Markdown, совместимый с WhatsApp¶
Стандартный Markdown в ответах ИИ автоматически преобразуется в родное форматирование WhatsApp:
Markdown| WhatsApp| Отображается как
---|---|---
**bold**| *bold*| жирный
~~strikethrough~~| ~strikethrough~| ~~зачёркнутый~~
# Heading| *Heading*| Жирный текст (нет родных заголовков)
[link text](url)| link text (url)| URL в строке
Блоки кода и инлайн-код сохраняются как есть, поскольку WhatsApp изначально поддерживает форматирование тройными обратными кавычками.
Прогресс инструментов¶
Когда агент вызывает инструменты (веб-поиск, операции с файлами и т. д.), WhatsApp отображает индикаторы прогресса в реальном времени, показывая, какой инструмент выполняется. Это включено по умолчанию — настройка не требуется.
Устранение неполадок¶
| Проблема | Решение |
|---|---|
| QR-код не сканируется | Убедитесь, что терминал достаточно широкий (60+ колонок). Попробуйте другой терминал. Убедитесь, что вы сканируете с правильного аккаунта WhatsApp (номер бота, а не личный). |
| QR-код истекает | QR-коды обновляются каждые ~20 секунд. Если время истекло, перезапустите hermes whatsapp. |
| Сессия не сохраняется | Проверьте, что ~/.hermes/platforms/whatsapp/session существует и доступен для записи. Если используется контейнеризация, подключите его как постоянный том. |
| Неожиданный выход из системы | WhatsApp отключает устройства после длительного бездействия. Держите телефон включённым и подключённым к сети, затем при необходимости выполните повторное сопряжение с hermes whatsapp. |
| Сбой моста или циклы переподключения | Перезапустите шлюз, обновите Hermes и выполните повторное сопряжение, если сессия была аннулирована из-за изменения протокола WhatsApp. |
| Бот перестал работать после обновления WhatsApp | Обновите Hermes, чтобы получить последнюю версию моста, затем выполните повторное сопряжение. |
| macOS: «Node.js не установлен», хотя node работает в терминале | Сервисы launchd не наследуют ваш shell PATH. Запустите hermes gateway install, чтобы повторно снять снимок вашего текущего PATH в plist, затем hermes gateway start. См. документацию Gateway Service для подробностей. |
| Сообщения не принимаются | Проверьте, что WHATSAPP_ALLOWED_USERS включает номер отправителя (с кодом страны, без + и пробелов), или установите *, чтобы разрешить всем. Установите WHATSAPP_DEBUG=true в .env и перезапустите шлюз, чтобы увидеть события сырых сообщений в bridge.log. |
| Бот отвечает незнакомцам кодом сопряжения | Установите whatsapp.unauthorized_dm_behavior: ignore в ~/.hermes/config.yaml, если вы хотите, чтобы неавторизованные DM молча игнорировались. |
| * * * | |
| ## Безопасность | |
| warning | |
Настройте контроль доступа перед запуском. Установите WHATSAPP_ALLOWED_USERS с конкретными номерами телефонов (включая код страны, без +), используйте *, чтобы разрешить всем, или установите WHATSAPP_ALLOW_ALL_USERS=true. Без любого из этих параметров шлюз отклоняет все входящие сообщения как меру безопасности. |
|
| По умолчанию неавторизованные DM всё равно получают ответ с кодом сопряжения. Если вы хотите, чтобы личный номер WhatsApp оставался полностью молчаливым для незнакомцев, установите: | |
| [code] | |
| whatsapp: | |
| unauthorized_dm_behavior: ignore |
[/code]
* Директория ~/.hermes/platforms/whatsapp/session содержит полные учётные данные сессии — берегите её как пароль
* Установите права доступа: chmod 700 ~/.hermes/platforms/whatsapp/session
* Используйте выделенный номер телефона для бота, чтобы изолировать риск от вашего личного аккаунта
* Если подозреваете компрометацию, отключите устройство в WhatsApp → Настройки → Связанные устройства
* Номера телефонов в логах частично скрыты, но просмотрите свою политику хранения логов