Webhooks

Аккаунты WhatsApp Business и их ресурсы представлены в социальном графе Facebook объектами. Как только для одного из этих объектов срабатывает событие-триггер, Facebook отправляет уведомление на URL Webhooks, заданный на панели приложения Facebook.

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

На каждый аккаунт WhatsApp Business, для которого вы хотите получать Webhooks, необходимо подписаться отдельно. Получив ID аккаунта WhatsApp Business клиента, подпишите приложение на него, чтобы начать получать Webhooks.

Подробнее см. в статье о Webhooks для аккаунтов WhatsApp Business.

Подписка на аккаунт WhatsApp Business

Сначала настройте продукт Webhooks для приложения:

Перейдите на панель приложений и добавьте продукт Webhooks для приложения, если это ещё не сделано.
Выберите продукт Webhooks в меню слева.
В раскрывающемся меню выберите аккаунт WhatsApp Business, а затем нажмите Подписаться на этот объект.
Укажите URL обратного вызова Webhooks и маркер подтверждения, проверьте и сохраните изменения.

Подробнее о подписке на Webhooks на панели приложений см. в разделе Настройка продукта Webhooks.

Настроив Webhooks на панели продукта Webhooks, отправьте запрос POST к конечной точке subscribed_apps для того аккаунта WhatsApp Business, для которого необходимо получать Webhooks.

ID аккаунта WhatsApp Business можно просмотреть здесь: Business Manager > Настройки компании > Аккаунты > Аккаунты WhatsApp Business. Нажмите нужный аккаунт. Откроется панель с информацией о нем, включая ID аккаунта.

В заголовке запроса укажите свой маркер доступа системного пользователя, перед которым должен следовать параметр Authorization: Bearer. Справку по генерации маркера доступа системного пользователя см. в разделе "Системные пользователи: установка приложений и создание маркеров".

Синтаксис запроса

POST https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Пример запроса

curl -X POST \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Пример ответа

{
   "success" : true
}

Ваше приложение, которое идентифицируется по маркеру доступа системного пользователя, теперь должно получать уведомления Webhooks с описанием изменений для аккаунта WhatsApp Business.

Повторите этот процесс для каждого аккаунта WhatsApp Business, для которого необходимо получать уведомления Webhooks. Обратите внимание: если вы подпишите свое приложение на Webhooks для нескольких аккаунтов WhatsApp Business, все уведомления Webhooks будут отправляться на тот URL-адрес обратного вызова приложения, который указан на панели продукта Webhooks на панели приложений.

Если для каждого аккаунта WhatsApp Business вы хотите использовать разные URL обратного вызова, создайте отдельные приложения с собственным URL обратного вызова для каждого аккаунта WhatsApp Business и выполните вышеуказанный запрос к каждому такому аккаунту, используя маркер доступа системного пользователя каждого приложения. Как вариант, если вы хотите использовать одно приложение, вы можете переопределить URL обратного вызова при оформлении подписки на Webhooks для каждого аккаунта WhatsApp Business. См. Переопределение URL обратного вызова.

Получение всех подписок для аккаунта WhatsApp Business

Чтобы получить список приложений, подписанных на Webhooks для аккаунта WhatsApp Business, отправьте запрос GET к конечной точке subscribed_apps в аккаунте WhatsApp Business:

Синтаксис запроса

GET https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

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

Пример запроса

curl \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Пример ответа

{
  "data" : [
    {
      "whatsapp_business_api_data" : {
        "id" : "67084...",
        "link" : "https://www.facebook.com/games/?app_id=67084...",
        "name" : "Jaspers Market"
      }
    },
    {
      "whatsapp_business_api_data" : {
        "id" : "52565...",
        "link" : "https://www.facebook.com/games/?app_id=52565...",
        "name" : "Jaspers Fresh Finds"
      }
    }
  ]
}

Отмена подписки для аккаунта WhatsApp Business

