Перейти к основному содержимому

Настройка WhatsApp Business Cloud API

VibeOS может подключаться к WhatsApp через официальный WhatsApp Business Cloud API от Meta. Это production-путь: никаких Node.js-мостов в подпроцессах, никаких QR-кодов, никакого риска блокировки аккаунта.

Взамен:

  • Вам понадобится Meta Business аккаунт (не личный WhatsApp).
  • Бот работает на выделенном бизнес-номере телефона, а не на вашем личном.
  • Шлюзу VibeOS требуется публичный HTTPS URL, чтобы Meta могла доставлять входящие сообщения через вебхук.
  • Ответы спустя более 24 часов после последнего сообщения пользователя требуют предварительно одобренного шаблона (это правило Meta «окна обслуживания клиента», а не ограничение VibeOS).

Если эти ограничения не подходят для вашего сценария, альтернативой является интеграция через мост Baileys — личный аккаунт, не нужен публичный URL, но неофициально и с риском блокировки.

Что выбрать?
  • Cloud API (это руководство) — запуск настоящего бизнес-бота, нужна стабильность, устраивает бумажная волокита с верификацией Meta и шаблонами.
  • Мост Baileys — личные проекты, быстрые демо, настройки для одного пользователя, готовность рискнуть аккаунтом номера бота.

Быстрый старт​

vibeos whatsapp-cloud

Мастер проведёт вас через все учётные данные, проверит каждое при вставке (ловит самую частую ошибку настройки — вставку номера телефона в поле Phone Number ID) и выведет точные дальнейшие инструкции для частей, которые нужно выполнить вне мастера (запуск cloudflared, настройка панели вебхуков Meta).

Остальная часть страницы — справочное руководство.

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

  1. Meta Business аккаунт. Создайте на business.facebook.com.
  2. Meta приложение с включённым WhatsApp. См. «Создание Meta приложения» ниже.
  3. Способ открыть локальный порт в публичный интернет с HTTPS. Рекомендуется Cloudflare Tunnel (cloudflared) — бесплатно, не нужен проброс портов, не нужен домен. Также подойдут ngrok, собственный домен с обратным прокси + TLS, или VPS со шлюзом, привязанным напрямую к публичному IP.
  4. Опционально, но рекомендуется: ffmpeg в PATH, чтобы исходящие голосовые сообщения отображались как нативные голосовые заметки WhatsApp (зелёная волна), а не как MP3-вложения. VibeOS корректно работает и без него.

Создание Meta приложения​

  1. Перейдите на developers.facebook.com/apps → Create App.
  2. Выберите сценарий использования: «Connect with customers through WhatsApp» → Next.
  3. Выберите или создайте бизнес-портфолио. Ознакомьтесь с требованиями к публикации. Подтвердите → Create app.
  4. После создания вы попадёте на страницу Customize use case → Connect on WhatsApp → Quickstart. Нажмите Start using the API → теперь вы на странице API Setup.
  5. Убедитесь, что привязан WhatsApp Business Account (WABA). Если вы создали новое портфолио на шаге 3, он был создан автоматически. Проверьте на странице API Setup.

Вам понадобятся эти значения из панели управления — мастер запрашивает их в таком порядке:

ЗначениеГде в панелиФормат поляПримечания
Phone Number IDApp Dashboard → WhatsApp → API Setup → под выпадающим списком «From»Числовой, 15-17 цифрНЕ номер телефона. Самая частая ошибка настройки — вставить сюда сам номер телефона.
Access TokenApp Dashboard → WhatsApp → API Setup → «Generate access token»Начинается с EAA, 100+ символовВременные токены живут 24 часа — см. «Постоянный токен» ниже для production.
App SecretApp Dashboard → Settings → Basic → нажмите «Show» рядом с App secret32-символьная шестнадцатеричная строкаИспользуется для проверки подписей входящих вебхуков. Без него входящие сообщения отклоняются с кодом 503.
App ID (опционально)App Dashboard → Settings → BasicЧисловой, 15-16 цифрНе требуется для обмена сообщениями, полезно для аналитики.
WABA ID (опционально)App Dashboard → WhatsApp → API Setup → вверхуЧисловой, 15+ цифрНе требуется для обмена сообщениями, полезно для аналитики.

