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

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

Что это такое

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

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

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

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

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

Запрос

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

Ответ

Верните статус 2xx после принятия события.

HTTP/1.1 200 OK

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

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

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

Запрос

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_example_smb_echoes",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "username": "example_customer"
    }
  }
}'

Ответ

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

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 можно получить напрямую в течение нескольких минут для удобства пользователя, но вам следует всегда передавать заголовок X-API-Key, чтобы скачать этот файл в течение 30 дней.

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

В этом случае ваша конечная точка 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 можно получить напрямую в течение нескольких минут для удобства пользователя, но вам следует всегда передавать заголовок X-API-Key, чтобы скачать этот файл в течение 30 дней.

Исходящее голосовое/аудиосообщение

В этом случае ваша конечная точка 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 можно получить напрямую в течение нескольких минут для удобства пользователя, но вам следует всегда передавать заголовок X-API-Key, чтобы скачать этот файл в течение 30 дней.

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

В этом случае ваша конечная точка 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 можно получить напрямую в течение нескольких минут для удобства пользователя, но вам следует всегда передавать заголовок X-API-Key, чтобы скачать этот файл в течение 30 дней.

Сообщение создано в Business App

Используйте whatsapp.smb.message.created при отправке сообщения из приложения WhatsApp Business.

Запрос

{
  "id": "evt_example_smb_created",
  "type": "whatsapp.smb.message.created",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z"
  }
}

Ответ

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

HTTP/1.1 200 OK

Пояснение

Прочитайте исходящее сообщение из whatsappMessage. Его поле type определяет объект с содержимым; в данном текстовом примере используется text.body. Маршрутизируйте это событие отдельно от whatsapp.smb.message.echoes, сохраняя общую логику парсинга сообщений там, где это применимо. Это события сосуществования Business App (coexistence), а не эхо-события Meta Business Agent.

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

Руководства

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

Webhooks

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

Что это такое

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

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

Запрос

Ответ

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

Исходящее голосовое/аудиосообщение

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

Сообщение создано в Business App

Запрос

Ответ

Пояснение

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

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

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

​Запрос

​Ответ

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

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

​

​Исходящее голосовое/аудиосообщение

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

​Сообщение создано в Business App

​Запрос

​Ответ

​Пояснение

Что это такое

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

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

Запрос

Ответ

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

Исходящее голосовое/аудиосообщение

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

Сообщение создано в Business App

Запрос

Ответ

Пояснение