Примеры вебхуков обновления WhatsApp Business Account

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

Что это такое

Обработка событий обновления WhatsApp Business Account.

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

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

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

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

Запрос

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

Ответ

Возвращайте статус 2xx после успешного принятия события.

HTTP/1.1 200 OK

Информацию о настройке конечной точки, проверке подписи и механизме повторных попыток см. в разделе Настройка вебхуков.

Право на международный тариф для сообщений аутентификации

С 1 июня 2024 года вводится новый международный тариф для аутентификации. Этот тариф будет действовать в следующих странах:

1 июня 2024 г. – Индонезия (телефонный код страны +62, код страны ID)
1 июля 2024 г. – Индия (телефонный код страны +91, код страны IN)

Дополнительные сведения см. в разделе Право на международный тариф для сообщений аутентификации. Webhook whatsapp.business_account.updated активируется, если ваша компания признана подходящей для международных тарифов. Webhook будет содержать время начала действия для каждой страны, в которой применяется международный тариф для аутентификации.

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

Ответ

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

HTTP/1.1 200 OK

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

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}

Пояснение

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

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

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

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

Ответ

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

HTTP/1.1 200 OK

Пояснение

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

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

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

Ответ

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

HTTP/1.1 200 OK

Пояснение

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

Нарушение правил аккаунтом

WhatsApp Business Accounts сначала получают предупреждение с информацией о нарушенных правилах. См. также Нарушения политик WhatsApp Business Platform
. Вот пример:

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SPAM"
  }
}

Ответ

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

HTTP/1.1 200 OK

Пояснение

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

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

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
    ]
  }
}

Ответ

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

HTTP/1.1 200 OK

Пояснение

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

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

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

Ответ

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

HTTP/1.1 200 OK

Пояснение

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

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

Запрос

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

Ответ

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

HTTP/1.1 200 OK

Пояснение

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

Начало работы

Руководства

Конечные точки

Webhooks

Примеры вебхуков обновления WhatsApp Business Account

Что это такое

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

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

Запрос

Ответ

Право на международный тариф для сообщений аутентификации

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

Нарушение правил аккаунтом

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

​Что это такое

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

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

​Запрос

​Ответ

​Право на международный тариф для сообщений аутентификации

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

​Нарушение правил аккаунтом

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

Что это такое

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

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

Запрос

Ответ

Право на международный тариф для сообщений аутентификации

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

Нарушение правил аккаунтом

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение