Примеры Webhook для статусов сообщений

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

Что это такое

Обработка обновлений сообщений для WhatsApp, Messenger, Email, SMS и голосовых сообщений.

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

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

Принцип работы

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

Запрос

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

Ответ

После принятия события верните статус 2xx.

HTTP/1.1 200 OK

Сведения о настройке конечной точки, проверке подписи и логике повторных попыток см. в разделе Настройка Webhook.

Для WhatsApp после успешного отправления запроса к API на отправку сообщений они получают статус accepted. Обновления статуса сообщения будут вызывать Webhook whatsapp.message.updated. Обычно статус сообщения:

Изменяется на failed, если нам не удается доставить это сообщение.
Изменяется на sent, если доставить это сообщение возможно, а позже может измениться на failed, delivered или read.
Изменяется на delivered или read, если это сообщение было доставлено на устройство получателя.

Однако фактическая ситуация сложнее. Во-первых, мы не гарантируем порядок уведомлений Webhook, особенно если события происходят практически одновременно. Во-вторых, события delivered могут происходить после failed и наоборот, особенно если конечный пользователь использует несколько устройств.

Сообщение отправлено

В этом случае ваша конечная точка Webhook получила событие сообщения sent:

Параметр status сообщения имеет значение sent, что означает, что сообщение находится в процессе передачи в системах WhatsApp.
Содержит информацию о переписке, включая время истечения срока действия переписки и исходный тип.
Содержит предварительные значения pricingCategory и totalPrice, которые могут быть списаны.
Содержит wamid — исходный идентификатор сообщения на платформе WhatsApp, начинающийся с wamid..

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M."
    },
    "status": "sent",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Ответ

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

HTTP/1.1 200 OK

Пояснение

totalPrice является лишь предварительной ценой до доставки первого сообщения и становится окончательной ценой, когда status принимает значение delivered или read. Баланс, зарезервированный под отправленные, но еще не доставленные сообщения, будет недоступен до тех пор, пока сообщения не будут аннулированы (отправленные сообщения, которые не были доставлены в течение 30 дней, аннулируются).
Как правило, сообщение со статусом sent вскоре переходит в статус delivered или read, за исключением следующих случаев:
- Аккаунт WhatsApp получателя находится не в сети; ваши отправленные сообщения WhatsApp не будут доставлены, пока у получателя не появится работающее или активное подключение к интернету.
- Любое сообщение, отправленное заблокировавшему вас контакту, всегда будет иметь статус sent и никогда не изменится на delivered.
- Получатель отключил отчеты о прочтении, поэтому вы не получите отчеты о статусе read.
- Сообщение позже переходит в статус failed с кодом ошибки 131026, что означает «Message Undeliverable.» («Невозможно доставить сообщение») или «Receiver is incapable of receiving this message» («Получатель не может принять это сообщение»). Скорее всего, получатель не зарегистрирован или использует устаревшую версию WhatsApp.
- Сообщение не было доставлено для обеспечения высокого качества взаимодействия с пользователем. См. раздел Ограничения маркетинговых сообщений по шаблону на пользователя.

Сообщение доставлено

В этом случае ваша конечная точка Webhook получила событие сообщения delivered:

Параметр status сообщения имеет значение delivered, что означает, что сообщение было доставлено на устройство получателя.

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Ответ

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

HTTP/1.1 200 OK

Пояснение

Это событие указывает на то, что сообщение, отправленное вашей компанией, было доставлено на устройство пользователя.
Чтобы статус стал read, он обязательно должен был быть delivered. В некоторых сценариях, например, когда пользователь находится на экране чата и поступает сообщение, оно переходит в статусы delivered и read практически одновременно. В этом и подобных сценариях уведомление delivered отправляться не будет, так как факт прочтения сообщения подразумевает, что оно было доставлено. Причиной такого поведения является внутренняя оптимизация.
Мы можем сгенерировать более одного события Webhook delivered для одного и того же сообщения, особенно если конечный пользователь использует несколько устройств.
pricingModel: «PMP» — указывает, что применяется тарификация за каждое сообщение. См. также whatsapp-message-pricing-updates
pricingType
- regular — указывает, что сообщение подлежит оплате.
- free_customer_service — указывает, что сообщение бесплатно, так как оно либо являлось сервисным шаблонным сообщением, либо нешаблонным сообщением, отправленным в рамках окна обслуживания клиентов.
- free_entry_point — указывает, что сообщение бесплатно, так как оно является частью переписки из бесплатной точки входа.

