WhatsApp echo message updated

Что это такое

Подпишитесь на whatsapp.echo_message.updated. Вы получаете это событие, когда YCloud обрабатывает соответствующий статус исходящего эхо-сообщения для Агента, созданного через API. Сохраняйте содержимое сообщения из события создания: обновления статуса не содержат текст сообщения и type. Обновления с ошибкой содержат сведения об исходной ошибке, если они доступны. Текущий контракт сохраняет имя события неизменным и передает изменения статуса в поле whatsappMessage, что соответствует объекту, используемому соответствующим событием создания.

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

Подключите Агента через публичный REST API.
Подпишите активную конечную точку Webhook в том же аккаунте на whatsapp.echo_message.updated.
Проверяйте YCloud-Signature по исходному телу запроса, надежно сохраняйте каждое событие и обрабатывайте его идемпотентно.

Агенты, созданные в Консоли, не отправляют этот пользовательский Webhook. Синхронизация их Входящих выполняется отдельным потоком.

Инструкции по настройке конечной точки см. в разделе Настройка вебхуков.

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

Во всех примерах используются фиктивные идентификаторы. Маршрутизируйте по внешнему свойству type и считывайте whatsappMessage, а не whatsappMetaBusinessAgent, whatsappEchoMessage или data. Выполняйте дедупликацию повторных доставок по внешнему id. Внешнее поле createTime содержит время события Webhook; вложенное поле updateTime и временные метки статусов представляют собой исходное время в формате RFC 3339.

Сопоставляйте обновления с событием создания по id или wamid в рамках вашего аккаунта и бизнес-номера.
Телефон клиента и BSUID независимы. Если исходный статус содержит одновременно recipient_id и recipient_user_id, событие включает to вместе с recipientUserId или parentRecipientUserId.
Если элемент статуса не содержит этих идентификаторов, а тот же обратный вызов включает ровно один контакт, YCloud может использовать явные wa_id и user_id этого контакта. При отсутствии контактов или наличии нескольких отсутствующие идентификаторы опускаются; они никогда не выводятся друг из друга.
from включается только тогда, когда исходный обратный вызов предоставляет корректный отображаемый номер телефона компании. Он не формируется из phoneNumberId.
Храните историю событий отдельно от текущего статуса сообщения. Запоздалое событие sent может поступить после read; зафиксируйте его, не понижая текущий статус.
Приведенный ниже пример с запоздалой отправкой относится к сообщению из примера с прочтением. Пример со сбоем относится к другому сообщению.
Повторяющиеся неизмененные статусы одинакового ранга подавляются во время обработки. Это не гарантирует доставку HTTP ровно один раз (exactly-once).
Статус, полученный до записи соответствующего эхо-сообщения, может быть повторно запрошен внутренне. Не полагайтесь на порядок доставки.
Обычные статусы сообщений, отправленных через API, используют whatsapp.message.updated, а не это событие.

Запрос

YCloud отправляет эти тела JSON в HTTP-запросах POST на настроенный вами URL Webhook.

Ответ

Возвращайте ответ 2xx после успешного сохранения каждого события. Длительные операции выполняйте асинхронно.

Эхо-сообщение доставлено

Запрос

Сопоставляйте с событием создания по id или wamid. События обновления не содержат текст и тип сообщения.

{
  "id": "evt_example_echo_delivered",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "delivered",
    "updateTime": "2026-09-09T02:00:01.000Z",
    "deliverTime": "2026-09-09T02:00:01.000Z"
  }
}

Ответ

HTTP/1.1 200 OK

Пояснение

Зафиксируйте переход в статус доставки и сохраните текст сообщения, полученный в событии создания.

Эхо-сообщение прочитано

Запрос

Сопоставляйте с событием создания по id или wamid. События обновления не содержат текст и тип сообщения.

{
  "id": "evt_example_echo_read",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "read",
    "updateTime": "2026-09-09T02:00:02.000Z",
    "readTime": "2026-09-09T02:00:02.000Z"
  }
}

Ответ

HTTP/1.1 200 OK

Пояснение

Зафиксируйте переход в статус прочтения, используя updateTime и readTime в качестве времени исходного события.

Запоздалый статус отправки после прочтения

Запрос

Исходный статус более низкого ранга может поступить после прочтения. Зафиксируйте событие, не понижая текущий статус сообщения.

{
  "id": "evt_example_echo_sent",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "sent",
    "updateTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

Ответ

HTTP/1.1 200 OK

Пояснение

Сохраните это событие в истории доставки, но не понижайте более поздний текущий статус, такой как read.

Ошибка эхо-сообщения

Запрос

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

{
  "id": "evt_example_echo_failed",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "FAILED_MESSAGE_ID",
    "wamid": "wamid.FAILED_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "failed",
    "errorCode": "131000",
    "errorMessage": "Provider failure",
    "updateTime": "2026-09-09T02:00:03.000Z"
  }
}

Ответ

HTTP/1.1 200 OK

Пояснение

Используйте errorCode и errorMessage для диагностики, когда исходный обратный вызов предоставляет их.

Начало работы

Руководства

Конечные точки

Webhooks

WhatsApp echo message updated

Что это такое

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

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

Запрос

Ответ

Эхо-сообщение доставлено

Запрос

Ответ

Пояснение

Эхо-сообщение прочитано

Запрос

Ответ

Пояснение

Запоздалый статус отправки после прочтения

Запрос

Ответ

Пояснение

Ошибка эхо-сообщения

Запрос

Ответ

Пояснение

Связанные примеры

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

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

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

​Запрос

​Ответ

​Эхо-сообщение доставлено

​Запрос

​Ответ

​Пояснение

​Эхо-сообщение прочитано

​Запрос

​Ответ

​Пояснение

​Запоздалый статус отправки после прочтения

​Запрос

​Ответ

​Пояснение

​Ошибка эхо-сообщения

​Запрос

​Ответ

​Пояснение

​Связанные примеры

Что это такое

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

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

Запрос

Ответ

Эхо-сообщение доставлено

Запрос

Ответ

Пояснение

Эхо-сообщение прочитано

Запрос

Ответ

Пояснение

Запоздалый статус отправки после прочтения

Запрос

Ответ

Пояснение

Ошибка эхо-сообщения

Запрос

Ответ

Пояснение

Связанные примеры