Перейти к основному содержимому

Веб-хуки | Документация для разработчиков

Вебхуки

Обновлено: 2 декабря 2025 г
В этом документе описываются веб-хуки и способы их использования платформой WhatsApp Business.
Вебхуки — это HTTP-запросы, содержащие JSON-данные, которые отправляются с серверов Meta на указанный вами сервер. Платформа WhatsApp Business использует вебхуки для информирования вас о входящих сообщениях, статусе исходящих сообщений и другой важной информации, такой как изменения статуса вашей учетной записи, обновления возможностей обмена сообщениями и изменения оценок качества ваших шаблонов.
Например, это веб-хук, описывающий сообщение, отправленное пользователем WhatsApp компании:


{

"объект":

"whatsapp_business_account",

"вход":

[ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "contacts": [ { "profile": { "name": "Sheena Nelson" }, "wa_id": "16505551234" } ], "messages": [ { "from": "16505551234", "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=", "timestamp": "1749416383", "type": "text", "текст": { "тело": "Есть ли он в другом цвете?" } } ] }, "поле": "сообщения" } ] } ] }
Создайте конечную точку веб-перехватчика


Для приема веб-хуков необходимо создать и настроить конечную точку веб-хука. Инструкции по созданию собственной конечной точки см. в нашем документе «Создание конечной точки веб-хука».


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








Разрешения


Для получения веб-хуков вам потребуются следующие разрешения:


    whatsapp_business_messaging — для веб-хуков сообщенийwhatsapp_business_management — для всех остальных веб-хуков

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

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

    

    

    

    Поля
    

    После создания и настройки конечной точки веб-перехватчика (или настройки тестовой конечной точки веб-перехватчика ) используйте  управления приложением > WhatsApp > Конфигурация , чтобы подписаться на отдельные поля веб-перехватчика.
    

    Обратите внимание, что если вы создали приложение, используя  взаимодействия с клиентами через WhatsApp , перейдите в Панель управления приложениями > Сценарии использования > Настройка > Конфигурация .
    

    

    



Название поля 

Описание 






    

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





    

    Веб  account_review_update уведомляет вас о том, что учетная запись WhatsApp Business была проверена на соответствие нашим правилам.
    





    

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





    

     automatic_events  , который отправил вам сообщение через вашу рекламу Click to WhatsApp, если вы включили  по автоматическим событиям .
    





    

    Веб  business_capability_update уведомляет вас об изменениях в возможностях бизнес-аккаунта WhatsApp или бизнес-портфеля ( лимиты на сообщения , лимиты на номера телефонов и т. д.).
    





    

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





    

    Веб  message_template_components_update уведомляет вас об изменениях в компонентах шаблона.
    





    

    Веб  message_template_quality_update  оценке качества шаблона .
    





    

    Веб  message_template_status_update уведомляет вас об изменениях статуса существующего шаблона.
    





    

    Веб  сообщений описывает сообщения, отправленные пользователем WhatsApp компании, а также статус сообщений, отправленных компанией пользователю WhatsApp.
    





    

    Веб -хук partner_solutions описывает изменения статуса многопартнерского решения .
    





    

     перехватчик payment_configuration_update уведомляет вас об изменениях в конфигурации платежей для Payments API India и Payments API Brazil .
    





    

    Веб  phone_number_name_update уведомляет вас о  проверки отображаемого имени  .
    





    

    Веб  phone_number_quality_update  уровня пропускной способности бизнес-телефонного номера .
    





    

    Веб  безопасности уведомляет вас об изменениях в настройках безопасности корпоративного телефонного номера.
    





    

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





    

    Веб  smb_message_echoes уведомляет вас о сообщениях, отправленных через приложение WhatsApp Business или сопутствующее («связанное») устройство бизнес-клиентом, подключенным к Cloud API через поставщика решений.
    





    

    Веб  template_category_update  категории шаблона .
    





    

    Веб  user_preferences  настройках получения маркетинговых сообщений пользователем WhatsApp .
    

    

    

    

    Переопределение веб-хуков
    

     определенных полей веб-перехватчика  вы можете использовать альтернативную конечную точку веб-перехватчика. Это может быть полезно для целей тестирования или если вы являетесь поставщиком решений и хотите использовать уникальные конечные точки веб-перехватчика для каждого из ваших подключенных клиентов.
    

    Чтобы узнать, как переопределять веб-хуки, ознакомьтесь с нашим 
    

    

    

    

    размер полезной нагрузки
    

    Размер полезной нагрузки веб-хука может достигать 3 МБ.
    

    

    

    

    Сбой доставки веб-хука
    

    Если мы отправим запрос веб-хука на вашу конечную точку, и ваш сервер ответит кодом состояния HTTP, отличным от 200, или если мы не сможем доставить веб-хук по другой причине, мы будем продолжать попытки с уменьшающейся частотой до тех пор, пока запрос не будет успешно выполнен, в течение до 7 дней.
    

    Обратите внимание, что повторные попытки будут отправлены всем приложениям, подписанным на веб-хуки (и соответствующие поля) для бизнес-аккаунта WhatsApp. Это может привести к дублированию уведомлений веб-хуков.
    

    

    

    

    Взаимная TLS
    

     Инструкции по включению и использованию mTLS см. в документе Graph API, посвященном mTLS для веб-хуков 
    

    

    

    

    IP-адреса
    

    IP-адреса наших веб-серверов можно получить, выполнив в терминале следующую команду:
    

    whois - ч кто . радб . сеть — '-i происхождение AS32934' | grep '^route' | awk '{print $2}' | сортировать
    

    Вы также можете использовать нашу геолокационную ленту, чтобы загрузить CSV-файл со списком наших IP-адресов.
    

    Однако обратите внимание, что мы периодически меняем наши IP-адреса, поэтому, чтобы избежать необходимости повторного формирования списка разрешенных IP-адресов, мы рекомендуем использовать mTLS .
    

    

    

    

    Поиск неисправностей
    

    Если вы не получаете веб-хуки:
    

      Убедитесь, что ваша конечная точка принимает запросы.Отправьте тестовую полезную нагрузку на вашу конечную точку через  управления приложением > WhatsApp > Настройки .Убедитесь, что ваше приложение находится в  Live ; некоторые веб-хуки не будут отправляться, если ваше приложение находится в  Dev .Используйте нашу тестовую конечную точку веб-перехватчика . Если тестовая конечная точка обрабатывает данные веб-перехватчика и отображает их в консоли, проблема, скорее всего, в коде вашей конечной точки.

      

      

      

      Узнать больше
      

        См. нашу статью в блоге WhatsApp Business « Использование Node.js для реализации веб-хуков» 
        
    
                
        
    
        

            
        
        
        
    
        

    
        

    
    
        
        
        
             Вернуться наверх