Skip to main content
Полный каталог на основе схемы см. в разделе все примеры.

Что это такое

Обрабатывайте события проверки, обновления и удаления бизнес-аккаунтов, а также удаления телефонных номеров, проверки отображаемого имени, качества и обновления Business Username. Маршрутизируйте каждую полезную нагрузку по точному значению события type: для событий аккаунта используется whatsappBusinessAccount, а для событий телефонных номеров — whatsappPhoneNumber.

Перед началом работы

  • Создайте общедоступную конечную точку HTTPS в своем приложении.
  • Настройте конечную точку Webhook YCloud для необходимых типов событий.
  • Надежно сохраните секрет подписи конечной точки.
  • Обеспечьте идемпотентность обработки событий.

Как это работает

YCloud отправляет HTTP-запрос POST при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ 2xx и выполняйте длительные операции асинхронно.

Запрос

Приведенные ниже сценарии демонстрируют запросы, доставляемые на ваш URL Webhook. Используйте id события в качестве идентификатора доставки, а type — для маршрутизации полезной нагрузки.

Ответ

Возвращайте статус 2xx после принятия события.
Инструкции по настройке конечной точки, проверке подписи и логике повторных попыток см. в разделе Настройка Webhook.

Удаление аккаунта

Используйте whatsapp.business_account.deleted для обработки события удаления WhatsApp Business Account. Читайте whatsappBusinessAccount.id, чтобы определить затронутый WABA.

Запрос

Ответ

Подтверждайте получение доставки после надежного сохранения события.

Объяснение

Поля удаления отображаются непосредственно внутри whatsappBusinessAccount, если они доступны. Известные значения removedReason включают: Сохраняйте неизвестные значения причин и инициаторов. Выполняйте дедупликацию доставок по id события и корректно обрабатывайте отсутствие полей удаления.

Доступность международных тарифов на аутентификацию

Начиная с 1 июня 2024 года, мы вводим новый международный тариф на аутентификацию. Этот тариф будет действовать в следующих странах:
  • 1 июня 2024 г. — Индонезия (телефонный код страны +62, код страны ID)
  • 1 июля 2024 г. — Индия (телефонный код страны +91, код страны IN)
Дополнительные сведения см. в разделе Доступность международных тарифов на аутентификацию. Webhook whatsapp.business_account.updated будет активирован, если ваш бизнес будет признан подходящим для международных тарифов. Webhook будет содержать время начала действия для каждой страны, в которой действует международный тариф на аутентификацию.

Запрос

Ответ

Подтверждайте получение доставки после надежного сохранения события.
Если за сообщение взимается плата по международному тарифу на аутентификацию, то поле whatsappMessage.pricingCategory в Webhook whatsapp.message.updated будет иметь значение authentication_international. Вот пример:

Объяснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Обновление основного местоположения бизнеса

Ваше основное местоположение бизнеса — это страна, в которой зарегистрирована ваша компания. Начиная с 1 мая 2024 года, оно будет отображаться в Business Manager в поле Primary Business Location. Если Meta удастся определить страну, в которой зарегистрирована ваша компания, мы отправим Webhook whatsapp.business_account.updated с двухзначным кодом страны. Вот пример:

Запрос

Ответ

Подтверждайте получение доставки после надежного сохранения события.

Объяснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Обновление лимита регистрации телефонных номеров

Meta отправляет обновление возможностей бизнеса для WABA при изменении лимита регистрации телефонных номеров в соответствующем Business Portfolio или WABA. YCloud доставляет его как whatsapp.business_account.updated с updateEvent=BUSINESS_CAPABILITY_UPDATE. Этот Webhook относится к уровню WABA: whatsappBusinessAccount.id — это идентификатор WABA из записи вебхука Meta. В настоящее время Meta сообщает о maxPhoneNumbersPerBusiness и maxPhoneNumbersPerWaba в отдельных обновлениях. Не рассматривайте их как взаимоисключающие: обрабатывайте каждое поле независимо и принимайте оба, если в будущих обновлениях они будут переданы вместе. Значение 0 является допустимым. Вот пример обновления лимита телефонных номеров WABA:

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и обновляйте только то поле лимита, которое включено в полезную нагрузку.

Нарушение со стороны аккаунта

При получении события whatsapp.business_account.updated, в котором поле whatsappBusinessAccount.updateEvent имеет значение ACCOUNT_VIOLATION, проверьте whatsappBusinessAccount.violationType, чтобы определить зафиксированное нарушение политики. Типы нарушений и их описания приведены в документации Meta Нарушения правил и меры принудительного характера. Meta может со временем обновлять этот список. Вот пример:

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и выносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Ограничение аккаунта