Постоянный токен (production)​

Временные токены доступа истекают через 24 часа, то есть токен, сгенерированный сегодня, перестанет работать завтра. Для production-развёртываний используйте постоянный токен системного пользователя:

  1. Перейдите на business.facebook.com/latest/settings → System users (левая боковая панель).
  2. Add → имя (например, vibeos-bot) → роль: Admin.
  3. Выберите нового пользователя → Assign Assets:
    • Выберите ваше приложение → включите Manage app в разделе Full control.
    • Выберите ваш WhatsApp аккаунт → включите Manage WhatsApp Business Accounts в разделе Full control.
    • Нажмите Assign assets.
  4. Generate token со следующими разрешениями:
    • business_management
    • whatsapp_business_messaging
    • whatsapp_business_management
  5. Установите token expiration: Never.
  6. Скопируйте токен → обновите WHATSAPP_CLOUD_ACCESS_TOKEN в ~/.vibeos/.env → перезапустите шлюз.

Токены системных пользователей не истекают, если вы явно не отзовёте их.

Открытие VibeOS в интернет​

Cloud API доставляет входящие сообщения через HTTPS POST на ваш URL вебхука — это означает, что шлюз VibeOS должен быть доступен с серверов Meta. Три распространённых способа:

Cloudflare Tunnel (рекомендуется)​

Бесплатно, не требует проброса портов, работает на Windows / macOS / Linux. Запускается как отдельный процесс рядом со шлюзом.

Установка:

# Windows
winget install Cloudflare.cloudflared

# macOS
brew install cloudflared

# Linux
# Скачайте бинарник с https://github.com/cloudflare/cloudflared/releases

