API WhatsApp Business Management

Компоненты Webhooks

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

Webhooks в API WhatsApp Business Management могут содержать следующие объекты:

ПараметрОписание

object

Объект, на который вы подписались.


Для встроенной регистрации всегда имеет значение whatsapp_business_account.

entry

Этот объект содержит информацию об изменении, которое активировало вызов Webhook.

Объект entry

ПараметрОписание

id

ID аккаунтов WhatsApp Business, с которыми связан этот Webhooks.

time

Время записи.

changes

Изменения, которые активировали вызов Webhooks. См. объект changes.

changes

ПараметрОписание (нажмите стрелку в столбце слева, чтобы открыть список поддерживаемых значений).

field

Тип уведомления Webhooks.

Поддерживаемые значения

  • account_alerts
  • account_review_update
  • account_update
  • business_capability_update
  • message_template_quality_update
  • message_template_status_update
  • phone_number_name_update
  • phone_number_quality_update
  • security
  • template_category_update

value

Содержит информацию об изменениях, связанных с указанным полем (field). См. объект value.

value

ПараметрОписание (нажмите стрелку в столбце слева, чтобы открыть список поддерживаемых значений)

ban_info

Добавляется в Webhooks, если аккаунт был заблокирован. Этот объект имеет два свойства:

  • waba_ban_state с одним из следующих значений:
    • DISABLE;
    • REINSTATE;
    • SCHEDULE_FOR_DISABLE;
  • waba_ban_date.

current_limit

Текущий уровень ограничения для аккаунта.

Поддерживаемые значения

  • TIER_50
  • TIER_250
  • TIER_1K
  • TIER_10K
  • TIER_100K
  • TIER_UNLIMITED

decision

Используется, если решение об аккаунтах или номерах телефонов принято.

Поддерживаемые значения

  • APPROVED
  • REJECTED

display_phone_number

Содержит отображаемый номер телефона бизнес-аккаунта, для которого активировано уведомление.

event

Используется, если событие произошло в определенном аккаунте WhatsApp Business. Нажмите стрелку в левом столбце, чтобы посмотреть все возможные варианты.

Обновления отображаемого имени

  • APPROVED — проверка окончена, имя одобрено. Если ранее компания не могла скачать свой сертификат, теперь у нее должна быть такая возможность, и она может использовать свое отображаемое имя.
  • DEFERRED — проверка отложена. Компания может использовать свое отображаемое имя, скачав сертификат.
  • REJECTED — имя отклонено по указанной причине. Если ранее компания не могла скачать свой сертификат, теперь, чтобы получить к нему доступ, она должна повторно подать заявку на проверку отображаемого имени. Если компания уже использует свой сертификат, отклонение отображаемого имени в результате проверки не повлияет на ее работу. Однако чтобы увеличить лимит сообщений и аккаунтов, необходимо пройти проверку.

Обновление оценки качества шаблона сообщения

Предыдущая оценка качества:


  • GREEN;
  • RED;
  • UNKNOWN;
  • YELLOW.

Новая оценка качества:


  • GREEN;
  • RED;
  • UNKNOWN;
  • YELLOW.

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

  • APPROVED
  • DISABLED
  • IN_APPEAL
  • PENDING
  • REINSTATED
  • REJECTED
  • FLAGGED

Обновления номера телефона

  • DOWNGRADE
  • FLAGGED
  • ONBOARDING
  • UNFLAGGED
  • UPGRADE

Обновление категории шаблона

Предыдущие категории:


  • MARKETING;
  • OTP;
  • TRANSACTIONAL.

Новые категории:


  • AUTHENTICATION;
  • MARKETING;
  • UTILITY.

Код подтверждения двухшаговой проверки

  • PIN_CHANGED: код подтверждения двухшаговой проверки обновлен (только для облачного API).
  • PIN_RESET_REQUEST: запрос на отключение кода подтверждения двухшаговой проверки.
  • PIN_RESET_SUCCESS: код подтверждения двухшаговой проверки отключен.

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

  • ACCOUNT_RESTRICTION: используется, если на аккаунт WhatsApp Business наложено ограничение из-за нарушения условий использования платформы WhatsApp Business.
  • DISABLED_UPDATE
  • VERIFIED_ACCOUNT

max_daily_conversation_per_phone

Всегда присутствует, если используется field=business_capability_update.


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

max_phone_numbers_per_business

Содержит максимальное количество номеров телефонов, которые может иметь компания.


Если field=business_capability_update, Webhook будет иметь один из двух параметров: max_phone_numbers_per_business или max_phone_numbers_per_waba.

max_phone_numbers_per_waba

Содержит максимальное количество номеров телефонов, которые может иметь аккаунт WhatsApp Business.


Если field=business_capability_update, Webhooks будет иметь один из двух параметров: max_phone_numbers_per_business или max_phone_numbers_per_waba.

reason

Причина отклонения шаблона. Возможные значения:


  • ABUSIVE_CONTENT — контент признан оскорбительным;
  • INCORRECT_CATEGORY — категория признана неправильной (см. раздел Категории шаблонов);
  • INVALID_FORMAT — дублируется контент или отсутствуют примеры;
  • NONE — значение по умолчанию, когда шаблон одобрен;
  • SCAM — контент признан мошенническим.

rejection_reason

Если запрос отклонен, в этом поле указана причина.

requested_verified_name

Оправленное на проверку имя.

restriction_info

enum

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


Список видов ограничений и их сроки истечения. Возможные виды ограничений:


  • RESTRICTED_ADD_PHONE_NUMBER_ACTION;
  • RESTRICTED_BIZ_INITIATED_MESSAGING;
  • RESTRICTED_CUSTOMER_INITIATED_MESSAGING.

