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

# Примеры сообщений WhatsApp

> Отправляйте шаблонные, медиа-, интерактивные, коммерческие сообщения, Flow и сообщения для звонков с примерами аннотированных запросов.

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

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

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

* Сохраните ключ API YCloud в секрете на стороне сервера.
* Подключите WhatsApp Business Account и номер телефона, используемый в запросе.
* Создайте и подтвердите любой шаблон, на который ссылается запрос на отправку сообщений.
* Замените все плейсхолдеры значениями из вашего аккаунта.

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

Выберите сценарий, соответствующий сообщению или шаблону, который вы хотите создать. Сравните его поля со Справочником по API, замените плейсхолдеры и протестируйте с контролируемым получателем перед использованием запроса в рабочей среде.

## Запрос

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

## Ответ

Успешный ответ на отправку подтверждает, что YCloud принял запрос на сообщение; используйте получение сообщений или вебхуки `whatsapp.message.updated` для определения окончательного статуса доставки.

<Note>Используйте [руководство по сообщениям WhatsApp](/ru/api-reference/guides/whatsapp-platform/send-whatsapp-message) для получения информации о жизненном цикле и Справочник по API для полной схемы.</Note>

## Выберите пример

<CardGroup cols={2}>
  <Card title="Шаблонные сообщения" icon="rectangle-list" href="#template-message-examples">
    Отправляйте одобренные шаблоны для аутентификации, маркетинга, сервисных уведомлений и сценариев электронной коммерции.
  </Card>

  <Card title="Сообщения в свободной форме" icon="message" href="#free-form-message-examples">
    Отправляйте текст, медиа, геолокацию, контакты и реакции в рамках открытого окна обслуживания клиентов.
  </Card>

  <Card title="Интерактивные сообщения" icon="list-check" href="#interactive-list-message">
    Добавляйте списки, кнопки, Flows, товары, вызовы и взаимодействия с каруселями.
  </Card>

  <Card title="Коммерческие сообщения" icon="cart-shopping" href="#interactive-order-details-message">
    Отправляйте карточки товаров, информацию о заказах, статусы заказов и сценарии оформления покупки.
  </Card>
</CardGroup>

Приведенные ниже примеры применимы как к API [Send a WhatsApp message directly](/api-reference/whatsapp-messages/send-a-message-directly), так и к API [Enqueue a WhatsApp message](/api-reference/whatsapp-messages/enqueue-a-message).

