Полный каталог, сформированный на основе схемы, см. в разделе все примеры.
Что это такое
Обработка обновлений сообщений для WhatsApp, Messenger, Email, SMS и Voice.Перед началом работы
- Создайте общедоступный эндпоинт HTTPS в своем приложении.
- Настройте эндпоинт Webhook в YCloud для необходимых типов событий.
- Обеспечьте безопасное хранение секрета подписи эндпоинта.
- Сделайте обработку событий идемпотентной.
Как это работает
YCloud отправляет HTTP-запросPOST при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ 2xx и выполняйте длительные операции асинхронно.
Запрос
Ниже приведены сценарии запросов, доставляемых на ваш URL-адрес Webhook. Используйте событиеid как идентификатор доставки, а type — для маршрутизации полезной нагрузки.
Ответ
После принятия события верните статус2xx.
Сведения о настройке эндпоинта, проверке подписи и логике повторных попыток см. в разделе Настройка Webhook.
accepted. Обновления статуса сообщений запускают Webhook whatsapp.message.updated.
Как правило, статус сообщения:
- Переходит в
failed, если нам не удается доставить это сообщение. - Переходит в
sent, если доставить это сообщение возможно, а затем может измениться наfailed,deliveredилиread. - Переходит в
deliveredилиread, если сообщение было доставлено на устройство получателя.
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 по исходному телу запроса перед возвратом успешного ответа.
