🏠 Главная › user guide › whatsapp

Настройка WhatsApp

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

⚠️ Warning

Неофициальный API — риск блокировки WhatsApp официально не поддерживает участие ботов вне Business API. Использование внешнего моста несет небольшой риск ограничения аккаунта. Чтобы минимизировать риск: - Используйте выделенный номер телефона для бота (не ваш личный номер) - Не отправляйте массовые/спам-сообщения — викор в режиме диалога - Не автоматизируйте исходящие сообщения тем, кто не написал первым.::::::предупреждение Обновление протокола WhatsApp Web WhatsApp периодически обновляет свой веб-протокол, что может временно нарушать совместимость. со сторонними мостами. Когда это происходит, Hermes обновляет зависимость моста. Если бот перестал работать после обновления WhatsApp, создать полную версию Hermes и выполнить повторное соединение.

Два режима

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

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

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

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

hermes whatsapp

Мастер выполнит:

  1. Спросите, какой режим вы хотите (бот или самочат)
  2. Установит в зависимости от моста, если это необходимо.
  3. Отобразить QR-код в вашем терминале.
  4. Дождется, пока вы его отсканируете.

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

  1. Откройте WhatsApp на телефоне.
  2. Перейдите в ** Настройки → Связанные устройства**.
  3. Нажмите Привязать устройство
  4. Введите камеру на QR-код в терминале.

После подключения мастер подтверждает соединение и завершает работу. Ваша сессия продолжается автоматически.:::совет Если QR-код выглядит нечитаемым, убедитесь, что ваш терминал имеет поворот не менее 60 столбцов и опор. Юникод. Также можно попробовать другой эмулятор терминала.

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

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

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

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

  1. Установите WhatsApp на телефон (или воспользуйтесь приложением WhatsApp Business с двумя SIM-картами).
  2. Зарегистрируйте новый номер в WhatsApp.
  3. Запустите hermes WhatsApp и отсканируйте QR-код с этого аккаунта WhatsApp.

Шаг 3: Настройка Гермеса

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

# Обязательно
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" или "self-chat"

# Контроль доступа — выберите ОДИН из этих вариантов:
WHATSAPP_ALLOWED_USERS=15551234567         # Номера телефонов через запятую (с кодом страны, без +)
# WHATSAPP_ALLOWED_USERS=*                 # ИЛИ используйте *, чтобы разрешить всех
# WHATSAPP_ALLOW_ALL_USERS=true            # ИЛИ установите этот флаг (тот же эффект, что и *)
```<div class="admonition admonition-tip"><p class="admonition-title">💡 Tip</p> Сокращение для разрешения всех
Установка `WHATSAPP_ALLOWED_USERS=*` разрешает **всем** отправителям (эквивалентно `WHATSAPP_ALLOW_ALL_USERS=true`).
Это согласовано с [белыми списками группы Signal](/docs/reference/environment-variables).
Чтобы вместо этого использовать соединение потока, удалите обе переменные и полагайтесь на
[систему соединения ЛС](/docs/user-guide/security#dm-pairing-system).</div>
Дополнительные настройки поведения в `~/.hermes/config.yaml`:
```yaml
unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

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

hermes gateway              # На переднем плане
hermes gateway install      # Установить как пользовательский сервис
sudo hermes gateway install --system   # Только Linux: системный сервис при загрузке

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

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

Большинство Baileys сохранит свою сессию в ~/.hermes/platforms/whatsapp/session. Это означает:

Повторное соединение

Если сессия нарушена (сброс телефона, обновление WhatsApp, ручное отвязывание), вы увидите ошибку Соединения в логах шлюза. Чтобы исправить:

hermes whatsapp

Это получился новый QR-код. Отсканируйте его еще раз, и сессия будет восстановлена. Шлюз автоматически обрабатывает временные отключения (сетевые сбои, строгое отключение телефона) с помощью логики переподключения.

Голосовые сообщения

Hermes поддерживает голос в WhatsApp:

# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # Пустая строка отключает заголовок
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # Пользовательский префикс (поддерживает \n для новых строк)

Форматирование и доставка сообщений

WhatsApp поддерживает потоковые (прогрессивные) ответы — бот редактирует свое сообщение в реальном времени по мере генерации текста AI, как в Discord и Telegram. Внутренне WhatsApp классифицируется как платформа TIER_MEDIUM для возможностей доставки.

Разбивка на части

Длинные ответы автоматически разбиваются на несколько сообщений по 4096 символов на часть (практический лимит отображения WhatsApp). Вам не нужно ничего настраивать — шлюз обрабатывает разбивку и отправляет части последовательно.

Markdown, совместимый с WhatsApp

Стандартный Markdown в ответах AI автоматически преобразуется в нативное форматирование 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 not installed", но node работает в терминале Сервисы launchd не наследуют ваш 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, если вы хотите, чтобы неавторизованные ЛС молча игнорировались.

Безопасность

⚠️ Warning

Настройте контроль доступа перед запуском. Установите WHATSAPP_ALLOWED_USERS с конкретными номерами телефонов (включая код страны, без +), используйте * для разрешения всех или установите WHATSAPP_ALLOW_ALL_USERS=true. Без любого из этих параметров шлюз отклоняет все входящие сообщения в целях безопасности. По умолчанию неавторизованные ЛС все равно получают ответ с кодом сопряжения. Если вы хотите, чтобы частный номер WhatsApp оставался полностью молчаливым для незнакомцев, установите:

whatsapp:
  unauthorized_dm_behavior: ignore