> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

<Note>Полный каталог на основе схем приведен в разделе [Все примеры](/ru/api-reference/guides/examples/webhook-examples/webhook-payload-examples).</Note>

## Что это такое

Обработка событий синхронизации истории 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

<Note>Информацию о настройке эндпоинта, проверке подписи и логике повторных попыток см. в разделе [Настройка Webhook](/ru/api-reference/guides/api-fundamentals/configure-webhooks).</Note>

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

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

* Содержит обычный текст, отправленный пользователем.
* Содержит информацию об упомянутом сообщении в `context`.
* Для других типов сообщений см. [whatsappInboundMessage](/ru/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples)

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Объяснение

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

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

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

* Содержит отправленный ранее обычный текст.
* Содержит информацию об упомянутом сообщении в `context`.
* Для других типов сообщений см. [Примеры Webhook синхронизации отправленных сообщений WhatsApp Business App](/ru/api-reference/guides/examples/webhook-examples/whatsapp-business-app-sent-message-sync-webhook-examples)

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Объяснение

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

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

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

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Объяснение

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.