> ## 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, Messenger и SMS, а также маркетинговых предпочтений WhatsApp.

> [!NOTE]
>
> Полный каталог на основе схемы приведен в разделе [все примеры](https://docs.ycloud.com/ru/api-reference/guides/examples/webhook-examples/webhook-payload-examples).

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

Обработка входящих сообщений WhatsApp, Messenger и SMS, а также маркетинговых предпочтений WhatsApp.

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

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

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

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

## Request

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

## Response

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

> [!NOTE]
>
> Сведения о настройке конечной точки, проверке подписи и механизме повторных попыток см. в разделе [Настройка Webhook](https://docs.ycloud.com/ru/api-reference/guides/api-fundamentals/configure-webhooks.md).

## Входящее неподдерживаемое сообщение

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

* `type` имеет значение `unsupported`.
* `errors` объясняет, почему сообщение не поддерживается или недоступно.
* `unsupported.type` определяет категорию сообщения, например `poll_creation`, `poll_update`, `edit` или `pin`.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f8709b741c165b4342a714",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "errors": [
       {
          "code": 131051,
          "title": "Message type unknown",
          "message": "Message type unknown",
          "error_data": {
             "details": "Message type is currently not supported."
          }
       }
     ],
     "type": "unsupported",
     "unsupported": {
       "type": "poll_update"
     }
  }
}'
```

### Response

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

* Ошибка `131051` с кодом `Message type unknown` означает, что WhatsApp Cloud API не поддерживает данный тип сообщений.
* Ошибка `131060` с кодом `This message is currently unavailable.` означает, что WhatsApp не смог предоставить содержимое сообщения.
* `unsupported.type` определяет общую категорию. Оно не содержит исходного текста сообщения.
* Удобный список типов сообщений см. в разделе [Неподдерживаемые сообщения во Входящих](https://docs.ycloud.com/ru/documentation/inbox/unsupported-messages-in-inbox.md). Актуальный контракт полезной нагрузки см. в справочнике Meta [unsupported messages webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/unsupported).

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

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

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

### Request

```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.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'
```

### Response

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

## Входящее текстовое сообщение, инициированное рекламой с переходом в WhatsApp

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

* Содержит обычный текст.
* Содержит информацию о рекламе.

### Request

```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.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "referral": {
      "source_url": "https://fb.me/xxx",
      "source_type": "ad",
      "source_id": "MEDIA-ID",
      "headline": "Chat with us",
      "media_type": "image",
      "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/xxx.jpg",
      "ctwa_clid": "feRgX__yiYtsI1HhjI2FRjyKInYlrU9cm9ml-Yl1MXp_fJy6Mwp-adZ-yLqOWX5CiZJYtjQERgKbAUetcwFXb_6FUYyOl9Kc6HFOBCd"
    }
  }
}'
```

### Response

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

* Поле `referral` содержит информацию о рекламе. См. также [Ads that Click to WhatsApp](https://www.facebook.com/business/help/447934475640650).

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

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

* Содержит URL изображения.
* Содержит подпись с описанием этого изображения.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkv5wsCJItpaH01",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87878509703399f3fd3d0",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/592623615738103?sig=t%3D1677228150%2Cs%3D0aa4810392602afb2a91e28e54223c4c0e638bba298f19f07a6c3a2ccf6bdf1e&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODc4Nzg1MDk3MDMzOTlmM2ZkM2QwIiwibWltZVR5cGUiOiJpbWFnZS9qcGVnIiwic2hhMjU2IjoiTGVScFFKcS9oNEhUam1QOHNtRkpRRXdZQm5rR0JVdDFjeDRxekZjblVoUT0ifQ",
      "caption": "Go for a walk.",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=",
      "mime_type": "image/jpeg"
    }
  }
}'
```

### Response

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

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

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