Начало работы с шаблонных сообщений — это простой способ инициировать [диалог](https://developers.facebook.com/docs/whatsapp/pricing#opening-conversations). **Как только клиент ответит на шаблонное сообщение компании, компания сможет отправлять клиенту сообщения любого типа в течение 24 часов.**

<br />

## Примеры шаблонных сообщений

Ниже приведены примеры шаблонных сообщений WhatsApp. Каждый шаблон должен быть создан и одобрен перед тем, как его можно будет использовать для отправки сообщений.

<br />

### Шаблонное сообщение аутентификации с кнопками одноразового пароля

В этом случае у вас есть **[Шаблон аутентификации с кнопкой копирования кода](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#authentication-template-with-copy-code-button)**, **[Шаблон аутентификации с кнопкой в одно касание](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#authentication-template-with-one-tap-button)** или **[Шаблон аутентификации в ноль касаний (zero-tap)](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#zero-tap-authentication-template)**, и вы отправляете шаблонное сообщение:

* Содержит одноразовый пароль или код подтверждения для доставки клиенту.
* Содержит кнопку **копирования кода** , кнопку **автозаполнения в одно касание** или вовсе не содержит кнопок при использовании **zero-tap**.

![example-messaging-otp.webp](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaging-otp.webp)

![](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-template-zerotap.webp)<br />
**<p align="center" style={{ color: '#67777F' }}>ZERO-TAP</p>**

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "otp_one_tap",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "797011"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "797011"
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Первоначальный статус `accepted` подтверждает отправку запроса, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Текст тела сообщения будет содержать код подтверждения, указанный в компоненте body. С другой стороны, код, который фактически используется при нажатии пользователем кнопок в одно касание или копирования кода, находится в компоненте button. В большинстве случаев они должны совпадать.

### Шаблонное сообщение с переменными

В этом случае у вас есть **[Сервисный шаблон с переменными в тексте](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#utility-template-with-variables-in-body)**, и вы отправляете шаблонное сообщение:

* Содержит текст с 3 переменными в теле сообщения.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "ORDER-TITLE"
          },
          {
            "type": "text",
            "text": "9.9 USD"
          },
          {
            "type": "text",
            "text": "February 25"
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Первоначальный статус `accepted` подтверждает отправку запроса, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Убедитесь, что соответствующий шаблон был одобрен.
* **Установите правильный `type` для отправляемых сообщений. В данном случае `type` имеет значение `template`, а `components` и `parameters` запроса сообщения должны соответствовать шаблону.**

### Шаблонное сообщение с изображением и кнопками быстрого ответа (Quick Reply)

В этом случае у вас есть **[Маркетинговый шаблон с изображением и кнопками быстрого ответа](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#marketing-template-with-image-and-quick-reply-buttons)**, и вы отправляете шаблонное сообщение:

* Содержит изображение в заголовке.
* Содержит текст с 1 переменной в теле сообщения.
* Содержит текст в нижнем колонтитуле.
* Содержит 2 кнопки быстрого ответа (Quick Reply). Максимальное количество кнопок быстрого ответа — 3.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "marketing_friday",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Lucy"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 0,
        "parameters": [
          {
            "type": "payload",
            "payload": "more_about_marketing_friday"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 1,
        "parameters": [
          {
            "type": "payload",
            "payload": "unsubscribe_marketing_notifications"
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Первоначальный статус `accepted` подтверждает отправку запроса, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Параметр `caption` (используемый для описания указанного медиафайла `image`, `video` или `document`) не поддерживается в сообщениях `template` или `interactive`.
* Для получения дополнительной информации об ограничениях медиафайлов в заголовке см. [Поддерживаемые типы медиа](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types).
* Используйте `payload` для отслеживания нажатий кнопок пользователями. Полезная нагрузка кнопки не видна, но будет включена при нажатии кнопки пользователем, см. также [Входящее сообщение по кнопке шаблона](/ru/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples#inbound-template-button-message).

### Шаблонное сообщение с видео и кнопками с призывом к действию

В этом случае у вас есть **[Маркетинговый шаблон с видео и кнопками с призывом к действию](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#marketing-template-with-video-and-call-to-action-buttons)**, и вы отправляете шаблонное сообщение:

* Содержит видео в заголовке.
* Содержит текст с 1 переменной в теле.
* Содержит текст в нижнем колонтитуле.
* Содержит 2 кнопки с призывом к действию: 1 кнопку `PHONE_NUMBER` и 1 кнопку `URL`. Кнопка `URL` может содержать максимум 1 переменную в конце URL.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "marketing_friday_more",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "video",
            "video": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "The Friday"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [
          {
            "type": "text",
            "text": "qptHJVK2EjU"
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* Параметр `caption` (используемый для описания указанного медиафайла `image`, `video` или `document`) не поддерживается в сообщениях `template` или `interactive`.

### Шаблонное сообщение с купоном

В этом случае у вас есть **[Шаблон с купоном](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#coupon-template)**, и вы отправляете шаблонное сообщение:

* Содержит текст с 2 переменными в теле.
* Содержит 1 кнопку копирования кода.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "marketing_coupon",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Tom"
          },
          {
            "type": "text",
            "text": "25OFF"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": 0,
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "25OFF"
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* Коды купонов ограничены 15 символами.
* Текст кнопки нельзя настроить.

### Шаблонное сообщение с геопозицией

В этом случае у вас есть **[Шаблон с геопозицией](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#location-template)**, и вы отправляете шаблонное сообщение с геопозицией:

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "location_header",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": 37.483307,
              "longitude": 122.148981,
              "name": "Pablo Morales",
              "address": "1 Hacker Way, Menlo Park, CA 94025"
            }
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* Параметры `latitude` и `longitude` являются обязательными.

### Шаблонное сообщение с ограниченным по времени предложением

В этом случае у вас есть **[Шаблон с ограниченным по времени предложением](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#limited-time-offer-template)**, и вы отправляете шаблонное сообщение с ограниченным по времени предложением (LTO):

* Содержит изображение в заголовке.
* Отображает даты окончания срока действия и таймеры обратного отсчета для кода предложения.
* Содержит текст с 2 переменными в теле.
* Содержит 2 кнопки: 1 кнопку `COPY_CODE` и 1 кнопку `URL`.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "limited_time_offer_caribbean_pkg_2023",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          }
        ]
      },
      {
        "type": "limited_time_offer",
        "parameters": [
          {
            "type": "limited_time_offer",
            "limited_time_offer": {
              "expiration_time_ms": 1698118200000
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Tom"
          },
          {
            "type": "text",
            "text": "C025"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": "0",
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "C025"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "1",
        "parameters": [
          {
            "type": "text",
            "text": "param025"
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

Сопоставьте поля запроса с выбранным типом сообщения и используйте возвращенный ID сообщения для сопоставления статусов.

### Шаблонное сообщение с каруселью

В этом случае у вас есть **[Шаблон с каруселью](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#carousel-template)**, и вы отправляете шаблонное сообщение с каруселью:

* Содержит текст с 2 переменными в теле.
* Содержит 2 карточки карусели в виде с горизонтальной прокруткой.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "summer_carousel_promo_2023",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "C015"
          },
          {
            "type": "text",
            "text": "15%"
          }
        ]
      },
      {
        "type": "carousel",
        "cards": [
          {
            "card_index": 0,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "image",
                    "image": {
                      "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
                    }
                  }
                ]
              },
              {
                "type": "body",
                "parameters": [
                  {
                    "type": "text",
                    "text": "C015"
                  },
                  {
                    "type": "text",
                    "text": "15%"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                  {
                    "type": "payload",
                    "payload": "summer_lemons_2023"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "url",
                "index": 1,
                "parameters": [
                  {
                    "type": "text",
                    "text": "summer_lemons_2023"
                  }
                ]
              }
            ]
          },
          {
            "card_index": 1,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "image",
                    "image": {
                      "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
                    }
                  }
                ]
              },
              {
                "type": "body",
                "parameters": [
                  {
                    "type": "text",
                    "text": "20OFFEXOTIC"
                  },
                  {
                    "type": "text",
                    "text": "20%"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                  {
                    "type": "payload",
                    "payload": "summer_blues_2023"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "url",
                "index": 1,
                "parameters": [
                  {
                    "type": "text",
                    "text": "summer_blues_2023"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* Пузыри сообщений поддерживают только текст и переменные. Максимального ограничения символов для переменных нет, но они учитываются в общем лимите текстового пузыря сообщения в 1024 символа.
* Текст тела карточки поддерживает переменные. Максимального ограничения символов для переменных нет, но они учитываются в лимите текста тела карточки в 160 символов.

### Шаблонное сообщение с каталогом

В этом случае у вас есть [Шаблон каталога](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#catalog-template), и вы отправляете сообщение, чтобы поделиться своим каталогом товаров с клиентами.

![example-messaging-catalog.webp](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaging-catalog.webp)

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "intro_catalog_offer",
    "language": {
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "100"
          },
          {
            "type": "text",
            "text": "400"
          },
          {
            "type": "text",
            "text": "3"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "catalog",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "thumbnail_product_retailer_id": "2lc20305pt"
            }
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* Параметр `thumbnail_product_retailer_id` является необязательным. Номер SKU обозначается как Content ID в [Commerce Manager](https://business.facebook.com/commerce/). Миниатюра этого товара будет использоваться в качестве изображения заголовка сообщения. Если объект `parameters` опущен, будет использовано изображение первого товара в вашем каталоге.

### Шаблонное сообщение MPM

В этом случае у вас есть [Шаблон MPM](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#multi-product-message-template), и вы отправляете сообщение, чтобы поделиться товарами с клиентами.

В этом примере отправляется утвержденный шаблон с именем «abandoned\_cart», а также подставляется переменная (имя клиента) в заголовок шаблона и промокод в тело шаблона. Также определяются два раздела («Popular Bundles» и «Premium Packages») и указываются товары (всего 3), которые должны быть добавлены в эти разделы.

![example-messaging-mpm.webp](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaging-mpm.webp)

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "abandoned_cart",
    "language": {
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "10OFF"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "mpm",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "thumbnail_product_retailer_id": "2lc20305pt",
              "sections": [
                {
                  "title": "Popular Bundles",
                  "product_items": [
                    {
                      "product_retailer_id": "2lc20305pt"
                    },
                    {
                      "product_retailer_id": "nseiw1x3ch"
                    }
                  ]
                },
                {
                  "title": "Premium Packages",
                  "product_items": [
                    {
                      "product_retailer_id": "n6k6x0y7oe"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Исходный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* Клиенты должны использовать WhatsApp версии 2.22.24 или выше.
* Шаблонные сообщения MPM нельзя пересылать другим клиентам.
* Когда клиент добавляет один или несколько товаров в корзину и оформляет заказ, мы отправляем вам Webhook с описанием заказа. См. также [Входящее сообщение о заказе](/ru/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples#inbound-order-message).

### Шаблонное сообщение Flow

[WhatsApp Flows](https://developers.facebook.com/docs/whatsapp/flows) — это способ построения структурированного взаимодействия в бизнес-сообщениях. С помощью Flows компании могут определять, настраивать и персонализировать сообщения с расширенными интерактивными возможностями, обеспечивая клиентам более упорядоченное общение.

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

В этом случае вы отправляете сообщение с использованием [шаблона Flow](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#flow-template):

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "flow",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "flow_token": "<FLOW_TOKEN>",
              "flow_action_data": {
                "data1": "value1"
              }
            }
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Исходный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* `flow_action_data` — это JSON-объект с полезной нагрузкой данных для первого экрана. См. также [Отправка шаблона с Flow — Платформа WhatsApp Business](https://developers.facebook.com/docs/whatsapp/flows/guides/sendingaflow#send-template-with-flow).
* Инструкции по отправке интерактивного сообщения с Flow см. в разделе [Интерактивное сообщение Flow](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#interactive-flow-message).
* Инструкции по получению ответа Flow см. в разделе [Входящее интерактивное сообщение с ответом Flow](/ru/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples#inbound-interactive-flow-response-message).

### Шаблонное сообщение с деталями заказа

Шаблонное сообщение с деталями заказа позволяет бизнесу отправлять информацию о заказе в виде предопределенных параметров компонента кнопки призыва к действию (`Open order details`). Оно поддерживает интеграцию любых платежей (таких как [UPI Intent](https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/payments-in/upi-intent), [Payment Gateway](https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/payments-in/pg) или [Payment Links](https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/payments-in/payment-links)) в качестве параметров кнопок.

Вот пример отправки Payment Gateway в параметрах шаблонного сообщения с деталями заказа для предложения клиенту произвести оплату.

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "order_details_example",
    "language": {
      "policy": "deterministic",
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "<HEADER_TEXT>",
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "order_details",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "order_details": {
                "currency": "INR",
                "order": {
                  "discount": {
                    "offset": 100,
                    "value": 250
                  },
                  "items": [
                    {
                      "amount": {
                        "offset": 100,
                        "value": 400
                      },
                      "name": "<ORDER_ITEM_NAME>",
                      "quantity": 1,
                      "retailer_id": "<ORDER_ITEM_RETAILER_ID>",
                      "country_of_origin": "<ORIGIN_COUNTRY>",
                      "importer_name": "<IMPORTER_NAME>",
                      "importer_address": {
                        "address_line1": "<IMPORTER_ADDRESS>",
                        "city": "<CITY>",
                        "country_code": "<COUNTRY>",
                        "postal_code": "<ZIP_CODE>"
                      }
                    }
                  ],
                  "shipping": {
                    "offset": 100,
                    "value": 0
                  },
                  "status": "pending",
                  "subtotal": {
                    "offset": 100,
                    "value": 400
                  },
                  "tax": {
                    "offset": 100,
                    "value": 500
                  }
                },
                "payment_settings": [
                  {
                    "type": "payment_gateway",
                    "payment_gateway": {
                      "type": "billdesk",
                      "configuration_name": "<payment-config-id>",
                      "billdesk": {
                        "additional_info1": "additional_info1-value",
                        "additional_info2": "additional_info2-value",
                        "additional_info3": "additional_info3-value",
                        "additional_info4": "additional_info4-value",
                        "additional_info5": "additional_info5-value",
                        "additional_info6": "additional_info6-value",
                        "additional_info7": "additional_info7-value",
                      }
                    }
                  }
                ],
                "reference_id": "<reference_id_value>",
                "total_amount": {
                  "offset": 100,
                  "value": 650
                },
                "type": "digital-goods"
              }
            }
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Исходный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* Чтобы узнать больше о параметрах `template`, см. также [Отправка шаблонного сообщения с деталями заказа](https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/payments-in/orderdetailstemplate#sending-order-details-template-message).
* Прежде чем отправлять шаблонные сообщения с деталями заказа, создайте [шаблон деталей заказа](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#order-details-template).
* Вы получите уведомление через Webhook, когда клиент предпримет попытку оплаты и статус платежа изменится. См. [Обновление платежной транзакции](/ru/api-reference/guides/examples/webhook-examples/whatsapp-payment-updated-webhook-examples).
* Если с момента последнего ответа клиента на ваш рабочий номер телефона прошло не более 24 часов, вместо этого можно отправить [интерактивное сообщение с деталями заказа](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#interactive-order-details-message).

### Шаблонное сообщение со статусом заказа

Шаблон статуса заказа — это один из интерактивных шаблонов сообщений, который расширяет функционал кнопки призыва к действию для поддержки обновления статуса заказа через шаблон. Он позволяет бизнесу обновлять статус заказа за пределами 24-часового окна сессии клиента в таких сценариях, как списание средств с карты за прошлый заказ или информирование об отправке ранее оформленного заказа.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "order_status_template",
    "language": {
      "policy": "deterministic",
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "order_status",
        "parameters": [
          {
            "type": "order_status",
            "order_status": {
              "reference_id": "<reference_id_value>",
              "order": {
                "status": "processing | partially_shipped | shipped | completed | canceled",
                "description": "<OPTIONAL_DESCRIPTION>"
              }
            }
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Исходный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` для сопоставления с последующими событиями `whatsapp.message.updated`.

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

* Чтобы узнать больше о параметрах `template`, см. также [Отправка шаблонного сообщения со статусом заказа](https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/payments-in/orderstatustemplate#sending-order-status-template-message).
* Прежде чем отправлять шаблонные сообщения со статусом заказа, создайте [шаблон статуса заказа](/ru/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#order-status-template).
* Если с момента последнего ответа клиента на ваш рабочий номер телефона прошло не более 24 часов, вместо этого можно отправить [интерактивное сообщение со статусом заказа](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#interactive-order-status-message).

<br />

***

<br />

## Примеры сообщений в свободной форме

Следующие примеры представляют собой сообщения в свободной форме. Для таких сообщений не требуется предварительно утвержденный шаблон, и их можно отправлять напрямую. Однако их отправка возможна только в рамках 24-часового окна обслуживания клиентов, которое отсчитывается от последнего сообщения клиента.

<br />

### Текстовое сообщение

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

* Содержит только обычный текст.
* Содержит URL и включает блок предварительного просмотра в текстовых сообщениях путем установки для `preview_url` значения `true`.
* Указывает сообщение (`context.message_id`), на которое вы отвечаете.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "text",
  "text": {
    "body": "*Learn* how to format your messages: https://faq.whatsapp.com/539178204879377",
    "preview_url": true
  },
  "context": {
    "message_id": "wamid.BgNODYxN..."
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* **Вы можете отправлять шаблонные сообщения только до того, как клиент ответит на ваше сообщение.**
* Используйте `context.message_id`, чтобы указать сообщение, на которое вы отвечаете. Обратите внимание, что это исходный ID сообщения на платформе WhatsApp, начинающийся с `wamid.`, а не ID сообщения в YCloud. `wamid` можно найти как в объекте `whatsappMessage` YCloud (когда статус меняется на `sent`), так и в объекте `whatsappInboundMessage`. Эта возможность также применима к другим типам сообщений, кроме сообщений `template` и `sticker`.
* Текст сообщения WhatsApp поддерживает форматирование текста, такое как *Курсив*, **Полужирный**, ~~Зачеркнутый~~, моноширинный шрифт, маркированный список, нумерованный список, цитату и встроенный код. См. также [**Как форматировать сообщения**](https://faq.whatsapp.com/539178204879377).

### Сообщение с изображением

В этом случае вы отправляете сообщение с изображением:

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

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "image",
  "image": {
    "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg",
    "caption": "Describes the specified media."
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Поддерживаемые типы изображений: `image/jpeg`, `image/png`. Изображения должны быть 8-битными, RGB или RGBA.
* Требуется встроенный цветовой профиль. См. также [Как встроить профиль](https://digital-photography-school.com/choose-right-color-profile-sharing-images-online/#how-to-embed-the-profile), [Встраивание цветового профиля в Adobe Photoshop](https://helpx.adobe.com/photoshop/using/working-with-color-profiles.html#Embedacolorprofile).
* Ограничение размера изображения: 5 МБ.
* См. также [Поддерживаемые типы медиафайлов](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types).

### Видеосообщение

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

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

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "video",
  "video": {
    "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4",
    "caption": "Describes the specified media."
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Поддерживаемые типы видео: `video/mp4`, `video/3gpp`.
  * Поддерживаются только видеокодек H.264 и аудиокодек AAC.
  * Поддерживаются видео с одной аудиодорожкой или без звука.
  * Формат файлов [MP4](https://en.wikipedia.org/wiki/MP4_file_format) основан на [базовом медиаформате ISO](https://en.wikipedia.org/wiki/ISO_base_media_file_format), который напрямую произошел от формата [QuickTime](https://en.wikipedia.org/wiki/QuickTime_File_Format), разработанного [Apple](https://www.apple.com). **Но видеофайлы QuickTime не поддерживаются, даже если вы изменили расширение файла с `.mov` на `.mp4`.**
* Ограничение размера видео: 16 МБ.
* См. также [Поддерживаемые типы медиафайлов](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types).

### Аудиосообщение

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

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

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "audio",
  "audio": {
    "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp3"
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Поддерживаемые типы аудио: `audio/aac`, `audio/mp4`, `audio/mpeg`, `audio/amr`, `audio/ogg` (только кодеки opus, базовый `audio/ogg` не поддерживается).
* Ограничение размера аудио: 16 МБ.
* См. также [Поддерживаемые типы медиафайлов](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types).
* `caption` можно использовать для медиасообщений типа `image`, `video` и `document`, но не поддерживается для аудиосообщений.

### Сообщение с документом

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

* Содержит URL документа.
* Содержит подпись с описанием документа.
* Задает имя файла документа.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "document",
  "document": {
    "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.pdf",
    "caption": "Describes the specified media.",
    "filename": "Sample.pdf"
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Поддерживаемые типы документов: `text/plain`, `application/pdf`, `application/vnd.ms-powerpoint`, `application/msword`, `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.openxmlformats-officedocument.presentationml.presentation`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`.
* Ограничение размера документа: 100 МБ.
* См. также [Поддерживаемые типы медиафайлов](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types).
* `filename` поддерживается только для сообщений с документами и не поддерживается для любых других медиасообщений.

### Сообщение со стикером

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

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

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "sticker",
  "sticker": {
    "link": "https://whatsticker.online/stickers_asset/ws-pack-196906m7W4ngr/c8e072f92595.webp"
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Поддерживаемые типы стикеров: `image/webp`. Ожидаемое разрешение: 512x512.
* Ограничение размера стикера: 100 КБ для статичных стикеров и 500 КБ для анимированных стикеров.
* См. также [Поддерживаемые типы медиафайлов](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types).

### Сообщение с контактом

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

* Содержит 1 контакт с адресами, датой рождения, адресами электронной почты, именем, телефонами и т. д.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "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"
        }
      ],
      "urls": [
        {
          "url": "<CONTACT_URL>",
          "type": "WORK"
        }
      ]
    }
  ]
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, но не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Поле `contacts[].name.formatted_name` является обязательным.

### Сообщение с местоположением

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

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

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "location",
  "location": {
    "latitude": 1.40435,
    "longitude": 103.79304,
    "name": "Singapore Zoo",
    "address": "80 Mandai Lake Road Singapore 72"
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, но не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Поля `latitude` и `longitude` являются обязательными.

### Сообщение-реакция

В этом случае вы отправляете реакцию в виде эмодзи:

* Содержит ID указанного сообщения.
* Содержит эмодзи.

![](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaing-reaction.png)<br />
Ставит отметку «палец вверх» ранее отправленному или полученному сообщению.

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.BgNODYxN...",
    "emoji": "👍"
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, но не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Параметр `message_id` представляет собой исходный ID сообщения на платформе WhatsApp, начинающийся с `wamid.`.
* Установите для `emoji` значение `""`, если хотите удалить эмодзи.
* Сообщения-реакции не поддерживают уведомления о прочтении.

### Интерактивное сообщение со списком

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

* Содержит текст заголовка, основной текст и текст нижнего колонтитула.
* Устанавливает значение `interactive.type` равным `list` и содержит кнопку с 2 разделами, каждый из которых содержит по 2 строки.

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

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "<HEADER_TEXT>"
    },
    "body": {
      "text": "<BODY_TEXT>"
    },
    "footer": {
      "text": "<FOOTER_TEXT>"
    },
    "action": {
      "button": "<BUTTON_TEXT>",
      "sections": [
        {
          "title": "<LIST_SECTION_1_TITLE>",
          "rows": [
            {
              "id": "<LIST_SECTION_1_ROW_1_ID>",
              "title": "<SECTION_1_ROW_1_TITLE>",
              "description": "<SECTION_1_ROW_1_DESC>"
            },
            {
              "id": "<LIST_SECTION_1_ROW_2_ID>",
              "title": "<SECTION_1_ROW_2_TITLE>",
              "description": "<SECTION_1_ROW_2_DESC>"
            }
          ]
        },
        {
          "title": "<LIST_SECTION_2_TITLE>",
          "rows": [
            {
              "id": "<LIST_SECTION_2_ROW_1_ID>",
              "title": "<SECTION_2_ROW_1_TITLE>",
              "description": "<SECTION_2_ROW_1_DESC>"
            },
            {
              "id": "<LIST_SECTION_2_ROW_2_ID>",
              "title": "<SECTION_2_ROW_2_TITLE>",
              "description": "<SECTION_2_ROW_2_DESC>"
            }
          ]
        }
      ]
    }
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, но не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Для интерактивных сообщений типа `list` необходимо настроить кнопку и указать от 1 до 10 разделов. Суммарно во всех разделах может быть не более 10 строк.

### Интерактивное сообщение с кнопками

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

* Содержит основной текст.
* Устанавливает значение `interactive.type` равным `button` и содержит 2 кнопки быстрого ответа.

![](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaging-interactivebutton.png)<br />
Получатель может нажать любую из кнопок, чтобы отправить вам ответное сообщение.

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "<BUTTON_TEXT>"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "<UNIQUE_BUTTON_ID_1>",
            "title": "<BUTTON_TITLE_1>"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "<UNIQUE_BUTTON_ID_2>",
            "title": "<BUTTON_TITLE_2>"
          }
        }
      ]
    }
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, но не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Для интерактивных сообщений типа `buttons` можно настроить не более 3 кнопок быстрого ответа.

### Интерактивное сообщение с CTA URL-кнопкой

В этом случае вы отправляете интерактивное сообщение с кнопкой-призывом к действию (CTA URL):

* Содержит текст заголовка, основной текст и текст нижнего колонтитула.
* Содержит кнопку со ссылкой (URL).

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "image",
      "image": {
        "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
      }
    },
    "body": {
      "text": "<BODY_TEXT>"
    },
    "footer": {
      "text": "<FOOTER_TEXT>"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "See Docs",
        "url": "https://developers.facebook.com/docs/whatsapp"
      }
    }
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, но не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Длина текста кнопки не должна превышать 20 байт.
* Поля `body` и `action` являются обязательными. Поля `header` и `footer` являются необязательными.

### Интерактивное сообщение с одним товаром

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

* Содержит основной текст и текст нижнего колонтитула.
* Устанавливает значение `interactive.type` равным `product` и содержит действие с информацией о товаре.

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

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "<OPTIONAL_BODY_TEXT>"
    },
    "footer": {
      "text": "<OPTIONAL_FOOTER_TEXT>"
    },
    "action": {
      "catalog_id": "367025965434465",
      "product_retailer_id": "<ID_TEST_ITEM_1>"
    }
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, но не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Чтобы получить ID товара и каталога, перейдите в [Meta Commerce Manager](https://business.facebook.com/commerce/).
* См. также [Share Products With Customers](https://developers.facebook.com/docs/whatsapp/guides/commerce-guides/share-products-with-customers).

### Интерактивное сообщение с несколькими товарами

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

* Содержит основной текст и текст нижнего колонтитула.
* Устанавливает значение `interactive.type` равным `product_list` и содержит несколько товаров.

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "product_list",
    "header": {
      "type": "text",
      "text": "<YOUR_TEXT_HEADER_CONTENT>"
    },
    "body": {
      "text": "<YOUR_TEXT_BODY_CONTENT>"
    },
    "footer": {
      "text": "<YOUR_TEXT_FOOTER_CONTENT>"
    },
    "action": {
      "catalog_id": "146265584024623",
      "sections": [
        {
          "title": "<SECTION1_TITLE>",
          "product_items": [
            {
              "product_retailer_id": "<YOUR_PRODUCT1_SKU_IN_CATALOG>"
            },
            {
              "product_retailer_id": "<YOUR_SECOND_PRODUCT1_SKU_IN_CATALOG>"
            }
          ]
        },
        {
          "title": "<SECTION2_TITLE>",
          "product_items": [
            {
              "product_retailer_id": "<YOUR_PRODUCT2_SKU_IN_CATALOG>"
            },
            {
              "product_retailer_id": "<YOUR_SECOND_PRODUCT2_SKU_IN_CATALOG>"
            }
          ]
        }
      ]
    }
  }
}'
```

#### Ответ

При успешном запросе возвращается объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, но не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Чтобы получить ID товара и каталога, перейдите в [Meta Commerce Manager](https://business.facebook.com/commerce/).

### Интерактивное сообщение с каталогом

Сообщения каталога — это сообщения произвольного формата, которые позволяют демонстрировать ваш каталог товаров непосредственно внутри WhatsApp.

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

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

Когда клиент нажимает кнопку **View catalog** , ваш каталог товаров открывается прямо в WhatsApp.

![example-messaging-catalog-view.webp](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaging-catalog-view.webp)

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "catalog_message",
    "body": {
      "text": "Hello! Thanks for your interest. Ordering is easy. Just visit our catalog and add items to purchase."
    },
    "action": {
      "name": "catalog_message",
      "parameters": {
        "thumbnail_product_retailer_id": "2lc20305pt"
      }
    },
    "footer": {
      "text": "Best grocery deals on WhatsApp!"
    }
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Необходимо [загрузить инвентарь в Meta](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services/upload-inventory) в каталоге электронной коммерции, [подключенном к вашему WhatsApp Business Account](https://www.facebook.com/business/help/158662536425974).
* Включите корзину покупок и каталог товаров отдельно для каждого бизнес-номера телефона. По умолчанию корзина покупок включена, а значок витрины скрыт для всех бизнес-номеров телефонов, связанных с WhatsApp Business Account. Используйте эндпоинт [Update commerce settings](https://docs.ycloud.com/reference/whatsapp_phone_number-update-commerce-settings), чтобы включить или отключить эти функции.

### Интерактивное сообщение с запросом местоположения

Сообщения с запросом местоположения — это сообщения в свободной форме, отображающие **основной текст** и **кнопку отправки местоположения**. Когда пользователь WhatsApp нажимает кнопку, появляется экран отправки местоположения, который пользователь может использовать, чтобы поделиться своими геоданными.

![example-messaging-location-request-sharing-response.png](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaging-localtion-request-sharing-response.png)

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": {
      "text": "<BODY_TEXT>"
    },
    "action": {
      "name": "send_location"
    }
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Основной текст (т. е. `interactive.body`) обязателен и может содержать не более 1024 символов. Верхний (header) и нижний (footer) колонтитулы не поддерживаются.
* Как только пользователь поделится своим местоположением, срабатывает Webhook `whatsapp.inbound_message.received`, содержащий сведения о местоположении пользователя. См. также [Входящее сообщение с местоположением](/ru/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples#inbound-location-message).

### Интерактивное сообщение Flow

Вы можете отправить сообщение с Flow в диалоге, инициированном пользователем, используя сообщение с призывом к действию (CTA):

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
        "flow_id": "1",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_ID>",
          "data": {
            "product_name": "name",
            "product_description": "description",
            "product_price": 100
          }
        }
      }
    }
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Для отправки сообщения с Flow мы добавили новый тип объекта `interactive` с именем `flow`. Дополнительные сведения см. в разделе [Параметры интерактивного сообщения](https://developers.facebook.com/docs/whatsapp/flows/guides/sendingaflow#interactive-message-parameters).
* Инструкции по отправке шаблонного сообщения с Flow см. в разделе [Шаблонное сообщение Flow](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#flow-template-message).
* Инструкции по получению ответа Flow см. в разделе [Входящее интерактивное ответное сообщение Flow](/ru/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples#inbound-interactive-flow-response-message).

### Интерактивное сообщение с деталями заказа

Сообщение типа `order_details` — это новый тип сообщения `interactive`, который всегда содержит 4 основных компонента: `header`, `body`, `footer` и `action`. Внутри компонента `action` компания указывает всю информацию, необходимую клиенту для совершения оплаты.

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "order_details",
    "header": {
      "type": "image",
      "image": {
        "link": "https://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    },
    "body": {
      "text": "your-text-body-content"
    },
    "footer": {
      "text": "your-text-footer-content"
    },
    "action": {
      "name": "review_and_pay",
      "parameters": {
        "reference_id": "reference-id-value",
        "type": "digital-goods",
        "payment_settings": [
          {
            "type": "payment_gateway",
            "payment_gateway": {
              "type": "billdesk",
              "configuration_name": "payment-config-id",
              "billdesk": {
                "additional_info1": "additional_info1-value",
                "additional_info2": "additional_info2-value",
                "additional_info3": "additional_info3-value",
                "additional_info4": "additional_info4-value",
                "additional_info5": "additional_info5-value",
                "additional_info6": "additional_info6-value",
                "additional_info7": "additional_info7-value",
              }
            }
          }
        ],
        "currency": "INR",
        "total_amount": {
          "value": 21000,
          "offset": 100
        },
        "order": {
          "status": "pending",
          "catalog_id": "the-catalog_id",
          "expiration": {
            "timestamp": "utc_timestamp_in_seconds",
            "description": "cancellation-explanation"
          },
          "items": [
            {
              "retailer_id": "1234567",
              "name": "Product name, for example bread",
              "amount": {
                "value": 10000,
                "offset": 100
              },
              "quantity": 1,
              "sale_amount": {
                "value": 100,
                "offset": 100
              }
            }
          ],
          "subtotal": {
            "value": 20000,
            "offset": 100
          },
          "tax": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text"
          },
          "shipping": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text"
          },
          "discount": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text",
            "discount_program_name": "optional_text"
          }
        }
      }
    }
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Чтобы узнать больше о параметрах `interactive`, см. раздел [Отправка интерактивного сообщения с деталями заказа](https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/payments-in/pg#step-1).
* Если с момента последнего ответа клиента на ваш бизнес-номер телефона прошло более 24 часов, отправьте вместо этого [шаблонное сообщение с деталями заказа](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#order-details-template-message).

### Интерактивное сообщение со статусом заказа

Чтобы уведомить клиента об изменениях по заказу, вы можете отправить интерактивное сообщение типа order\_status, как показано ниже.

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "order_status",
    "body": {
      "text": "your-text-body-content"
    },
    "action": {
      "name": "review_order",
      "parameters": {
        "reference_id": "reference-id-value",
        "order": {
          "status": "processing | partially_shipped | shipped | completed | canceled",
          "description": "optional-text"
        }
      }
    }
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

* Чтобы узнать больше о параметрах `interactive`, см. раздел [Отправка обновлений статуса заказа](https://developers.facebook.com/docs/whatsapp/cloud-api/payments-api/payments-in/pg#step-4--update-order-status).
* Если с момента последнего ответа клиента на ваш бизнес-номер телефона прошло более 24 часов, отправьте вместо этого [шаблонное сообщение с деталями заказа](/ru/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#order-status-template-message).
* Вы будете получать уведомления через Webhook при попытке оплаты клиентом и при изменении статуса платежа. См. раздел [Обновление платежной транзакции](/ru/api-reference/guides/examples/webhook-examples/whatsapp-payment-updated-webhook-examples).

### Интерактивное сообщение голосового вызова

Компания вызывает этот API для отправки сообщения клиентам, чтобы информировать о возможности телефонной поддержки с помощью встроенной кнопки внутри сообщения. Когда клиент нажимает эту кнопку, инициируется звонок WhatsApp на бизнес-номер, с которого было отправлено это сообщение. Это действие аналогично нажатию клиентом значка телефона/вызова в строке заголовка чата. Кнопка не поддерживает звонки в WhatsApp на другой номер телефона.

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "voice_call",
    "body": {
      "text": "You can call us on WhatsApp now for faster service!"
    },
    "action": {
      "name": "voice_call",
      "parameters": {
        "display_text": "Call on WhatsApp"
      }
    }
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

Сопоставьте поля запроса с выбранным типом сообщения и используйте возвращенный ID сообщения для отслеживания статуса.

### Интерактивные медиасообщения с каруселью

Интерактивное сообщение с медиа-каруселью позволяет компаниям отправлять карточки с изображениями или видео, прокручиваемые по горизонтали, каждая из которых содержит кнопку с призывом к действию, в чатах WhatsApp. Этот формат позволяет пользователям просматривать несколько предложений или единиц контента в одном сообщении, обеспечивая богатый и увлекательный опыт взаимодействия через WhatsApp Business API и мобильные клиенты.

* `interactive.type` должно иметь значение `carousel`
* `interactive.action.cards` необходимо добавить не менее 2 объектов карточек в сообщение, максимум — 10.
* Тип каждой карточки должен быть установлен на `cta_url`
* все карточки должны иметь одинаковый тип заголовка (`image` или `video`)
* необходимо добавить текст сообщения (`interactive.body`) в сообщение (максимум 1024 символа). Заголовок, футер или кнопки вне карточек не допускаются.
* все карточки должны иметь одинаковую структуру (заголовок, текст, действие).
* текст карточки не обязателен, но не более 160 символов и до 2 переносов строк.

![f657ef005148593d05cc1ded201de7731d11b51200fd4900ad2584533ddd282d-interactive\_media\_carousel\_message.jpg](https://files.readme.io/f657ef005148593d05cc1ded201de7731d11b51200fd4900ad2584533ddd282d-interactive_media_carousel_message.jpg)

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Check out our latest offers!"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          },
          "body": {
            "text": "Exclusive deal #1"
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Shop now",
              "url": "https://shop.example.com/deal1"
            }
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          },
          "body": {
            "text": "Exclusive deal #2"
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Shop now",
              "url": "https://shop.example.com/deal2"
            }
          }
        }
      ]
    }
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

Сопоставьте поля запроса с выбранным типом сообщения и используйте возвращенный ID сообщения для отслеживания статуса.

### Интерактивные сообщения с медиа-каруселью и кнопками быстрого ответа

* Карточки должны содержать либо одну кнопку со ссылкой (URL), либо одну или несколько кнопок быстрого ответа. Типы и количество кнопок должны совпадать для всех карточек (например, если вы определяете карточку с 2 кнопками быстрого ответа, все карточки должны содержать ровно 2 кнопки быстрого ответа).

![a604f0105ba6b8dfa01f317ce10c2cb3961f1564a6cf12c9bede2eac57a11808-carousel\_quick\_reply.png](https://files.readme.io/a604f0105ba6b8dfa01f317ce10c2cb3961f1564a6cf12c9bede2eac57a11808-carousel_quick_reply.png)

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Check out our latest offers!"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          },
          "body": {
            "text": "Exclusive deal #1"
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-zebra-haworthia",
                  "title": "Learn more"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-zebra-haworthia",
                  "title": "Add to favorites"
                }
              }
            ]
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          },
          "body": {
            "text": "Exclusive deal #2"
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-zebra-haworthia",
                  "title": "Learn more"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-zebra-haworthia",
                  "title": "Add to favorites"
                }
              }
            ]
          }
        }
      ]
    }
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

Сопоставьте поля запроса с выбранным типом сообщения и используйте возвращенный ID сообщения для отслеживания статуса.

### Сообщение с кнопкой оформления заказа (Checkout Button)

После одобрения вашего шаблона с кнопкой оформления заказа вы можете отправить его в виде шаблонного сообщения

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "item_back_in_stock_v1",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic",

    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "id": "12312312", <!-- Only if using uploaded media -->
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg" <!-- Only if using hosted media (not recommended) -->
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Nidhi"
          },
          {
            "type": "text",
            "text": "Blue Elf Aloe"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "order_details",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "order_details": {
                "reference_id": "abc.123_xyz-1",
                "type": "physical-goods",
                "currency": "INR",
                "payment_settings": [
                  {
                    "type": "payment_gateway",
                    "payment_gateway": {
                      "type": "razorpay",
                      "configuration_name": "prod-razor-pay-config-05"
                    }
                  }
                ],
                "shipping_info": {
                  "country": "IN",
                  "addresses": [
                    {
                      "name": "Nidhi Tripathi",
                      "phone_number": "919000090000",
                      "address": "Bandra Kurla Complex",
                      "city": "Mumbai",
                      "state": "Maharastra",
                      "in_pin_code": "400051",
                      "house_number": "12",
                      "tower_number": "5",
                      "building_name": "One BKC",
                      "landmark_area": "Near BKC Circle"
                    }
                  ]
                },
                "order": {
                  "items": [
                    {
                      "amount": {
                        "offset": 100,
                        "value": 200000
                      },
                      "sale_amount": {
                        "offset": 100,
                        "value": 150000
                      },
                      "name": "Blue Elf Aloe",
                      "quantity": 1,
                      "country_of_origin": "India",
                      "importer_name": "Lucky Shrub Imports and Exports",
                      "importer_address": {
                        "address_line1": "One BKC",
                        "address_line2": "Bandra Kurla Complex",
                        "city": "Mumbai",
                        "zone_code": "MH",
                        "postal_code": "400051",
                        "country_code": "IN"
                      }
                    }
                  ],
                  "subtotal": {
                    "offset": 100,
                    "value": 150000
                  },
                  "shipping": {
                    "offset": 100,
                    "value": 20000
                  },
                  "tax": {
                    "offset": 100,
                    "value": 10000
                  },
                  "discount": {
                    "offset": 100,
                    "value": 15000,
                    "description": "Additional 10% off"
                  },
                  "status": "pending",
                  "expiration": {
                    "timestamp": "1726627150"
                  }
                },
                "total_amount": {
                  "offset": 100,
                  "value": 165000
                }
              }
            }
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

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

Сопоставьте поля запроса с выбранным типом сообщения и используйте возвращенный ID сообщения для отслеживания статуса.

### Шаблонное сообщение с GIF

В этом случае вы отправляете шаблонное сообщение с GIF:

* Содержит URL GIF-изображения.

![d29ea20d56e36017614121fc2079e5c513d6f922c3713a2c963e3dfca7570c0c-Feishu20260128-162503.gif](https://files.readme.io/d29ea20d56e36017614121fc2079e5c513d6f922c3713a2c963e3dfca7570c0c-Feishu20260128-162503.gif)

#### Запрос

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "marketing_friday_more",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "gif",
            "gif": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4"
            }
          }
        ]
      }
    ]
  }
}'
```

#### Ответ

Успешный запрос возвращает объект сообщения YCloud. Начальный статус `accepted` подтверждает отправку, а не окончательную доставку.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "status": "accepted"
}
```

Сохраните `id` и сопоставляйте последующие события `whatsapp.message.updated`.

<br />

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

Сопоставьте поля запроса с выбранным типом сообщения и используйте возвращенный ID сообщения для отслеживания статуса.


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