Если бизнес-аккаунты неоднократно нарушают Условия предоставления услуг WhatsApp Business или политики категорий повышенного риска (например, рассылка спама, контент для взрослых, продажа алкоголя и табака, наркотики, азартные игры и небезопасные биодобавки), в их отношении могут начать применяться ограничения на отправку сообщений с постепенным увеличением срока действия. Для Utility Direct Send см. раздел Уведомления Direct Send с полезной нагрузкой ACCOUNT_RESTRICTION от YCloud. См. документацию Meta Вебхук для ограничения аккаунта, где описаны специфичные для Direct Send типы нарушений и сведения об ограничениях. Вот пример:

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и выносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Ограничение Utility Direct Send

Вы получаете whatsapp.business_account.updated, когда Meta ограничивает использование Utility Direct Send после повторного нецелевого использования категорий. В этом примере показано семидневное ограничение.

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Используйте whatsappBusinessAccount.id, чтобы определить затронутый WABA и приостановить его рабочий процесс Utility Direct Send. Значение поля violationType указывает причину, restrictions[].restrictionType — затронутую функцию, а restrictions[].expiration — срок окончания (если указан). Успешная проверка одного шаблона не приводит к автоматическому снятию ограничения на уровне всего аккаунта. См. раздел Ограничения и уведомления Direct Send.

Отключение аккаунта

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

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и выносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Восстановление аккаунта

Вы можете обжаловать решение о блокировке аккаунта WhatsApp Business, чтобы восстановить его. После одобрения статус проверки аккаунта изменится на APPROVED. Вот пример:

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Маршрутизируйте событие по type, выполняйте дедупликацию по id и выносите медленные или подверженные сбоям задачи в асинхронный обработчик.

Проверка бизнес-аккаунта

Используйте whatsapp.business_account.reviewed, когда аккаунт WhatsApp Business прошел проверку.

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Определите WABA с помощью id. Прочитайте поле decision, чтобы узнать решение проверки (APPROVED или REJECTED), и поле accountReviewStatus для статуса проверки аккаунта (если оно передано). Не маршрутизируйте это событие как whatsapp.business_account.updated.

Удаление телефонного номера

Используйте whatsapp.phone_number.deleted, когда удаляется рабочий телефонный номер WhatsApp.

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Используйте whatsappPhoneNumber.id, чтобы определить удаленный номер телефона, и wabaId, чтобы связать его с соответствующим аккаунтом. Это событие телефонного номера; не интерпретируйте его как удаление всей WABA.

Проверка отображаемого имени телефонного номера

Используйте whatsapp.phone_number.name_updated, когда отображаемое имя рабочего телефонного номера одобрено или отклонено.

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Проверьте decision и переданные поля статуса имени. Поле newNameStatus описывает новый запрос отображаемого имени, requestedVerifiedName указывает последнее запрошенное имя, а rejectionReason описывает причину отклонения (если присутствует). Проверка отображаемого имени не связана с обновлением Business Username.

Обновление качества телефонного номера

Используйте whatsapp.phone_number.quality_updated для отслеживания изменений статуса качества рабочего телефонного номера.

Запрос

Ответ

Подтвердите получение (ack) после надежного сохранения события.

Пояснение

Прочитайте qualityRating (GREEN, YELLOW или RED) и qualityUpdateEvent, чтобы понять суть обновления. messagingLimit — это уровень (tier) номера телефона; whatsappBusinessManagerMessagingLimit — это лимит владеющего бизнес-портфолио. Разделяйте эти поля и обновляйте только те значения, которые переданы в событии.

Business Username активирован

Используйте whatsapp.phone_number.business_username_updated для синхронизации Business Username номера телефона.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

businessUsername — это активное имя пользователя без начального символа @. Читайте businessUsernameStatus и businessUsernameUpdatedAt вместе с id номера телефона. Не путайте это значение с подтвержденным отображаемым именем (display name).

Запрос Business Username зарезервирован

Активный Business Username может продолжать использоваться, пока запрос на замену находится в состоянии резервации.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

В этом примере businessUsername остается acme.support, в то время как requestedBusinessUsername имеет значение acme.help. Статус reserved описывает ожидающий запрос, а не активацию замены. Принимайте устаревшее значение pending_review при чтении старых событий; новые операции записи используют reserved.

Business Username отозван

Тип события остается whatsapp.phone_number.business_username_updated. businessUsernameContext — это необязательная строка. Значение revoked описывает уведомление об отзыве; оно отделено от businessUsernameStatus.

Запрос

Ответ

Подтвердите доставку после надежного сохранения события.

Пояснение

YCloud обновляет актуальное имя пользователя и статус из Meta перед генерацией этого события. Поле revoked включается только тогда, когда имя пользователя, возвращенное успешным текущим запросом к Meta, совпадает с именем пользователя в уведомлении об отзыве. Если уведомление относится к имени пользователя A, но Meta теперь возвращает B, отправленное событие содержит B и опускает устаревший контекст revoked. Контекст также опускается, когда уведомление не содержит контекста. Исторические предупреждения, отображаемые в консоли, не воспроизводятся в этом поле. Имитация вышестоящего уведомления не заменяет имя пользователя или статус, возвращенные Meta.