Сообщение прочитано

В этом случае ваша конечная точка Webhook получила событие сообщения read:

Поле status сообщения имеет значение read, что означает, что сообщение было прочитано получателем.

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "read",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "readTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

Если получатель отключил отчёты о прочтении, вы не получите уведомления read для сообщения.

Сбой доставки сообщения

В этом случае ваша конечная точка Webhook получила событие сообщения failed:

Поле status сообщения имеет значение failed.
Содержит errroCode, errorMessage и whatsappApiError.

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "status": "failed",
    "errorCode": "100",
    "errorMessage": "Parameter Invalid",
    "whatsappApiError": {
      "message": "(#100) Invalid parameter",
      "type": "OAuthException",
      "code": "100",
      "fbtrace_id": "AwmiSOCojlAkqvjCTjGt37r",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Parameter Invalid"
      }
    },
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

Эти события предназначены для уведомления об изменениях статуса исходящих сообщений, ранее отправленных клиентам.
Причиной сбоя отправки обычно являются неверные параметры запроса сообщения, незарегистрированный номер телефона клиента и т. д. Дополнительные сведения об обработке ошибок см. в разделе Ошибки WhatsApp.
Поле whatsappApiError предоставляется, если мы пытались отправить это сообщение на платформу WhatsApp компании Meta, чтобы помочь вам разобраться в деталях ошибки. См. также Коды ошибок Cloud API.
Плата за недоставленные сообщения не взимается.

Обновление статуса доставки Email

Используйте email.delivery.updated, когда статус доставки электронного письма меняется на delivered или failed.

Запрос

