Настройка WhatsApp

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

Запустите vibeos gateway setup и выберите WhatsApp для пошаговой настройки.

Две интеграции WhatsApp

Эта страница посвящена мосту Baileys — быстрая настройка, личные аккаунты, не нужен публичный URL, есть риск бана.

Если вам нужен стабильный бизнес-бот, обратитесь к руководству по WhatsApp Business Cloud API. Это официальный путь от Meta: без риска блокировки аккаунта, но требуется бизнес-аккаунт Meta и публичный webhook URL.

Оба адаптера могут работать параллельно с разными номерами телефонов, если есть такая необходимость.

Неофициальный API — риск блокировки

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

Используйте выделенный номер телефона для бота (не ваш личный номер)
Не рассылайте массовые/спам-сообщения — используйте в режиме диалога
Не автоматизируйте исходящие сообщения тем, кто не написал первым

Обновления протокола WhatsApp Web

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

Два режима

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

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

Node.js v18+ и npm — мост WhatsApp работает как процесс Node.js
Телефон с WhatsApp (для сканирования QR-кода)

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

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

vibeos whatsapp

Мастер выполнит следующие действия:

Спросит, какой режим вам нужен (бот или чат с собой)
Установит зависимости моста, если необходимо
Отобразит QR-код в вашем терминале
Будет ждать, пока вы его отсканируете

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

Откройте WhatsApp на телефоне
Перейдите в Настройки → Связанные устройства
Нажмите Привязать устройство
Наведите камеру на 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 — попробуйте несколько, если первый не сработает.

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

Установите WhatsApp на телефон (или используйте приложение WhatsApp Business с двумя SIM-картами)
Зарегистрируйте новый номер в WhatsApp
Запустите vibeos whatsapp и отсканируйте QR-код из этой учётной записи WhatsApp

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

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

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

# Контроль доступа — выберите ОДИН из этих вариантов:
WHATSAPP_ALLOWED_USERS=15551234567         # Номера телефонов через запятую (с кодом страны, без +)
# WHATSAPP_ALLOWED_USERS=*                 # ИЛИ используйте *, чтобы разрешить всем
# WHATSAPP_ALLOW_ALL_USERS=true            # ИЛИ установите этот флаг (тот же эффект, что и *)

Сокращение «разрешить всем»

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

Необязательные настройки поведения в ~/.vibeos/config.yaml:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

unauthorized_dm_behavior: pair — глобальное значение по умолчанию. Неизвестные отправители личных сообщений получают код сопряжения.
whatsapp.unauthorized_dm_behavior: ignore — заставляет WhatsApp молчать в ответ на неавторизованные личные сообщения, что обычно лучше для частного номера.

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

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

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

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

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

Сессии переживают перезапуски — вам не нужно повторно сканировать QR-код каждый раз
Данные сессии включают ключи шифрования и учётные данные устройства
Не распространяйте и не сохраняйте в репозитории эту директорию сессии — она предоставляет полный доступ к учётной записи WhatsApp

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

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

vibeos whatsapp

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

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

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

Входящие: Голосовые сообщения (.ogg opus) автоматически расшифровываются с помощью настроенного STT-провайдера: локальный faster-whisper, Groq Whisper (GROQ_API_KEY) или OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
Исходящие: TTS-ответы отправляются как вложения в формате MP3
Ответы агента по умолчанию имеют префикс «⚕ VibeOS». Вы можете настроить или отключить это в config.yaml:

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

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

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

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

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

Совместимая с WhatsApp разметка

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

Markdown	WhatsApp	Отображается как
`жирный`	`жирный`	жирный
`~~зачёркнутый~~`	`~зачёркнутый~`	~~зачёркнутый~~
`# Заголовок`	`Заголовок`	Жирный текст (нет собственных заголовков)
`[текст ссылки](url)`	`текст ссылки (url)`	URL в строке

Блоки кода и встроенный код сохраняются как есть, поскольку WhatsApp изначально поддерживает форматирование тройными обратными кавычками.

Прогресс инструментов

Когда агент вызывает инструменты (веб-поиск, операции с файлами и т. д.), WhatsApp отображает индикаторы прогресса в реальном времени, показывая, какой инструмент выполняется. Это включено по умолчанию — настройка не требуется.