Чтобы отменить подписку вашего приложения на Webhooks для аккаунта WhatsApp Business, отправьте запрос DELETE к конечной точке subscribed_apps в аккаунте WhatsApp Business.

Синтаксис запроса

DELETE https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps

Пример запроса

curl -X DELETE \
'https://graph.facebook.com/v19.0/102289599326934/subscribed_apps' \
-H 'Authorization: Bearer EAAJi...'

Пример ответа

{
   "success" : true
}

Переопределение URL обратного вызова

См. статью Переопределения Webhooks.

Настройка уведомлений

Чтобы получать уведомления об изменениях в ваших аккаунтах WhatsApp Business, можно настроить Webhooks. Можно подписаться на следующие виды уведомлений:

Доступные поля подписки

Имя поля	Описание
`account_review_update`	Уведомления об окончании проверки аккаунта WhatsApp Business.
`account_update`	Уведомления об изменениях в вашем аккаунте WhatsApp Business. Это могут быть обновление номера телефона, нарушение политики, блокировка аккаунта WhatsApp Business и др.
`business_capability_update`	Уведомления об изменении ограничений. Например, это может быть ограничение на количество номеров телефонов, связанных с одним аккаунтом WhatsApp Business, или на количество переписок для каждого номера телефона.
`message_template_status_update`	Уведомления об одобрении, отклонении или отключении шаблона сообщения.
`messages`	Уведомления о получении вашей компанией сообщения от клиента, об отправке вами сообщения клиенту, о доставке сообщения клиенту и о прочтении вашего сообщения клиентом.
`phone_number_name_update`	Уведомления об одобрении или отклонении имени, связанного с номером телефона.
`phone_number_quality_update`	Уведомления об обновлении статуса, связанного с качеством, для номера телефона.
`security`	Уведомления о следующем: вы запросили отключение кода двухшаговой проверки; двухшаговая проверка отключена; код двухшаговой проверки обновлен.

Подробнее обо всех полях с полезными данными см. в справке по Webhooks для аккаунта WhatsApp Business , а о типах уведомлений messages, которые можно получать, — в справке по Webhooks для облачного API WhatsApp .

Подробнее см. в документации по Webhooks для аккаунтов WhatsApp Business.

Формат Webhooks

Общий формат уведомлений:

{
  "object": "whatsapp_business_account",
  "entry": [
    { // entry object, containing changes
      "changes": [
        { // changes object, containing value
          "value": {
            // value object
          }
        }
      ]
    }
  ]
}

Далее приведена информация о каждом поле.

Примеры

Обновления, связанные с номером телефона

Получено обновление имени

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243053,
      "changes": [
        {
          "field": "phone_number_name_update",
          "value": {
            "display_phone_number": "16505551111",
            "decision": "APPROVED",
            "requested_verified_name": "WhatsApp",
            "rejection_reason": null
          }
        }
      ]
    }
  ]
}

Получено обновление, связанное с качеством

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "waba-id",
      "time": 1608243062,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "16505551111",
            "event": "FLAGGED",
            "current_limit": "TIER_10K"
          }
        }
      ]
    }
  ]
}

Обновления аккаунта WhatsApp Business

Обновление аккаунта при переходе из песочницы к подтвержденному аккаунту

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505551111",
            "event": "VERIFIED_ACCOUNT"
          }
        }
      ]
    }
  ]
}

Аккаунт WhatsApp Business заблокирован

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703058,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "DISABLED_UPDATE"
            "ban_info": {
              "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"],
              "waba_ban_date": "January 31, 2021"
            }
          }
        }
      ]
    }
  ]
}

Проверка аккаунта WhatsApp Business завершена

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "account_review_update",
          "value": {
            "decision": "APPROVED"
          }
        }
      ]
    }
  ]
}

Обновления шаблона сообщения

Одобрен

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "time": 1604703141,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "APPROVED",
              "message_template_id": 1234567, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null 
         }
       }
      ]
    }
  ]
}