{
  "id": "evt_example_email_delivery_updated",
  "type": "email.delivery.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "emailDelivery": {
    "emailId": "email_12345678",
    "recipientAddress": "customer@example.com",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Ответ

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

HTTP/1.1 200 OK

Объяснение

Сопоставьте доставку с помощью emailId и recipientAddress: статус относится к этому получателю. Используйте externalId (при наличии) для сопоставления с вашей собственной записью. Проверьте errorCode и errorMessage в случае неудачной доставки. Свойство полезной нагрузки — emailDelivery, а не whatsappMessage.

Обновление статуса доставки SMS

Используйте sms.message.updated, когда статус доставки SMS меняется на delivered или undelivered.

Запрос

{
  "id": "evt_example_sms_message_updated",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "sms": {
    "id": "sms_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Ответ

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

HTTP/1.1 200 OK

Объяснение

Идентифицируйте SMS с помощью sms.id и прочитайте sms.status. Проверьте errorCode в случае неудачной доставки. Для отрицательного отчёта о доставке в SMS используется undelivered; не применяйте модель статусов WhatsApp read к этому событию.

Обновление статуса голосовой доставки

Используйте voice.message.updated, когда статус голосового сообщения меняется на delivered или undelivered.

Запрос

{
  "id": "evt_example_voice_message_updated",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "voice": {
    "id": "voice_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "verification_123"
  }
}

Ответ

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

HTTP/1.1 200 OK

Объяснение

Идентифицируйте голосовое сообщение с помощью voice.id и прочитайте voice.status. Проверьте errorCode (при наличии). Это событие доставки относится к Voice messaging API; оно отделено от событий жизненного цикла WhatsApp Calling.

Снимок статуса прочтения исходящего сообщения Messenger

Подпишитесь на messenger.message.updated для получения сохранённых снимков обычных индивидуальных исходящих сообщений. При повторной попытке доставки сохраняется Event.id; повторное создание события из того же исходного факта может привести к созданию нового Event.id. Сопоставляйте обновления по messengerMessage.id.

Состояния отправки и получения

accepted означает, что Meta приняла отправку, а не то, что сообщение было sent или delivered. rejected является окончательным отклонением отправки; unknown — это неподтверждённый результат, который нельзя рассматривать как сбой. Не отправляйте сообщение повторно автоматически после истечения времени ожидания или результата unknown. Проверьте его сохранённый статус с помощью возвращённого ID сообщения (если доступен) или обратитесь в службу поддержки. Снимок сохраняет текущие зафиксированные факты, при этом read имеет приоритет над delivered, sent и результатом отправки. Запоздалые подтверждения не понижают это состояние. Вы можете получать повторные снимки или пропускать промежуточные состояния. Используйте GET /v2/messenger/messages/{id} с from или выполните запрос по подтверждённому ID сообщения Meta для согласования текущего сохранённого состояния. Уведомления о результатах отправки доставляются по мере возможности (best effort). Не полагайтесь на получение Webhook для каждого синхронного результата отправки. Необязательные идентификаторы, errorCode и время получения опускаются, если они недоступны. Сохранённая ошибка отправки может оставаться, даже если последующие факты получения устанавливают более сильное состояние.

Запрос

{
  "id": "evt_89abcdef0123456789abcdef",
  "type": "messenger.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:03.000Z",
  "messengerMessage": {
    "id": "1308528868252065792",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "from": "422500000000000",
    "to": "100800000000000",
    "type": "text",
    "text": {
      "body": "How can I help you?"
    },
    "status": "read",
    "createTime": "2026-10-20T02:00:00.000Z",
    "updateTime": "2026-10-20T02:00:03.000Z",
    "readTime": "2026-10-20T02:00:03.000Z"
  }
}

Ответ

HTTP/1.1 200 OK

Объяснение

ID страницы Facebook — from, а PSID клиента — to. В этом примере показано сохранённое состояние read без домысливания недостающих sendTime или deliverTime. id — это ID сообщения YCloud, а metaMessageId — идентификатор провайдера.

Реакция на сообщение в Messenger

Запрос

{
  "id": "evt_abcdef0123456789abcdef01",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:04.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "react",
    "reaction": "love",
    "emoji": "❤️"
  }
}

Ответ

HTTP/1.1 200 OK

Объяснение

Используйте pageId и psid для идентификации переписки, а metaMessageId — для идентификации целевого сообщения. Реакция является взаимодействием и не меняет статус доставки. Для целевого сообщения может отсутствовать локальная запись сообщения YCloud. Сохраняйте исходный createTime; возможна повторная доставка. Проверьте YCloud-Signature по необработанному телу запроса перед возвратом успешного ответа.

Реакция на сообщение в Messenger удалена

Запрос

{
  "id": "evt_bcdef0123456789abcdef012",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:05.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "unreact"
  }
}

Ответ

HTTP/1.1 200 OK

Пояснение

Удалите реакцию, связанную с этой Страницей, PSID клиента и целевым сообщением Meta. unreact может опускать reaction и emoji. Не требуйте наличия локального ID сообщения и не делайте вывод об изменении статуса сообщения. При повторных попытках доставки по HTTP сохраняются тот же ID события и тело запроса; повторные обратные вызовы от источника могут создавать новый ID события. Проверьте YCloud-Signature по необработанному телу запроса перед возвратом успешного ответа.

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

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

​Принцип работы

​Запрос

​Ответ

​Сообщение отправлено

​Запрос

​Ответ

​Пояснение

​Сообщение доставлено

​Запрос

​Ответ

​Пояснение

​Сообщение прочитано

​Запрос

​Ответ

​Объяснение

​Сбой доставки сообщения

​Запрос

​Ответ

​Объяснение

​Обновление статуса доставки Email

​Запрос

​Ответ

​Объяснение

​Обновление статуса доставки SMS

​Запрос

​Ответ

​Объяснение

​Обновление статуса голосовой доставки

​Запрос

​Ответ

​Объяснение

​Снимок статуса прочтения исходящего сообщения Messenger

​Состояния отправки и получения

​Запрос

​Ответ

​Объяснение

​Реакция на сообщение в Messenger

​Запрос

​Ответ

​Объяснение

​Реакция на сообщение в Messenger удалена

​Запрос

​Ответ

​Пояснение

Что это такое

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

Принцип работы

Запрос

Ответ

Сообщение отправлено

Запрос

Ответ

Пояснение

Сообщение доставлено

Запрос

Ответ

Пояснение

Сообщение прочитано

Запрос

Ответ

Объяснение

Сбой доставки сообщения

Запрос

Ответ

Объяснение

Обновление статуса доставки Email

Запрос

Ответ

Объяснение

Обновление статуса доставки SMS

Запрос

Ответ

Объяснение

Обновление статуса голосовой доставки

Запрос

Ответ

Объяснение

Снимок статуса прочтения исходящего сообщения Messenger

Состояния отправки и получения

Запрос

Ответ

Объяснение

Реакция на сообщение в Messenger

Запрос

Ответ

Объяснение

Реакция на сообщение в Messenger удалена

Запрос

Ответ

Пояснение