🏠 Главная › User Guide › whatsapp

sidebar_position: 5 title: "WhatsApp" description: "Set up Hermes Agent as a WhatsApp bot via the built-in Baileys bridge" lang: ru

Настройка WhatsApp

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

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

::: предупреждение об обновлениях веб-протокола WhatsApp 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 следующее:

# 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`). Это соответствует [спискам разрешенных групп сигналов](/docs/reference/environment-variables). Чтобы вместо этого использовать поток сопряжения, удалите обе переменные и положитесь на [Система сопряжения DM](/docs/user-guide/security#dm-pairing-system).

Дополнительные настройки поведения в ~/.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. Это означает:

Повторное сопряжение

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

hermes whatsapp

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

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

Hermes поддерживает голосовую связь в WhatsApp:

# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # Empty string disables the header
  # reply_prefix: "🤖 *My Bot*\n──────\n"  # Custom prefix (supports \n for newlines)

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

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

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

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

Уценка, совместимая с WhatsApp

Стандартный Markdown в ответах AI автоматически преобразуется в собственное форматирование WhatsApp:

Уценка 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 не установлен», но узел работает в терминале Службы launchd не наследуют PATH вашей оболочки. Запустите hermes gateway install, чтобы повторно сделать снимок текущего PATH в plist, затем hermes gateway start. Подробности см. в документации службы шлюза.
Сообщения не приходят Убедитесь, что WHATSAPP_ALLOWED_USERS включает номер отправителя (с кодом страны, без + и пробелов), или установите для него значение *, чтобы разрешить всем. Установите WHATSAPP_DEBUG=true в .env и перезапустите шлюз, чтобы увидеть события необработанных сообщений в bridge.log.
Бот отвечает незнакомцам с помощью кода сопряжения Установите whatsapp.unauthorized_dm_behavior: ignore в ~/.hermes/config.yaml, если вы хотите, чтобы неавторизованные DM вместо этого молча игнорировались.

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

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

whatsapp:
  unauthorized_dm_behavior: ignore