ВойтиНачать бесплатный пробный период
Meta Tech Provider

Вебхуки WhatsApp: маршрутизация сообщений на ваш сервер

Вебхук WhatsApp представляет собой HTTPS-эндпоинт, который вы указываете, а Meta отправляет на него события: входящие сообщения, статусы доставки, изменения рейтинга качества и обновления аккаунта. Для номера Coexistence назначение можно указать на своём сервере, поэтому переписка вообще не проходит через провайдера.

EasyCoexistence устанавливает переопределение вебхука на ваш эндпоинт, проверяет его до вызова и автоматически применяет снова после любого подключения.

  • Meta отправляет события прямо на ваш URL
  • Ваш эндпоинт, а не платформа провайдера
  • Одно переопределение на каждый WhatsApp Business Account
Начать бесплатный пробный период

В течение 3 дней ничего не списывается. Отмена в любое время.

Не храним сообщения по умолчаниюBusiness App + Cloud APIMCP для Claude и ChatGPTПодключение за 2 минуты
1 URL

Что представляет собой вся интеграция: один HTTPS-адрес назначения на аккаунт.

2 fields

messages и smb_message_echoes, события пути сообщений, которые направляются вам.

hub.challenge

Значение, которое Meta отправляет при GET-проверке и которое ваш эндпоинт должен вернуть.

Что именно Meta отправляет на вебхук?

События, разделённые на категории. Различие между ними определяет архитектуру интеграции.

Путь сообщений содержит то, что отправляют клиенты, а для номера Coexistence также копии сообщений, которые ваша команда отправляет из приложения WhatsApp Business. Это поля messages и smb_message_echoes, содержащие переписку.

Операционный путь содержит всё остальное: account_update при изменении состояния подключения, phone_number_quality_update при изменении качества или пропускной способности, account_alerts, account_review_update, business_capability_update и phone_number_name_update. В них нет содержания переписки, на них строятся мониторинг и оповещения.

Провайдер, который ставит себя в путь сообщений, получает первую группу событий. Провайдер, который этого не делает, её не получает.

Как Meta проверяет эндпоинт?

Сначала отправляется GET-запрос, и только после успешной проверки Meta начинает доставку. Ошибка на этом этапе чаще всего объясняет, почему готовая на вид настройка не получает сообщений.

Meta обращается к вашему URL с hub.mode, равным subscribe, вашим hub.verify_token и значением hub.challenge. Эндпоинт должен вернуть это challenge как необработанное тело ответа, без JSON и любых добавлений. Если этого не произойдёт, Meta не начнёт доставку, а в панели управления это никак не отобразится.

Эндпоинт также должен работать через HTTPS. Эндпоинт с незаметной ошибкой 404 или с уровнем аутентификации, отклоняющим запрос Meta, выглядит рабочим до самого момента, когда первое сообщение так и не приходит.

Можно ли направить назначение на свой сервер?

Да, и именно здесь различаются провайдеры.

Meta позволяет приложению переопределить место доставки вебхуков для конкретного WhatsApp Business Account. Мы устанавливаем это переопределение на ваш URL и переносим события пути сообщений с нашего обратного вызова на ваш. Операционные события мы сохраняем, поскольку из них состоят панель управления и оповещения.

Последствие связано с архитектурой, а не с опубликованной нами политикой. По умолчанию содержание переписки негде хранить на нашей стороне, потому что оно к нам не доставляется. Для аккаунта без переопределения используется наш обратный вызов, где по умолчанию обработчик отбрасывает эти события без сохранения.

Что происходит с назначением при повторном подключении номера?

Оно удаляется. Это сбой, который почти никто не закладывает в план.

Назначение не является свойством номера телефона. Это переопределение подписки нашего приложения на WhatsApp Business Account. Когда подключение удаляется из-за правила Meta о четырнадцати днях неактивности или по другой причине, приложение удаляется из аккаунта вместе с этим переопределением.

Повторное подключение восстанавливает отправку и мониторинг. Оно не восстанавливает доставку на ваш сервер, и об ошибке ничего не сообщает. Поэтому первым сигналом может стать клиент, который скажет, что ему никто не ответил. Мы повторно применяем переопределение при каждом подключении, потому что такое уже произошло с реальным номером: он подключился без ошибок, но сообщения перестали поступать.

Распространённые ошибки

  • Возвращать JSON из GET-запроса проверки. Meta нужен только исходный параметр hub.challenge.
  • Использовать временный или тестовый URL. Meta продолжит отправлять на него запросы после того, как инструмент, создавший URL, перестанет его обслуживать.
  • Считать, что назначение сохраняется после повторного подключения. Оно относится к подписке приложения и удаляется вместе с ней.
  • Размещать эндпоинт за аутентификацией, отклоняющей запрос Meta.
Настройка с EasyCoexistence

От US$ 9 за подключённый номер в месяц, до US$ 0,75 по мере добавления номеров; первые 3 дня бесплатно.

Часто задаваемые вопросы

Проходят ли мои сообщения через EasyCoexistence?

По умолчанию нет. Переопределение направляет события пути сообщений от Meta прямо на ваш эндпоинт. Для аккаунта без переопределения события возвращаются к нашему обратному вызову и отбрасываются без сохранения.

Можно ли позже изменить назначение?

Да, в любое время через панель управления или подключение MCP. Передача null сбрасывает его к нашему назначению по умолчанию.

Что будет, если мой сервер недоступен во время доставки Meta?

Meta будет повторять попытки некоторое время, а затем остановится. Сообщения всё равно поступят в приложение WhatsApp Business на телефоне, поэтому бизнес ничего не потеряет, даже если интеграция не сработает.

Достаточно ли одного вебхука для нескольких номеров?

Да. Укажите один и тот же эндпоинт для каждого номера и разделяйте события по идентификатору номера телефона получателя в полезной нагрузке.

Читайте дальше

Готовы начать?

Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.

Начать бесплатный пробный периодВ течение 3 дней ничего не списывается. Отмена в любое время.

Проверено по состоянию на