> ## 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

> Обработка входящих типов сообщений WhatsApp с примерами полезной нагрузки и пояснениями.

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

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

Обработка входящих типов сообщений WhatsApp с примерами полезной нагрузки и пояснениями.

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

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

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

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

## Запрос

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

## Ответ

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

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

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

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

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

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

### Запрос

```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"
     }
  }
}'
```

### Ответ

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

```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` указывает общую категорию. Поле не содержит исходного текста или контента сообщения.
* Список типов сообщений см. в разделе [Неподдерживаемые сообщения во входящих](/ru/documentation/inbox/unsupported-messages-in-inbox). Актуальный формат полезной нагрузки описан в [справочнике по вебхукам неподдерживаемых сообщений от Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/unsupported).

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

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

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

### Запрос

```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..."
    }
  }
}'
```

### Ответ

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

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

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

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

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

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

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

### Запрос

```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"
    }
  }
}'
```

### Ответ

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

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

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

* Объект `referral` содержит информацию о рекламе. См. также раздел [Реклама с переходом в WhatsApp](https://www.facebook.com/business/help/447934475640650).

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

В этом случае ваш эндпоинт 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_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"
    }
  }
}'
```

### Ответ

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

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

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

* По ссылке `image.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_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"
    }
  }
}'
```

### Ответ

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

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

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

* По ссылке `video.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_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"
    }
  }
}'
```

### Ответ

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

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

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

* По ссылке `audio.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_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"
    }
  }
}'
```

### Ответ

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

```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`.

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

В этом случае ваша конечная точка 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` и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

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

В этом случае ваша конечная точка 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` и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

## Входящее сообщение-реакция (Reaction)

В этом случае ваша конечная точка 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` присутствует, когда пользователь реагирует на сообщение с помощью эмодзи. Его отсутствие означает, что пользователь удалил эмодзи с сообщения.

## Входящее сообщение по нажатию кнопки шаблона (Template Button)

В этом случае ваша конечная точка 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` и переносите медленные или подверженные сбоям задачи в асинхронный обработчик.

## Входящее интерактивное сообщение с выбором из списка (Interactive List Reply)

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

* Поле `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.`.

## Входящее интерактивное сообщение с ответом по кнопке (Interactive Button Reply)

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

* Поле `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 (Interactive Flow Response)

После завершения 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](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#flow-template-message) и [Интерактивное сообщение Flow](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#interactive-flow-message).

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

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

* `type` имеет значение `system`, а `system.type` — `user_changed_number`.
* Пользователь меняет свой номер телефона в WhatsApp, и `wa_id` — это новый WhatsApp ID (номер телефона без префикса `+`).
* `user_id` — это новый BSUID. `parent_user_id` включается только тогда, когда включены родительские BSUID.

### Запрос

```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": "system",
    "system": {
      "body": "User A changed from 123456789 to 987654321",
      "wa_id": "987654321",
      "user_id": "US.13491208655302741919",
      "parent_user_id": "US.ENT.11815799212886844831",
      "type": "user_changed_number"
    }
  }
}'
```

### Ответ

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

```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": "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
```

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

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

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

Вы можете получать уведомления через 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` и не отправляет никаких сообщений автоматически в ответ. Отправлять ли приветственное сообщение — решать вам.

<br />


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