Пакетная обработка сообщений (Debounce)

WhatsApp доставляет каждое сообщение индивидуально, поэтому быстрый поток (пересланные пакеты, разбивка вставки, многострочный текст) в противном случае вызвал бы отдельный вызов агента для каждого фрагмента — тратя токены и создавая несколько разрозненных ответов. Адаптер буферизирует последовательные текстовые сообщения из одного чата и отправляет их как один объединённый запрос после короткого периода тишины (по умолчанию 5 с, увеличивается до 10 с для очень длинных фрагментов). Настройка через config.yaml:

# ~/.vibeos/config.yaml
gateway:
  platforms:
    whatsapp:
      extra:
        text_batch_delay_seconds: 5.0         # период тишины перед отправкой пакета
        text_batch_split_delay_seconds: 10.0  # увеличенная задержка около порога разбивки

Установите text_batch_delay_seconds: 0, чтобы отправлять каждое сообщение немедленно (отключает пакетную обработку).

Устранение неполадок

Проблема	Решение
QR-код не сканируется	Убедитесь, что терминал достаточно широкий (60+ столбцов). Попробуйте другой терминал. Убедитесь, что вы сканируете с правильной учётной записи WhatsApp (номер бота, а не личный).
QR-код истекает	QR-коды обновляются каждые ~20 секунд. Если время истекло, перезапустите `vibeos whatsapp`.
Сессия не сохраняется	Проверьте, что `~/.vibeos/platforms/whatsapp/session` существует и доступен для записи. Если используется контейнеризация, смонтируйте его как постоянный том.
Неожиданный выход из системы	WhatsApp отключает устройства после длительного бездействия. Держите телефон включённым и подключённым к сети, затем при необходимости выполните повторное сопряжение с помощью `vibeos whatsapp`.
Мост падает или зацикливается на переподключении	Перезапустите шлюз, обновите VibeOS и выполните повторное сопряжение, если сессия была аннулирована изменением протокола WhatsApp.
Бот перестаёт работать после обновления WhatsApp	Обновите VibeOS, чтобы получить последнюю версию моста, затем выполните повторное сопряжение.
macOS: «Node.js не установлен», но node работает в терминале	Сервисы launchd не наследуют ваш PATH из оболочки. Запустите `vibeos gateway install`, чтобы повторно зафиксировать текущий PATH в plist, затем `vibeos gateway start`. См. документацию Gateway Service для подробностей.
Сообщения не принимаются	Убедитесь, что `WHATSAPP_ALLOWED_USERS` включает номер отправителя (с кодом страны, без `+` или пробелов), или установите его в `*`, чтобы разрешить всем. Установите `WHATSAPP_DEBUG=true` в `.env` и перезапустите шлюз, чтобы увидеть необработанные события сообщений в `bridge.log`.
Бот отвечает незнакомцам кодом сопряжения	Установите `whatsapp.unauthorized_dm_behavior: ignore` в `~/.vibeos/config.yaml`, если вы хотите, чтобы неавторизованные личные сообщения молча игнорировались.

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

предупреждение

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

По умолчанию неавторизованные личные сообщения всё равно получают ответ с кодом сопряжения. Если вы хотите, чтобы частный номер WhatsApp оставался полностью молчаливым для незнакомцев, установите:

whatsapp:
  unauthorized_dm_behavior: ignore

Директория ~/.vibeos/platforms/whatsapp/session содержит полные учётные данные сессии — защищайте её как пароль
Установите права доступа к файлам: chmod 700 ~/.vibeos/platforms/whatsapp/session
Используйте выделенный номер телефона для бота, чтобы изолировать риск от вашего личного аккаунта
Если вы подозреваете компрометацию, отключите устройство в WhatsApp → Настройки → Связанные устройства
Номера телефонов в журналах частично скрыты, но проверьте свою политику хранения журналов

Два режима​

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

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

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

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

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

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

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

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

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

Совместимая с WhatsApp разметка​

Прогресс инструментов​

Пакетная обработка сообщений (Debounce)​

Устранение неполадок​

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