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

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

Что это такое

Обработка событий синхронизации сообщений, отправленных через WhatsApp Business App.

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

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

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

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

Запрос

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

Ответ

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

HTTP/1.1 200 OK

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

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

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

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

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

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

Исходящее сообщение с изображением

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

Содержит ранее отправленное изображение.

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

Для удобства получателя к image.link можно получить прямой доступ в течение нескольких минут, однако для скачивания этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

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

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

Содержит ранее отправленное видео.

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "video",
    "video": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "video/mp4"
    }
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

Для удобства получателя к video.link можно получить прямой доступ в течение нескольких минут, однако для скачивания этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

Исходящее аудиосообщение

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

Содержит ранее отправленное аудио.

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "audio",
    "audio": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "audio/ogg; codecs=opus"
    }
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

Для удобства получателя к audio.link можно получить прямой доступ в течение нескольких минут, однако для скачивания этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

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

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

Содержит ранее отправленный документ.

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "document",
    "document": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "caption": "图片",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'

Ответ

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

HTTP/1.1 200 OK

Объяснение

Для удобства получателя к document.link можно получить прямой доступ в течение нескольких минут, однако для скачивания этого файла в течение 30 дней всегда следует передавать заголовок X-API-Key.

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

Руководства

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

Webhooks

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

Что это такое

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

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

Запрос

Ответ

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

Запрос

Ответ

Объяснение

Исходящее сообщение с изображением

Запрос

Ответ

Объяснение

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

Запрос

Ответ

Объяснение

Исходящее аудиосообщение

Запрос

Ответ

Объяснение

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

Запрос

Ответ

Объяснение

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

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

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

​Запрос

​Ответ

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

​Запрос

​Ответ

​Объяснение

​Исходящее сообщение с изображением

​Запрос

​Ответ

​Объяснение

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

​Запрос

​Ответ

​Объяснение

​

​Исходящее аудиосообщение

​Запрос

​Ответ

​Объяснение

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

​Запрос

​Ответ

​Объяснение

Что это такое

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

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

Запрос

Ответ

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

Запрос

Ответ

Объяснение

Исходящее сообщение с изображением

Запрос

Ответ

Объяснение

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

Запрос

Ответ

Объяснение

Исходящее аудиосообщение

Запрос

Ответ

Объяснение

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

Запрос

Ответ

Объяснение