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

Что именно 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.

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

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