* Содержит URL видео.
* Содержит подпись с описанием этого видео.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkwhYtqMPmYdsN3",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87991741c165b4342a797",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "video",
    "video": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/919306472440541?sig=t%3D1677228430%2Cs%3D481b972ebc10e6b384f11274ba59e64b8c355543ea0b30e066b209361212abad&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODc5OTE3NDFjMTY1YjQzNDJhNzk3IiwibWltZVR5cGUiOiJ2aWRlby9tcDQiLCJzaGEyNTYiOiJ4RHpyU1R1YnZURm53MytzMVdJbEFiSUZLanpBS2k1dFZWaVFOVjhKV3BnPSJ9",
      "caption": "Go for a walk.",
      "id": "919306472440541",
      "sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=",
      "mime_type": "video/mp4"
    }
  }
}'
```

### Response

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

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

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

* Содержит URL аудиозаписи.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEl1TDAcquZUxzLn",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87cd3509703399f3fd3f2",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "audio",
    "audio": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/712063723747110?sig=t%3D1677229265%2Cs%3D5c6a65172ef8caa7bc969dacb831d6e15362fd7a5b6be7aa994aa83cdd15fc4e&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODdjZDM1MDk3MDMzOTlmM2ZkM2YyIiwibWltZVR5cGUiOiJhdWRpby9tcGVnIiwic2hhMjU2IjoiQWtSWkR5dEx5MkkxSzFkT2VMNnBRT2pZblBwcGdqdFNDTzlNUStDcnkwUT0ifQ",
      "id": "712063723747110",
      "sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=",
      "mime_type": "audio/mpeg"
    }
  }
}'
```

### Response

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

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

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

