Эхо-сообщение Meta Business Agent обновлено

Что это такое

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

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

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

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

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

Как это работает

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

Сопоставляйте обновления с событием создания по id или wamid в рамках вашего аккаунта и бизнес-номера.
Телефон клиента и BSUID независимы. Когда исходный статус предоставляет и recipient_id, и recipient_user_id, событие включает to вместе с recipientUserId или parentRecipientUserId.
Если в элементе статуса отсутствуют эти идентификаторы, а тот же callback содержит ровно один контакт, YCloud может использовать явные wa_id и user_id этого контакта. При нулевом или нескольких контактах отсутствующие идентификаторы остаются опущенными; они никогда не выводятся друг из друга.
from включается только тогда, когда исходный callback предоставляет действительный отображаемый номер телефона компании. Он не выводится из 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 для диагностики, если исходный callback предоставляет их.

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

Руководства

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

Webhooks

Эхо-сообщение Meta Business Agent обновлено

Что это такое

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

Как это работает

Запрос

Ответ

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

Неудачное эхо-сообщение

Запрос

Ответ

Пояснение

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

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

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

​Как это работает

​Запрос

​Ответ

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

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

​Неудачное эхо-сообщение

​Запрос

​Ответ

​Пояснение

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

Что это такое

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

Как это работает

Запрос

Ответ

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

Неудачное эхо-сообщение

Запрос

Ответ

Пояснение

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