Skip to main content

Что это такое

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

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

  1. Подключите агента через Public REST API.
  2. Подпишите активную конечную точку Webhook в том же аккаунте на whatsapp.echo_message.updated.
  3. Проверяйте YCloud-Signature по исходному телу запроса, надежно подтверждайте прием каждого события и обрабатывайте его идемпотентно.
Агенты, созданные в консоли, не отправляют этот клиентский Webhook. Синхронизация их Inbox представляет собой отдельный процесс.
Инструкции по настройке конечной точки см. в разделе Configure webhooks.

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

Во всех примерах используются подстановочные идентификаторы. Маршрутизируйте по внешнему полю 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 ровно один раз.
  • Статус, полученный до появления соответствующей эхо-записи, может быть повторно обработан внутри системы. Не полагайтесь на порядок доставки.
  • Для обычных статусов отправленных через API сообщений используется событие whatsapp.message.updated, а не это событие.

Запрос

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

Ответ

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

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

Запрос

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

Ответ

Пояснение

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

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

Запрос

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

Ответ

Пояснение

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

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

Запрос

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

Ответ

Пояснение

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

Эхо-сообщение с ошибкой

Запрос

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

Ответ

Пояснение

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

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