Запуск быстрого туннеля (аккаунт Cloudflare не нужен — выдаёт URL вида https://<random>.trycloudflare.com):

cloudflared tunnel --url http://localhost:8090

Запомните выведенный URL — его вы укажете Meta.

Быстрые туннели меняются

Бесплатный URL быстрого туннеля меняется при каждом перезапуске cloudflared. Для стабильного URL войдите с помощью cloudflared tunnel login и создайте именованный туннель. Бесплатные аккаунты Cloudflare получают неограниченное количество именованных туннелей — см. документацию Cloudflare по работе с именованными туннелями.

ngrok​

ngrok http 8090

Бесплатный тариф показывает другой URL при каждом перезапуске. Платный тариф даёт стабильный поддомен.

Собственный домен + обратный прокси​

Если у вас уже есть сервер с TLS-сертификатом (Caddy, nginx и т.д.), направьте маршрут на localhost:8090. Это самый стабильный вариант для production, но требует существующей инфраструктуры.

Настройка вебхука на стороне Meta​

Как только ваш туннель запущен:

  1. Запомните публичный URL, выведенный вашим туннелем — например, https://abc123.trycloudflare.com.
  2. Сгенерируйте Verify Token — мастер делает это за вас с помощью secrets.token_urlsafe(32); если настраиваете вручную, выполните: 
    python -c "import secrets; print(secrets.token_urlsafe(32))"
    Сохраните его как WHATSAPP_CLOUD_VERIFY_TOKEN в ~/.vibeos/.env.
  3. Запустите шлюз VibeOS: vibeos gateway.
  4. В панели управления Meta App Dashboard → WhatsApp → Configuration (или Use cases → Customize → Configuration в зависимости от версии интерфейса) → нажмите Edit в разделе Webhook.
  5. Заполните:
    • Callback URL: https://abc123.trycloudflare.com/whatsapp/webhook
    • Verify Token: строка из шага 2 (должна совпадать в точности)
  6. Нажмите Verify and save. Meta отправляет GET-запрос на ваш URL, шлюз возвращает challenge, и Meta отмечает вебхук как проверенный.
  7. В разделе Webhook fields нажмите Manage → подпишитесь на поле messages. Это указывает Meta фактически доставлять входящие сообщения на ваш вебхук.

Для ручной проверки цикла (из третьего терминала):

TUNNEL="https://abc123.trycloudflare.com"
VERIFY="<ваш verify token>"

# Должен вернуть HTTP 200 с телом "hello"
curl -i "$TUNNEL/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=$VERIFY&hub.challenge=hello"

# Эндпоинт здоровья — должен показать verify_token_configured: true и app_secret_configured: true
curl "$TUNNEL/health"

Белый список получателей (на стороне Meta)​

В режиме разработки (до прохождения App Review) Meta ограничивает, на какие номера ваш бот может отправлять сообщения:

  1. App Dashboard → WhatsApp → API Setup → выпадающий список To.
  2. Нажмите Manage phone number list.
  3. Добавьте номера телефонов, на которые хотите отправлять сообщения (ваш, вашей команды, дружественных тестировщиков). Meta отправляет каждому 6-значный код верификации через SMS или WhatsApp.

До 5 номеров в режиме разработки. Прохождение App Review снимает это ограничение.

Белый список (на стороне VibeOS)​

В дополнение к белому списку получателей Meta, VibeOS имеет собственный поплатформенный белый список, который контролирует, какие входящие сообщения обрабатывает агент. Добавьте в ~/.vibeos/.env:

# Номера телефонов через запятую, с кодом страны, без '+' / пробелов / дефисов
WHATSAPP_CLOUD_ALLOWED_USERS=15551234567,15557654321

# Или разрешить всем (безопасно только в сочетании с белым списком получателей Meta)
# WHATSAPP_CLOUD_ALLOW_ALL_USERS=true

Мастер устанавливает это на шаге 6. Без белого списка каждое входящее сообщение отклоняется — это сделано намеренно, чтобы бота не могли вызвать случайные номера, если белый список получателей когда-либо будет ослаблен.

Доработка профиля бота в WhatsApp​

WhatsApp отображает имя и изображение профиля вашего бота в заголовке чата и списке контактов. Их нельзя задать через Cloud API — они живут в Meta Business Manager.

Как только ваш бот заработает, перейдите на business.facebook.com/wa/manage/phone-numbers, нажмите на свой номер телефона, и вы найдёте:

ЧтоГдеПримечания
Отображаемое имяВверху страницы номера телефонаИзменения проходят процесс проверки имени Meta (~24–48 часов).
Изображение профиляВверху страницы номера телефонаКвадратное изображение, рекомендуется ≥640×640px. Обновляется мгновенно.
Описание / веб-сайт / email / часы работы / категорияКнопка «Edit profile»Отображаются в информационной панели, когда пользователь нажимает на имя бота. Косметика.
Значок верификации (зелёная галочка)Business Manager → Security Center → Start VerificationТребует отдельного процесса верификации бизнеса Meta.

Мастер vibeos whatsapp-cloud выводит эти ссылки в конце настройки. Ничего из этого не требуется для работы бота — это чисто косметические улучшения того, как ваш бот выглядит для пользователей.

Справочник по конфигурации​

Все настройки хранятся в ~/.vibeos/.env. Обязательные значения выделены жирным.

ПеременнаяПо умолчаниюОписание
WHATSAPP_CLOUD_PHONE_NUMBER_ID—15-17-значный ID из API Setup. Не номер телефона.
WHATSAPP_CLOUD_ACCESS_TOKEN—Токен доступа Meta (начинается с EAA). Временный на 24ч или постоянный системного пользователя.
WHATSAPP_CLOUD_APP_SECRET—32-символьная шестнадцатеричная строка из Settings → Basic. Без него входящие отклоняются с 503.
WHATSAPP_CLOUD_VERIFY_TOKEN—Общий секрет для GET-рукопожатия. Автоматически генерируется мастером.
WHATSAPP_CLOUD_ALLOWED_USERS—wa_id через запятую, которым разрешено писать боту.
WHATSAPP_CLOUD_ALLOW_ALL_USERSfalseУстановите true, чтобы отключить белый список.
WHATSAPP_CLOUD_APP_ID—Опционально, для будущей интеграции аналитики.
WHATSAPP_CLOUD_WABA_ID—Опционально, для будущей интеграции аналитики.
WHATSAPP_CLOUD_WEBHOOK_HOST0.0.0.0Интерфейс, к которому привязывается сервер вебхука.
WHATSAPP_CLOUD_WEBHOOK_PORT8090Порт, к которому привязывается сервер вебхука. Должен совпадать с портом, который пробрасывает ваш туннель.
WHATSAPP_CLOUD_WEBHOOK_PATH/whatsapp/webhookПуть URL, на который Meta отправляет POST-запросы.
WHATSAPP_CLOUD_API_VERSIONv20.0Версия Meta Graph API. Изменяйте, только если в документации Meta рекомендована более новая версия.
WHATSAPP_CLOUD_HOME_CHANNEL—wa_id для использования в качестве домашнего канала бота (для cron-задач и т.д.).

Вы можете включить оба адаптера — Baileys (whatsapp) и Cloud (whatsapp_cloud) — одновременно, для работы с разными номерами телефонов.

Возможности​

Входящие​

  • Текстовые сообщения — передаются агенту напрямую.
  • Изображения — автоматически загружаются и прикрепляются к вводу агента. Модели со встроенным зрением (Claude, GPT-4o, Gemini и др.) читают изображение напрямую; модели без зрения получают автоматически сгенерированное текстовое описание.
  • Голосовые заметки — автоматически загружаются как .ogg, транскрибируются через настроенный STT-провайдер (локальный faster-whisper, OpenAI/Nous, Groq и т.д.), затем передаются агенту как текст.
  • Документы — автоматически загружаются. Небольшие текстовые файлы (.txt, .md, .json, .py, .csv и т.д.) до 100 КБ встраиваются в ввод агента, чтобы он мог прочитать их без вызова инструмента. Файлы большего размера кэшируются локально для доступа через другие инструменты агента.
  • Нажатия кнопок — когда пользователь нажимает кнопку, отправленную ботом ранее (уточнение выбора, подтверждение команды, подтверждение слеш-команды), нажатие направляется непосредственно соответствующему обработчику. Устаревшие нажатия обрабатываются как обычный текстовый ввод.
  • Контекст ответа — когда пользователь отвечает на предыдущее сообщение бота, агент видит исходное сообщение как контекст.

Исходящие​

  • Текст — markdown автоматически конвертируется в синтаксис WhatsApp (**bold** → *bold*, ~~strike~~ → ~strike~, заголовки → жирный, [link](url) → link (url)). Длинные сообщения разбиваются на части по 4096 символов.
  • Изображения — поддерживаются как изображения, сгенерированные агентом, так и локальные файлы изображений; доставляются как нативные вложения фотографий.
  • Голосовые сообщения — вывод text-to-speech конвертируется через ffmpeg в нативный пузырёк голосовой заметки WhatsApp (зелёная волна). Без ffmpeg используется MP3-вложение. См. «Голосовые сообщения» ниже.
  • Видео / документы — оба поддерживаются, отправляются как нативные вложения.

Интерактивный UX​

Когда агент вызывает любой из этих потоков, VibeOS использует нативные интерактивные сообщения WhatsApp — кнопки для ответа касанием вместо подсказок «ответьте цифрой»:

  • Инструмент clarify — вопросы с множественным выбором отображаются как кнопки быстрого ответа (1–3 варианта) или открывающийся по нажатию список (4+ варианта). Выбор «✏️ Другое» позволяет пользователю ввести произвольный ответ, который агент получает как разрешение.
  • Подтверждения опасных команд — когда выполнение терминала/кода агентом натыкается на ограниченную команду, пользователь видит кнопки ✅ Approve / ❌ Deny вместо необходимости вводить /approve или /deny.
  • Подтверждения слеш-команд — привилегированные команды, такие как /reload-mcp, показывают кнопки ✅ Approve Once / 🔒 Always / ❌ Cancel.

Все интерактивные подсказки корректно деградируют до обычного текста, если кнопки не отображаются (например, на старых клиентах WhatsApp).

Уведомления о прочтении и индикатор набора​

VibeOS немедленно подтверждает получение входящих сообщений:

  • Ваше сообщение показывает синие двойные галочки, как только шлюз его получает.
  • Имя бота в вашем чате WhatsApp показывает «печатает…», пока агент готовит ответ.
  • Индикатор набора автоматически исчезает, когда приходит первое ответное сообщение бота.

Это делает очевидным, когда бот увидел ваше сообщение, а когда он всё ещё работает над ответом.

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

WhatsApp различает «голосовую заметку» (зелёный пузырёк с волной) и обычное вложение аудиофайла. Разница исключительно в кодеке: голосовые заметки должны быть audio/ogg с кодировкой opus.

VibeOS TTS создаёт MP3. Два пути:

  • С ffmpeg в PATH (рекомендуется) — исходящий TTS конвертируется и arrives как полноценная голосовая заметка. Установка:
    • Windows: winget install Gyan.FFmpeg
    • macOS: brew install ffmpeg
    • Linux: менеджер пакетов
  • Без ffmpeg — исходящий TTS arrives как MP3-вложение. Воспроизводится нормально, но не выглядит как голосовая заметка. В логе шлюза выводится одноразовое предупреждение, чтобы вы знали.

Вы можете проверить, нашёл ли шлюз ffmpeg, через эндпоинт здоровья:

curl http://localhost:8090/health
# ищите "ffmpeg_present": true

Известные ограничения​

24-часовое окно разговора​

Meta разрешает свободные сообщения только в пределах 24-часового окна после последнего входящего сообщения пользователя. За пределами этого окна API Meta принимает только предварительно одобренный шаблон сообщения.

Что это означает на практике:

  • Реактивный чат (пользователь пишет в ЛС → бот отвечает в течение 24ч → пользователь отвечает → ...) работает постоянно. Это покрывает >95% обычного использования бота.
  • Cron-задачи, отправляющие в WhatsApp после перерыва > 24ч, завершатся ошибкой Graph с кодом 131047 («Re-engagement message»).
  • Асинхронные результаты delegate_task, выполняющиеся дольше 24ч, завершатся той же ошибкой.
  • Подписчики вебхуков, направляющие внешние события в WhatsApp, не сработают, если пользователь не писал боту в ЛС в последнее время.

VibeOS предупреждает агента об этом окне в системном промпте, чтобы модель знала о нём при планировании отложенных сообщений.

Поддержка шаблонов сообщений (обходной путь для отправки за пределами окна) пока не реализована в VibeOS. Если вам это нужно, пожалуйста, откройте issue — это запланировано, но ждёт явного сигнала спроса.

Групповые чаты​

Cloud API имеет ограниченную поддержку групп (уровень возможностей определяется Meta). Адаптер whatsapp_cloud в VibeOS в v1 обрабатывает только личные сообщения. Если вам нужны групповые чаты, используйте мост Baileys.

Лимит исходящих запросов​

Пропускная способность Meta по умолчанию — 80 сообщений в секунду на один бизнес-номер телефона, доступны апгрейды. VibeOS в настоящее время не контролирует это на стороне клиента — очень высокие объёмы отправки могут достичь лимита Meta.

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

Ошибка верификации настройки («URL couldn't be validated») в панели Meta​

Почти всегда одна из:

  • URL туннеля неверен или устарел — быстрые туннели cloudflared меняются. Получите свежий URL и обновите как .env, так и панель Meta.
  • Несовпадение verify token — токен в WHATSAPP_CLOUD_VERIFY_TOKEN в ~/.vibeos/.env должен в точности совпадать с тем, что вы ввели в панели Meta. Сначала выполните curl-проверку выше, чтобы убедиться, что рукопожатие verify работает локально.
  • Шлюз не запущен — проверьте, что vibeos gateway работает.
  • App Secret не установлен — без него VibeOS отклоняет входящие POST-запросы с кодом 503. Meta интерпретирует это как «не удаётся проверить».

graph error 100: Object with ID '...' does not exist​

Вы вставили номер телефона (10-11 цифр) в WHATSAPP_CLOUD_PHONE_NUMBER_ID вместо Phone Number ID (внутреннего ID Meta из 15-17 цифр). Перепроверьте страницу API Setup — Phone Number ID отображается под выпадающим списком «From».

Мастер теперь ловит это с помощью валидатора, но полезно знать, если настраиваете вручную.

graph error 190: Authentication Error​

Ваш токен доступа недействителен. Подкоды:

  • subcode 463 — срок действия токена истёк. Временные токены живут 24ч. Сгенерируйте заново или переключитесь на постоянный токен системного пользователя (см. выше).
  • subcode 467 — токен аннулирован (отозван или изменён пароль).
  • Другие 190 — при генерации токена не были выбраны необходимые разрешения. Убедитесь, что выбраны все три (business_management, whatsapp_business_messaging, whatsapp_business_management).

graph error 131047: Re-engagement message​

Истекло 24-часовое окно разговора (см. «Известные ограничения»). Либо:

  • Попросите пользователя сначала написать боту в ЛС, чтобы открыть окно заново.
  • Дождитесь появления поддержки шаблонов в VibeOS.

Входящее сообщение: media metadata fetch failed (status=401)​

Те же причины 401, что и для исходящих (graph error 190) — токен доступа недействителен или истёк. Исправьте токен.

Ответы бота отображаются как сырой JSON / утечка вызова инструмента​

Распространённая причина: в наборе инструментов, настроенном для whatsapp_cloud, отсутствуют инструменты, которые агент хочет вызвать. Проверьте vibeos tools list и убедитесь, что платформа использует vibeos-whatsapp (набор инструментов адаптера Cloud по умолчанию, такой же, как у Baileys).

Если модель выводит текст в форме вызова инструмента вместо структурированного вызова, это обычно означает, что набор инструментов был фактически пуст. См. vibeos_cli/platforms.py для сопоставления платформы и набора инструментов по умолчанию.

STT (транскрипция голосовых заметок) возвращает пустой результат / «could not transcribe»​

Провайдер stt.provider: local по умолчанию требует pip install faster-whisper. Если вы подписчик Nous, вы можете направить STT через управляемый аудиошлюз Meta:

vibeos config set stt.provider openai
vibeos config set stt.use_gateway true
vibeos gateway restart

При этом используется ваш токен доступа Nous Portal вместо отдельного ключа OpenAI.

Замечания по безопасности​

  • Относитесь к App Secret как к паролю — любой, у кого он есть, может подделать полезную нагрузку вебхука, которую VibeOS примет как подлинную.
  • Verify token — это общий секрет — утечка менее критична (в худшем случае кто-то сможет переподписать вебхук Meta на другой URL), но всё равно избегайте его сохранения в репозитории.
  • Access token — это идентичность вашего бота — токены системных пользователей эквивалентны долгоживущим API-ключам. Немедленно отзывайте их, если развёртывание скомпрометировано.
  • Эндпоинт вебхука принимает только подписанные запросы, когда установлен WHATSAPP_CLOUD_APP_SECRET — оставляйте его установленным даже в разработке. Без него шлюз отклоняет входящие сообщения с HTTP 503.
  • Эндпоинт /health не требует аутентификации — его безопасно открывать, поскольку он сообщает только булевы значения наличия конфигурации, а не сами значения. Но если вы предпочитаете не раскрывать его, ограничьте доступ на уровне обратного прокси / туннеля.

Сравнение с мостом Baileys​

Baileys (vibeos whatsapp)Cloud API (vibeos whatsapp-cloud)
Тип аккаунтаЛичныйБизнес
НастройкаСканирование QR-кодаMeta приложение + WABA + токен
ЗависимостиNode.js + npmЧистый Python (httpx + aiohttp)
ПроцессУправляемый подпроцесс NodeСервер вебхука aiohttp
Нужен публичный URL?НетДа
Риск блокировки аккаунтаДа (неофициальное API)Нет (официально поддерживается)
ВходящиеОпрос Node-мостаPOST-вебхук от Meta
ИсходящиеЛокальный мост → BaileysHTTPS к graph.facebook.com
ГруппыПолная поддержкаТолько ЛС (v1)
24-часовое окноНет ограниченийЖёсткое правило — требуются шаблоны после
Голосовые заметки (исх.)НативныеНативные с ffmpeg, иначе MP3
Уведомления о прочтенииНетДа (синие двойные галочки)
Индикатор набораНетДа (автоисчезает при ответе)
Интерактивные кнопкиТолько текстНативные (clarify, approval, slash-confirm)
Использование в productionРискованно (Meta может заблокировать)Предназначено для этого

Большинство пользователей, запускающих VibeOS для личных проектов, предпочитают Baileys. Большинство пользователей, запускающих ботов для клиентов, предпочитают Cloud API.

См. также​