* Содержит URL документа.
* Содержит подпись с описанием этого документа.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkz3y7V6TCqgkbK",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87b2e741c165b4342a79b",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "document",
    "document": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/948915536111569?sig=t%3D1677228843%2Cs%3D6eb8b4fc2796bae9f2e95702fbbd4d211cace96bc5c934a12d97704140e47a16&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODdiMmU3NDFjMTY1YjQzNDJhNzliIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9wZGYiLCJzaGEyNTYiOiJFcHZDdHpUallkcTRleG1xc2ZHYmVpK1NUZ1h4VnFUQzJ0b2laODB2bW5rPSJ9",
      "caption": "PDF example",
      "filename": "sample.pdf",
      "id": "948915536111569",
      "sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=",
      "mime_type": "application/pdf"
    }
  }
}'
```

### Response

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

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

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

* Содержит URL стикера.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc1678741c165b4342b38e",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "sticker",
    "sticker": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/729118992174848?sig=t%3D1677465205%2Cs%3Dbc0d582e37cc701d5d090c1d11aa7eaed9b3f8e83925425a82d0aaab8b7da258&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmYzE2Nzg3NDFjMTY1YjQzNDJiMzhlIiwibWltZVR5cGUiOiJpbWFnZS93ZWJwIiwic2hhMjU2IjoiUlpFRWw1SFZXVDRTNkMwUG9PZ2pZQ1FWRFdzNWVzSU1Kc2pjRFlJODBaRT0ifQ",
      "id": "729118992174848",
      "sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=",
      "mime_type": "image/webp"
    }
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

## Входящее сообщение с геопозицией

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

* Содержит широту и долготу места.
* Содержит название, адрес и URL места.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc18ae509703399f3fe000",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "location",
    "location": {
      "latitude": 1.40435,
      "longitude": 103.79304,
      "name": "Singapore Zoo",
      "address": "80 Mandai Lake Road Singapore 72",
      "url": "https://www.zoo.com.sg"
    }
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

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

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

* Содержит один контакт с адресами, датой рождения, адресами электронной почты, именем, телефонами и другими полями контакта.
* Содержит `origin: contact_request`, если пользователь поделился контактом в ответ на сообщение с запросом контактных данных.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "street": "<ADDRESS_STREET>",
            "city": "<ADDRESS_CITY>",
            "state": "<ADDRESS_STATE>",
            "zip": "<ADDRESS_ZIP>",
            "country": "<ADDRESS_COUNTRY>",
            "country_code": "<ADDRESS_COUNTRY_CODE>",
            "type": "HOME"
          }
        ],
        "birthday": "2001-01-01",
        "emails": [
          {
            "email": "joe@example.com",
            "type": "WORK"
          }
        ],
        "name": {
          "formatted_name": "<CONTACT_FORMATTED_NAME>",
          "first_name": "<CONTACT_FIRST_NAME>",
          "last_name": "<CONTACT_LAST_NAME>",
          "middle_name": "<CONTACT_MIDDLE_NAME>",
          "suffix": "<CONTACT_SUFFIX>",
          "prefix": "<CONTACT_PREFIX>"
        },
        "org": {
          "company": "<CONTACT_ORG_COMPANY>",
          "department": "<CONTACT_ORG_DEPARTMENT>",
          "title": "<CONTACT_ORG_TITLE>"
        },
        "phones": [
          {
            "phone": "+447901614024",
            "wa_id": "447901614024",
            "type": "WORK"
          }
        ],
        "origin": "contact_request",
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

## Входящее сообщение с реакцией

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

* Содержит ID сообщения, на которое пользователь отреагировал.
* Содержит эмодзи.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgNODYxNTcwMDA3NzE0NRUCABIYIEYyMzY3OUJBMzY2RkFFQkRDQjYyQ0Q5RDE1QjA2RUYyAA==",
      "emoji": "👍"
    }
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

* Поле `emoji` присутствует, если пользователь отреагировал на сообщение с помощью эмодзи. Его отсутствие указывает на то, что пользователь удалил эмодзи из сообщения.

## Входящее сообщение с кнопкой шаблона

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

* Содержит `text` кнопки шаблона, который использовался при отправке шаблонного сообщения.
* Содержит `payload` кнопки, переданный вами при отправке шаблонного сообщения.
* Содержит wamid (`context.wamid`) отправленного вами шаблонного сообщения.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "button",
    "button": {
      "payload": "more_about_marketing_friday",
      "text": "Learn more"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

## Входящее интерактивное сообщение с ответом из списка

В этом случае ваша конечная точка Webhook получила входящее интерактивное сообщение с ответом из списка (Interactive List Reply):

* Поле `interactive` содержит ответ из списка, выбранный пользователем в ранее отправленном вами интерактивном сообщении.
* Поле `context` содержит информацию об интерактивном сообщении, ранее отправленном вами пользователю.

![](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaging-interactivelist-select.png) Нажмите кнопку, чтобы выбрать один элемент.

![](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-inboundmessage-listreply.png) Получатель отвечает на ваше сообщение, выбирая один из элементов в ранее отправленном вами интерактивном сообщении.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f73942741c165b43429f86",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "list_reply",
      "list_reply": {
        "id": "<LIST_SECTION_2_ROW_1_ID>",
        "title": "<SECTION_2_ROW_1_TITLE>",
        "description": "<SECTION_2_ROW_1_DESC>"
      }
    },
    "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 получила входящее интерактивное сообщение с ответом кнопкой (Interactive Button Reply):

* Поле `interactive` содержит ответ кнопкой, которую нажал пользователь в ранее отправленном вами интерактивном сообщении.
* Поле `context` содержит информацию об интерактивном сообщении, ранее отправленном вами пользователю.

![example-inboundmessage-buttonreply.png](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-inboundmessage-buttonreply.png)

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "<UNIQUE_BUTTON_ID_2>",
        "title": "<BUTTON_TITLE_2>"
      }
    },
    "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.`.

## Входящее интерактивное сообщение с ответом из Flow

После завершения flow в чат WhatsApp будет отправлено ответное сообщение. Вы получите его так же, как и все остальные сообщения от пользователя — через Webhook сообщений. Поле `response_json` будет содержать данные, специфичные для flow.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "nfm_reply",
      "nfm_reply": {
        "name": "flow",
        "body": "Sent",
        "response_json": "{\"flow_token\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
      }
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

