Примеры Webhook для сообщений из истории WhatsApp Business App

Полный каталог на основе схем приведен в разделе Все примеры.

Что это такое

Обработка событий синхронизации истории WhatsApp Business App.

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

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

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

YCloud отправляет HTTP-запрос POST при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ 2xx и выполняйте длительные задачи асинхронно. Для событий, созданных из фрагмента истории Meta, YCloud копирует phase и progress фрагмента в событие верхнего уровня. Фрагменты, содержащие сообщения, включают один объект сообщения в зависимости от направления. Если оба поля threads и errors пусты, YCloud отправляет одно событие только с информацией о прогрессе без whatsappMessage или whatsappInboundMessage. Доставка выполняется по модели at-least-once (как минимум один раз), и события могут приходить не по порядку. Выполняйте дедупликацию по id события; не используйте phase и progress в качестве уникального ключа доставки.

Запрос

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

Ответ

Возвращайте статус 2xx после успешного принятия события.

HTTP/1.1 200 OK

Информацию о настройке эндпоинта, проверке подписи и логике повторных попыток см. в разделе Настройка Webhook.

Входящее текстовое сообщение

В этом случае ваш эндпоинт Webhook получил входящее текстовое сообщение:

Содержит обычный текст, отправленный пользователем.
Содержит информацию об упомянутом сообщении в context.
Для других типов сообщений см. whatsappInboundMessage

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeWick"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

Входящие сообщения — это сообщения, отправленные клиентами на телефонные номера вашей компании.
Поле context (необязательно) содержит информацию об упомянутом сообщении, обычно используемую для ответа на предыдущее сообщение, отправленное пользователем или вашей компанией.
- context.from — это WhatsApp ID (номер телефона без префикса «+») пользователя, отправившего упомянутое сообщение.
- context.id — это исходный ID упомянутого сообщения на платформе WhatsApp, начинающийся с wamid..

Исходящее текстовое сообщение

В этом случае ваш эндпоинт Webhook получил исходящее текстовое сообщение, отправленное бизнес-клиентом пользователю WhatsApp через приложение WhatsApp Business или поддерживаемое сопряженное устройство:

Содержит отправленный ранее обычный текст.
Содержит информацию об упомянутом сообщении в context.
Для других типов сообщений см. Примеры Webhook синхронизации отправленных сообщений WhatsApp Business App

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId" : "US.13491208655302741918",
    "toParentUserId": "US.11815799212886844830",
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "context": {
      "message_id": "wamid.BgNODYxN..."
    }
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

Маршрутизируйте событие по type, дедуплицируйте его по id и передавайте медленные или потенциально сбойные задачи в асинхронный обработчик.

Фрагмент истории только с информацией о прогрессе

Если фрагмент истории Meta не содержит ни цепочек сообщений, ни ошибок, событие все равно передает свои метаданные синхронизации. Событие не содержит полезной нагрузки сообщения.

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_progressOnly73",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:02.000Z",
  "phase": 1,
  "progress": 73
}'

Ответ

HTTP/1.1 200 OK

Объяснение

В этом событии намеренно отсутствует объект сообщения WhatsApp. Продолжайте отслеживать прогресс и подтверждайте получение, как и при любой другой доставке Webhook.

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

Руководства

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

Webhooks

Примеры Webhook для сообщений из истории WhatsApp Business App

Что это такое

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

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

Запрос

Ответ

Входящее текстовое сообщение

Запрос

Ответ

Объяснение

Исходящее текстовое сообщение

Запрос

Ответ

Объяснение

Фрагмент истории только с информацией о прогрессе

Запрос

Ответ

Объяснение

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

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

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

​Запрос

​Ответ

​Входящее текстовое сообщение

​Запрос

​Ответ

​Объяснение

​Исходящее текстовое сообщение

​Запрос

​Ответ

​Объяснение

​Фрагмент истории только с информацией о прогрессе

​Запрос

​Ответ

​Объяснение

Что это такое

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

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

Запрос

Ответ

Входящее текстовое сообщение

Запрос

Ответ

Объяснение

Исходящее текстовое сообщение

Запрос

Ответ

Объяснение

Фрагмент истории только с информацией о прогрессе

Запрос

Ответ

Объяснение