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

Справочник по веб-перехватчикам сообщений о состоянии | Документация для разработчиков

Справочник веб-перехватчиков сообщений о состоянии

Обновлено: 20 ноября 2025 г
В этом справочнике описаны события-триггеры и содержимое полезной нагрузки для сообщений .

Триггеры

    Ваше сообщение отправлено пользователю WhatsApp.Ваше сообщение доставлено на устройство пользователя WhatsApp.Ваше сообщение отображается (то есть «прочитано») в клиенте WhatsApp на устройстве пользователя WhatsApp.Ваше сообщение не может быть отправлено пользователю WhatsApp.Ваше сообщение не может быть доставлено на устройство пользователя WhatsApp.Ваше сообщение отправляется пользователю WhatsApp в групповом чате.Ваше голосовое сообщение воспроизводится устройством пользователя WhatsApp.
    Обратите внимание, что указанные выше триггеры также применяются к пользователям WhatsApp, участвующим в групповом чате.
    Статус сообщения считается прочитанным только в том случае, если оно было доставлено. В некоторых случаях, например, когда пользователь получает сообщение в чате, сообщение одновременно доставляется и читается. В таких случаях веб-хук «доставлено» не отправляется, поскольку подразумевается, что сообщение было доставлено, так как оно было прочитано. Такое поведение обусловлено внутренней оптимизацией.

    Синтаксис

    { "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID> ", "изменения": [ { "значение": { "messaging_product": "whatsapp", "метаданные": { "отображаемый_номер_телефона": "<BUSINESS_DISPLAY_PHONE_NUMBER> ", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID> " }, "statuses": [ { "id": "<WHATSAPP_MESSAGE_ID> ", "статус": "<STATUS> ", "временная метка": "<WEBHOOK_TRIGGER_TIMESTAMP> ", "recipient_id": "<USER_PHONE_NUMBER_OR_GROUP_ID> ", "recipient_type": "group",<!-- Only included if message sent to a group --> "recipient_participant_id": "<GROUP_PARTICIPANT_USER_PHONE_NUMBER> ",<!-- Only included if message sent to a group --> "recipient_identity_key_hash": "<IDENTITY_KEY_HASH> ",<!-- Only included if identity change check enabled --> "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA> ", <!-- Only included if message sent with biz_opaque_callback_data --><!-- (1) Only included with sent status, and one of either delivered or read status (2) Omitted entirely for v24.0+ unless webhook is for a free entry point conversation --> "разговор": { "id": "<CONVERSATION_ID> ", "expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP> ", "origin": { "type": "<CONVERSATION_CATEGORY> " } },<!-- only included with sent status, and one of either delivered or read status --> "ценообразование": { "оплачиваемый":<IS_BILLABLE?> , "pricing_model": "<PRICING_MODEL> ", "тип": "<PRICING_TYPE> ", "категория": "<PRICING_CATEGORY> " },<!-- only included if failure to send or deliver message --> "ошибки": [ { "код":<ERROR_CODE> , "заголовок": "<ERROR_TITLE> ", "сообщение": "<ERROR_MESSAGE> ", "error_data": { "details": "<ERROR_DETAILS> " }, "href": "<ERROR_CODES_URL> " } ] } ] }, "поле": "сообщения" } ] } ] }
    Параметры
    
Заполнитель

Описание

Пример значения

    <BUSINESS_DISPLAY_PHONE_NUMBER>
    Нить
    Номер телефона компании, отображаемый на экране.
    15550783881
    <BUSINESS_OPAQUE_DATA>
    Нить
    Строка, присвоенная бизнес-процессом  biz_opaque_callback_data в запросе на отправку сообщения.
    Включается только в том случае, если компания установила  biz_opaque_callback_data при отправке сообщения.
    1744434060
    <BUSINESS_PHONE_NUMBER_ID>
    Нить
    Идентификатор номера служебного телефона.
    106540352242922
    <CONVERSATION_CATEGORY>
    Нить
    Категория «Разговор» . Возможные значения:
    Аутентификация — указывает на диалог аутентификации.
    маркетинг — указывает на маркетинговую дискуссию.
    marketing_lite — Указывает на API маркетинговых сообщений для переписки в WhatsApp.
    referral_conversion — Указывает на бесплатную точку входа в диалог.
    сервис — Обозначает разговор об обслуживании.
    утилита — указывает на разговор об утилите.
    услуга
    <CONVERSATION_EXPIRATION_TIMESTAMP>
    Нить
    Временная метка Unix, указывающая, когда завершится диалог.
    Свойство expiration_timestamp включается только для  "отправлено" .
    1744434060
    <CONVERSATION_ID>
    Нить
    Версия 24.0 и выше:
    Объект диалога будет полностью опущен, за исключением случаев, когда веб-хук предназначен для сообщения, отправленного в открытом окне свободной точки входа, в этом случае значение будет уникальным для каждого окна.
    Версия 23.0 и ниже:
    Теперь для каждого сообщения будет присваиваться уникальный идентификатор, за исключением случаев, когда веб-хук предназначен для сообщения, отправленного с открытым окном свободной точки входа; в этом случае значение будет уникальным для каждого окна.
    8f842dbba350821654c9dfed31f5635c
    <ERROR_CODE>
    Целое число
    131050
    <ERROR_CODES_URL>
    Нить
    /docs/whatsapp/cloud-api/support/error-codes/
    <ERROR_DETAILS>
    Нить
    Для поддержания здорового взаимодействия в экосистеме сообщение не было донесено должным образом.
    <ERROR_MESSAGE>
    Нить
     об ошибке . Это значение совпадает со  title .
    Это сообщение было отправлено не для поддержания здорового взаимодействия в рамках экосистемы.
    <ERROR_TITLE>
    Нить
    Код ошибки (заголовок). Это значение совпадает со  сообщения .
    Это сообщение было отправлено не для поддержания здорового взаимодействия в рамках экосистемы.
    <GROUP_PARTICIPANT_USER_PHONE_NUMBER>
    Нить
    Номер телефона пользователя WhatsApp. Информация о товаре указывается только в том случае, если сообщение было отправлено в группу .
    16505551234
    <IDENTITY_KEY_HASH>
    Нить
    Хэш ключа идентификации. Включается только в том случае, если включена  проверки изменений идентификатора .
    DF2lS5v2W6x=
    <IS_BILLABLE?>
    Логический
    Указывает, является ли сообщение платным ( true ) или нет ( false ).
    Обратите внимание, что  "платно" будет устаревшим в будущих версиях, поэтому мы рекомендуем начать использовать свойства "ценообразование" и "ценообразование" вместе, чтобы определить, является ли сообщение платным, и если да, то каков его тариф.
    истинный
    <PRICING_CATEGORY>
    Нить
     категория ценообразования ( тариф ), если оплата производится по счету. Возможные значения:
    Аутентификация — указывает применяемый уровень аутентификации.
    authentication-international — Указывает применяемый тариф аутентификации по международному тарифу.
    маркетинг — указывает на примененную маркетинговую ставку.
    marketing_lite — Указывает  Marketing Messages API для WhatsApp .
    referral_conversion — Указывает на бесплатную точку входа в диалог .
    сервис – указывает применяемый тариф за обслуживание.
    Показатель коммунальных услуг — указывает применяемый тариф на коммунальные услуги.
    услуга
    <PRICING_MODEL>
    Нить
    Модель ценообразования. Возможные значения:
    CBP — Указывает на применение ценообразования, основанного на диалоге. Это значение будет установлено только в том случае, если веб-хук был отправлен до 1 июля 2025 года.
    PMP — Обозначает, что  тарификация за сообщение .
    ПМП
    <PRICING_TYPE>
    Нить
    Тип ценообразования.
    обычный — указывает на то, что сообщение является платным.
    free_customer_service — Указывает, что сообщение является бесплатным, поскольку оно было либо шаблонным сообщением, либо сообщением без шаблона, отправленным в рамках окна обслуживания клиентов.
    free_entry_point — Указывает, что сообщение является бесплатным, поскольку оно было отправлено в течение открытого окна свободной точки входа.
    обычный
    <STATUS>
    Нить
    Статус сообщения. Возможные значения:
    Доставлено — указывает на то, что сообщение было успешно доставлено на устройство пользователя WhatsApp.
      Аналог в пользовательском интерфейсе WhatsApp: две галочки.
      Ошибка — указывает на невозможность отправки или доставки сообщения на устройство пользователя WhatsApp.
        Аналог пользовательского интерфейса WhatsApp: красный треугольник ошибки.
        Воспроизведено — указывает на первое воспроизведение голосового сообщения на устройстве пользователя WhatsApp.
          Аналог интерфейса WhatsApp: синий микрофон.
          Прочитано — указывает на то, что сообщение было отображено в открытом чате на устройстве пользователя WhatsApp.
            Аналогично в пользовательском интерфейсе WhatsApp: две синие галочки.
            отправлено — указывает на то, что сообщение было успешно отправлено с наших серверов.
              Аналогично пользовательскому интерфейсу WhatsApp: одна галочка.
              читать
              <USER_PHONE_NUMBER_OR_GROUP_ID>
              Нить
              Номер телефона пользователя WhatsApp или идентификатор группы.
              Если сообщение было отправлено на номер телефона пользователя WhatsApp, значение устанавливается равным номеру телефона пользователя, если сообщение было отправлено на этот номер, или равным идентификатору группы , если сообщение было отправлено на идентификатор группы. Если сообщение было отправлено на идентификатор группы, номер телефона пользователя WhatsApp присваивается свойству recipient_participant_id .
              16505551234
              <WEBHOOK_TRIGGER_TIMESTAMP>
              Нить
              Временная метка Unix, указывающая на момент срабатывания веб-перехватчика.
              1739321024
              <WHATSAPP_BUSINESS_ACCOUNT_ID>
              Нить
              Идентификатор бизнес-аккаунта WhatsApp.
              102290129340398
              <WHATSAPP_MESSAGE_ID>
              Нить
              Идентификатор сообщения WhatsApp.
              wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=
              Примеры
              В этом примере веб-перехватчика описывается маркетинговое сообщение, успешно отправленное с наших серверов.
              { "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "statuses": [ { "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=", "status": "sent", "timestamp": "1750030073", "recipient_id": "16505551234", "conversation": { "id": "72b14d6bd5407799e66f64d1b338e567", "expiration_timestamp": "1750116480", "origin": { "type": "marketing" } }, "pricing": { "billable": true, "pricing_model": "PMP", "type": "regular", "category": "marketing" } } ] }, "field": "messages" } ] } ] }
              В этом примере веб-хук версии 24.0 описывает маркетинговое сообщение, которое было отображено в клиенте WhatsApp (т.е. «прочитано»). Обратите внимание, что в данном случае  «диалог» опущен, поскольку это веб-хук версии 24.0, а  «цена» опущен, поскольку он был отображен в связанном веб-хуке для сообщений о статусе доставки (объект может отображаться только в одном из них).
              { "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "statuses": [ { "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=", "status": "sent", "timestamp": "1750030073", "recipient_id": "16505551234" } ] }, "field": "messages" } ] } ] }
              В этом примере описывается сообщение, которое не удалось отправить.
              { "object": "whatsapp_business_account", "entry": [ { "id": "102290129340398", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" }, "statuses": [ { "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA", "status": "failed", "timestamp": "1751142888", "recipient_id": "16505551234", "errors": [ { "code": 131049, "title": "Это сообщение не было "Доставлено для поддержания здорового взаимодействия в экосистеме."", "message": "Это сообщение не было доставлено для поддержания здорового взаимодействия в экосистеме."", "error_data": { "details": "Для поддержания здорового взаимодействия в экосистеме сообщение не было доставлено." }, "href": "/documentation/business-messaging/whatsapp/support/error-codes" } ] } ] }, "field": "messages" } ] } ] }
              
    
                      
              
        
              
    
              
        
              
            
              
                
                
              
                    
                    
                
              
            
              
            
            
              
                                            
              
        
              
    
              

    

              
    
              

    
            
              
            
              

    
              
        
              
            
             
         
              
            
              

    
              
        
              
                    
              

        
              Комментарии отсутствуют
              

            
              

    

    

                          
              
        
              
                
              
        
              
    
              

    
              

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