Сроки действия указаны в формате DateTime.

requester

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

Примеры

Обновления, связанные со статусом шаблона сообщения

Одобрение шаблона

{
  "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 
         }
       }
      ]
    }
  ]
}

Отклонение шаблона

{
  "object": "whatsapp_business_account"
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "value": {
            "event": "REJECTED",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>",
            "reason": "<REJECTION_REASON>"
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ]
}

Планирование отключения шаблона

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "field": "message_template_status_update",
          "value": { 
              "event": "FLAGGED",
              "message_template_id": TEMPLATE-ID, 
              "message_template_name": "My message template",
              "message_template_language": "en-US",
              "reason": null,
              "disable_info": {
                  "disable_date": "DATE",
              }
         }
       }
      ]
    }
  ]
}

Приостановка шаблона

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10908...",
      "time": 1661885238,
      "changes": [
        {
          "value": {
            "event": "PAUSED",
            "message_template_id": 6048...,
            "message_template_name": "welcome",
            "message_template_language": "en_US",
            "reason": "NONE",
            "other_info": {
              "title": "SECOND_PAUSE",
              "description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues."
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

Шаблон сообщения ожидает удаления

{
  "object": "whatsapp_business account",
  "entry": [
    {
      "id": "10310...",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "PENDING_DELETION",
            "message_template_id": 1137...,
            "message_template_name": "<MY_TEMPLATE_NAME>",
            "message_template_language": "en_US",
            "reason": "NONE"            
            }
          },
          "field": "message_template_status_update"
        }
      ]
    }
  ],
}

Обновления, связанные с категорией шаблона

Изменение категории шаблона

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<ID>",
      "time": <TIME>,
      "changes": [
        {
          "field": "template_category_update",
          "value": {            
            "message_template_id": <MESSAGE_TEMPLATE_ID>,
            "message_template_name": "<MESSAGE_TEMPLATE_NAME>",
            "message_template_language": "<MESSAGE_TEMPLATE_LANGUAGE",
            "previous_category": "<PREVIOUS_CATEGORY>",
            "new_category": "<NEW_CATEGORY>"
          }
        }
      ]
    }
  ]
}

Обновления, связанные с оценкой качества шаблона сообщения

Изменение оценки качества шаблона

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <TIMESTAMP>,
      "changes": [
        {
          "field": "message_template_quality_update",
          "value": {
            "previous_quality_score": "<PREVIOUS_QUALITY_SCORE>",
            "new_quality_score": "<NEW_QUALITY_SCORE>",
            "message_template_id": <TEMPLATE_ID>,
            "message_template_name": "<TEMPLATE_NAME>",
            "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>"
          }
        }
      ]
    }
  ]
}

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

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

{
  "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": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "VIOLATION_TYPE"
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

На аккаунт WhatsApp Business наложены ограничения после нарушения правил

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
               {"restriction_type": 
                 "RESTRICTED_BIZ_INITIATED_MESSAGING" | 
                 "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION" | 
                 "RESTRICTED_CUSTOMER_INITIATED_MESSAGING", 
                 "expiration": TIMESTAMP}
                 ]
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

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

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
            "event": "DISABLED_UPDATE",
            "ban_info": {
              "waba_ban_state": 
               "SCHEDULE_FOR_DISABLE" | 
               "DISABLE" | 
               "REINSTATE",
               "waba_ban_date": TIMESTAMP
            }
          },
          "field": "account_update"
        }
      ]
    }
  ]
}

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

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

На аккаунт WhatsApp Business наложены ограничения из-за нарушения правил

{
  "field": "account_update",
  "value": {
    "phone_number": "PHONE_NUMBER",
    "event": "ACCOUNT_RESTRICTION",
    "restriction_info": [
      {
        "restriction_type": "RESTRICTION_ADD_PHONE_NUMBER_ACTION",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      },
      {
        "restriction_type": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": TIMESTAMP
      }
    ]
  }
}

Аккаунт WhatsApp Business удален

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "ACCOUNT_DELETED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

Аккаунт WhatsApp Business удален у партнера

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
      "time": TIMESTAMP,
      "changes": [
        {
          "value": {
              "phone_number": "15551...",
              "event": "PARTNER_REMOVED",
           },
          "field": "account_update"
        }
      ]
    }
  ]
}

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

{
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
        "time": TIMESTAMP,
        "changes": [
          {
            "field": "business_capability_update",
            "value": {
              "max_daily_conversation_per_phone": NUMBER,
              "max_phone_numbers_per_business": NUMBER
            }
          }
        ]
      }
    ]
  }

Оповещения, связанные с аккаунтом

Отказ в увеличении ограничения на число сообщений

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "CRITICAL",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_FAILED",
            "alert_description": "Based on your activity, limits cannot be increased for your business <BUSINES_NAME>. Contact support for more information."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Отказ в увеличении ограничения на число сообщений, нужно использовать больше

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED",
            "alert_description": "Limits cannot be increased for your business <BUSINES_NAME>. Use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}

Отказ в увеличении ограничения на число сообщений, требуется дополнительная информация

{
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "time": <UNIX_TIMESTAMP>,
      "changes": [
        {
          "value": {
            "entity_type": "BUSINESS",
            "entity_id": "<BUSINESS_ID>",
            "alert_severity": "WARNING",
            "alert_status": "ACTIVE",
            "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO",
            "alert_description": "Additional verification is required for your business <BUSINESS_NAME>. Go to Security Center in Meta for Business to complete identity verification. To continue without completing additional verification, your business can use WhatsApp Business platform actively for several days and follow our messaging policies."
          },
          "field": "account_alerts"
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}