* `interactive.type` всегда имеет значение `nfm_reply`. `interactive.name` всегда имеет значение `flow`. `interactive.body` всегда имеет значение `Sent`.
* `interactive.response_json` — это данные, относящиеся к flow. Их структура либо определяется в JSON flow (см. [действие Complete](https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson#complete-action)), либо, если flow использует конечную точку, управляется конечной точкой (см. Final Response Payload в [Data Exchange Request](https://developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint#data_exchange_request)). Распарсите JSON-строку `interactive.response_json` в JSON-объект, типы данных значений которого могут быть различными. Обычно значениями является простой текст, за исключением следующих случаев:
  * Если значение получено из компонента [CheckboxGroup](https://developers.facebook.com/docs/whatsapp/flows/reference/components#checkbox), оно представляет собой список строк.
  * Если значение исходит от компонента [OptIn](https://developers.facebook.com/docs/whatsapp/flows/reference/components#opt), оно является логическим (boolean), то есть `true` или `false`. В настоящее время, если оно присутствует, его значение должно быть `true`, поскольку такой ключ не будет включен в `response_json`, если пользователь не дал согласие.
  * Если значение исходит от компонента [DatePicker](https://developers.facebook.com/docs/whatsapp/flows/reference/components#dp), оно представляет собой строку со значением метки времени Unix в миллисекундах, например `"1725936737548"` (т. е. 2024-09-10T02:52:17.548Z). Начиная с [Flow JSON версии 5.0](https://developers.facebook.com/docs/whatsapp/flows/changelogs#august-13th--2024-release), даты будут задаваться в формате "yyyy-MM-dd", что делает значения независимыми от часовых поясов.
* Инструкции по отправке сообщений с помощью Flow см. в разделах [Шаблонное сообщение Flow](https://docs.ycloud.com/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples.md#flow-template-message) и [Интерактивное сообщение Flow](https://docs.ycloud.com/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples.md#interactive-flow-message).

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

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

* `type` имеет значение `system`, а `system.type` — значение `user_changed_number`.
* Пользователь изменяет свой номер телефона в WhatsApp, и `wa_id` представляет собой новый идентификатор WhatsApp ID (номер телефона без префикса `+`).
* `user_id` — это новый BSUID. `previous_user_id` указывает на предыдущий BSUID, если Meta предоставляет его.
* `parent_user_id` и `previous_parent_user_id` — это необязательные родительские идентификаторы Parent BSUID, которые включаются только тогда, когда функция включена и данные предоставлены Meta. Сохраняйте исходные имена полей в snake\_case внутри `system`.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_system_number_changed_123",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "msg_system_number_changed_123",
    "wamid": "wamid.EXAMPLE_NUMBER_CHANGED",
    "wabaId": "whatsapp-business-account-id",
    "from": "+16315552222",
    "to": "+16315551111",
    "sendTime": "2026-10-10T08:00:00.000Z",
    "type": "system",
    "system": {
      "type": "user_changed_number",
      "wa_id": "16315553333",
      "user_id": "US.13491208655302741919",
      "previous_user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844831",
      "previous_parent_user_id": "US.ENT.11815799212886844830"
    }
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

## Входящее сообщение об изменении BSUID

Вы также можете получить входящее системное сообщение, в котором для `system.type` установлено значение
`user_changed_user_id`. Номер телефона пользователя может остаться неизменным или быть недоступным. Используйте `system.previous_user_id` и `system.user_id`, чтобы связать предыдущий и новый BSUID, если переданы оба значения. Поля Parent BSUID являются необязательными.

### Запрос

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_system_user_id_changed_123",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "msg_system_user_id_changed_123",
    "wamid": "wamid.EXAMPLE_USER_ID_CHANGED",
    "wabaId": "whatsapp-business-account-id",
    "to": "+16315551111",
    "sendTime": "2026-10-10T08:00:00.000Z",
    "type": "system",
    "system": {
      "type": "user_changed_user_id",
      "user_id": "US.13491208655302741919",
      "previous_user_id": "US.13491208655302741918",
      "parent_user_id": "US.ENT.11815799212886844831",
      "previous_parent_user_id": "US.ENT.11815799212886844830"
    }
  }
}
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

В этом примере `from` и `system.wa_id` опущены, так как номер телефона недоступен. Если передан параметр `wa_id`, он содержит номер телефона без ведущего символа `+`; не предполагайте автоматически, что он отличается от прежнего номера. Сохраняйте существующий номер телефона, если событие не содержит заменяющего значения.

## Входящее сообщение с заказом

В этом случае ваша конечная точка webhook получила входящее сообщение с заказом, когда клиент добавляет один или несколько товаров в корзину и оформляет заказ:

* Содержит информацию о заказанном товаре.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "order",
    "order": {
      "catalog_id": "the-catalog_id",
      "product_items": [
        {
          "product_retailer_id": "the-product-SKU-identifier",
          "quantity": "number-of-item",
          "item_price": "unitary-price-of-item",
          "currency": "price-currency"
        }
      ],
      "text": "text-message-sent-along-with-the-order"
    },
    "context": {
      "from": "16315551234",
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
    }
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

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

## Входящее сообщение с запросом информации о товаре

В этом случае ваша конечная точка webhook получила входящее текстовое сообщение, когда клиент запрашивает информацию о товаре:

* Содержит информацию о товаре.

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "Can I get this in another color?"
    },
    "context": {
      "referred_product": {
        "catalog_id": "catalog-ID",
        "product_retailer_id": "product-ID"
      }
    }
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

* Сообщение с запросом информации о товаре принимается, когда пользователь запрашивает дополнительные сведения о конкретном товаре. Оно может быть получено в двух сценариях:
  * Когда клиент отвечает на [сообщения с одним или несколькими товарами](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services/share-products).
  * Когда клиент открывает каталог компании через другую точку входа, переходит на страницу сведений о товаре и нажимает кнопку «Написать компании об этом товаре».

## Входящее сообщение запроса приветствия

Вы можете получать уведомления через webhook каждый раз, когда пользователь WhatsApp впервые открывает чат с вами. Это полезно, если вы хотите отправлять таким пользователям специальное приветственное сообщение собственного дизайна.

Если эта функция включена и пользователь открывает чат (как правило, нажимая [универсальную ссылку](https://faq.whatsapp.com/425247423114725) — ссылки формата **wa.me** или **api.whatsapp.com** ), клиент WhatsApp проверяет наличие существующей переписки между пользователем и номером телефона вашей компании. Если переписка отсутствует, клиент активирует webhook `request_welcome`. Затем вы можете отправить пользователю собственное приветственное сообщение.

![example-inboundmessage-welcomemessage](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-inboundmessage-welcomemessage.png)

### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "request_welcome"
  }
}'
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

* Чтобы включить эту функцию для номера телефона, перейдите в Meta **WhatsApp Manager** > **Номера телефонов** > **Настройки** > **Автоматизация**.
* Чтобы протестировать сообщение `request_welcome`, если у вас уже есть существующий чат с номером телефона компании, сначала необходимо удалить этот чат.
* Эта функция только инициирует входящее сообщение `request_welcome` и не отправляет никаких автоматических ответов. Отправлять ли приветственное сообщение, решаете вы.

## Входящее SMS

Используйте `sms.inbound.received`, когда пользователь отвечает на ваше SMS.

### Запрос

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_sms_inbound_received",
  "type": "sms.inbound.received",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "smsInbound": {
    "id": "sms_inbound_12345678",
    "from": "+16315552222",
    "to": "+16315551111",
    "text": "Please send the order details.",
    "sendTime": "2026-05-26T11:59:00.000Z"
  }
}
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

Считайте ответ из `smsInbound.text`. `from` — это номер телефона пользователя, `to` — ваш зарегистрированный Sender ID, а `sendTime` — время отправки сообщения. Не обрабатывайте это событие как `whatsappInboundMessage`.

## Маркетинговые предпочтения WhatsApp

Используйте `whatsapp.user.preferences`, когда пользователь WhatsApp отключает или возобновляет получение маркетинговых сообщений.

### Запрос

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_whatsapp_user_preferences",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappUserPreference": {
    "wabaId": "whatsapp-business-account-id",
    "businessPhoneNumber": "+16315551111",
    "businessPhoneId": "1234567890123456",
    "contactName": "Example customer",
    "contactPhoneNumber": "+16315552222",
    "userId": "US.13491208655302741918",
    "parentUserId": "US.ENT.11815799212886844830",
    "detail": "User requested to stop marketing messages",
    "category": "marketing_messages",
    "value": "stop",
    "timestamp": "1779796800000"
  }
}
```

### Ответ

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

Считайте `category` и `value` из `whatsappUserPreference`; в этом примере зафиксирован запрос на прекращение получения маркетинговых сообщений. Используйте бизнес-идентификаторы и предоставленные идентификаторы клиентов для сопоставления предпочтения. `parentUserId` опускается, если родительские BSUID не включены. Сохраните `detail` как пояснительный текст и сохраните переданный `timestamp`. Это специальное событие предпочтений, а не входящее сообщение чата или полезная нагрузка `contact.unsubscribe.created`.

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

Подпишитесь на `messenger.inbound_message.received` для обычных личных текстовых сообщений. Проверьте заголовок `YCloud-Signature` перед подтверждением события. Повторная попытка доставки сохраняет `Event.id`; повторное создание события из того же исходного факта может сгенерировать новый `Event.id`. Сопоставляйте повторяющиеся входящие сообщения по `messengerInboundMessage.id`.

### Запрос

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_0123456789abcdef01234567",
  "type": "messenger.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:00.000Z",
  "messengerInboundMessage": {
    "id": "1308528868252065793",
    "metaMessageId": "m_EXAMPLE_IN_001",
    "from": "100800000000000",
    "to": "422500000000000",
    "type": "text",
    "text": {
      "body": "  Hello  "
    },
    "sendTime": "2026-10-20T02:00:00.000Z",
    "createTime": "2026-10-20T02:00:00.100Z"
  }
}
```

### Ответ

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

PSID клиента — `from`, а ID страницы Facebook — `to`. Сохраняйте текст в точности, включая пробелы. `sendTime` — сохраненное время исходного события; `createTime` — время локального сохранения. Это событие передает только обычные текстовые сообщения. Повторная доставка из источника может создать еще одно событие для того же сохраненного ID сообщения.

## Редактирование входящего текстового сообщения Messenger

Подпишитесь на `messenger.inbound_message.updated`, чтобы получать актуальный текст существующего входящего сообщения. Проверьте `YCloud-Signature` перед обработкой полезной нагрузки.

### Запрос

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_cdef0123456789abcdef0123",
  "type": "messenger.inbound_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:01:00.000Z",
  "messengerInboundMessage": {
    "id": "1308528868252065793",
    "metaMessageId": "m_EXAMPLE_IN_001",
    "from": "100800000000000",
    "to": "422500000000000",
    "type": "text",
    "text": {
      "body": "  Hello, corrected  "
    },
    "sendTime": "2026-10-20T02:00:00.000Z",
    "createTime": "2026-10-20T02:00:00.100Z",
    "editCount": 2,
    "editTime": "2026-10-20T02:01:00.000Z"
  }
}
```

### Ответ

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Пояснение

Сохраняйте те же `id` и `metaMessageId` сообщения при обновлении вашей записи. Новые `text.body`, совокупное `editCount` и `editTime` описывают сохраненное изменение. `sendTime` и `createTime` сообщения сохраняют свои исходные значения; `createTime` события — это время редактирования. В неотредактированных сообщениях поля редактирования опускаются. Обновляются только существующие входящие сообщения; отсутствующие оригиналы и устаревшие версии правок не восстанавливаются. Повторные попытки доставки сохраняют ID события, но повторная обработка источником может создать новый ID события. Используйте ID сообщения и счетчик правок для обработки дубликатов и упорядочивания.


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