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

Что это такое

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

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

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

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

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

Запрос

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

Ответ

После принятия события верните статус 2xx.
Сведения о настройке эндпоинта, проверке подписи и логике повторных попыток см. в разделе Настройка Webhook.
Для WhatsApp после успешного обращения к API для отправки сообщений сообщения получают статус accepted. Обновления статуса сообщений запускают Webhook whatsapp.message.updated. Как правило, статус сообщения:
  • Переходит в failed, если нам не удается доставить это сообщение.
  • Переходит в sent, если доставить это сообщение возможно, а затем может измениться на failed, delivered или read.
  • Переходит в delivered или read, если сообщение было доставлено на устройство получателя.
Однако реальная ситуация устроена сложнее. Во-первых, мы не гарантируем порядок уведомлений Webhook, особенно если события происходят практически одновременно. Во-вторых, события delivered могут поступать после failed и наоборот, особенно если конечный пользователь использует несколько устройств.

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

Используйте обновление статуса доставленного сообщения для сверки окончательной платы за маркетинговое сообщение Max Price.

Запрос

Ответ

Верните ответ 2xx после надежного сохранения события.

Пояснение

bidPricingFlag: true и pricingCategory: marketing_lite_bidding определяют режим назначения ставок. При delivered или read используйте totalPrice и currency для определения окончательной суммы списания. Настроенное значение maxBid является предельным уровнем цены; сумма, указанная при accepted или sent, является оценочной. Примеры настройки и множителей см. в руководстве по интеграции Max Price.

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

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

Запрос

Ответ

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

Пояснение

  • 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, что означает, что сообщение было доставлено на устройство получателя.

Запрос

Ответ

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

Пояснение

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

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

В этом случае ваша конечная точка Webhook получила событие сообщения read:
  • Сообщение status имеет значение read, что означает, что сообщение было прочитано получателем.

Запрос

Ответ

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

Пояснение

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

Ошибка отправки сообщения

В этом случае ваша конечная точка Webhook получила событие сообщения failed:
  • Сообщение status имеет значение failed.
  • Содержит errroCode, errorMessage и whatsappApiError.

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

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

Запрос

Ответ

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

Пояснение

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

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

Подпишитесь на messenger.message.updated для получения сохраненных обычных снимков индивидуальных (one-to-one) исходящих сообщений. Повторная попытка доставки сохраняет 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). Не полагайтесь на получение вебхука для каждого результата синхронной отправки. Необязательные идентификаторы, errorCode и время получения опускаются, если они недоступны. Сохраненная ошибка отправки может оставаться даже после того, как последующие данные о получении установят более определенное состояние.

Запрос

Ответ

Пояснение

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

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

Запрос

Ответ

Пояснение

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

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

Запрос

Ответ

Пояснение

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