Интерактивные сообщения в виде карусели | Документация для разработчиков

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

Обновлено: 22 декабря 2025 г

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

Например, это интерактивное сообщение в виде карусели из медиакарточек, отображающее три карточки в прокручиваемой области (выделены пунктирным прямоугольником), каждая из которых содержит заголовок с изображением, основной текст и кнопку URL:

Это то же самое сообщение, но вместо кнопок URL используются кнопки быстрого ответа:

Компоненты

Сообщения должны включать от 2 до 10 открыток.Основной текст сообщения обязателен.Заголовки, нижние колонтитулы и интерактивные компоненты основного сообщения не поддерживаются.В заголовке карточки должно быть либо изображение, либо видео. Другие типы заголовков не поддерживаются.Текст основного содержимого карточки необязателен.Карточки должны содержать либо одну кнопку URL, либо одну или несколько кнопок быстрого ответа. Типы и количество кнопок должны совпадать на всех карточках (например, если вы определили карточку с двумя кнопками быстрого ответа, то на всех карточках должно быть ровно две кнопки быстрого ответа).

Синтаксис запроса

curl 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<USER_PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "<MESSAGE_BODY_TEXT>"
    },
    "action": {

<!-- First card object -->
      "cards": [
        {
          "card_index": <CARD_INDEX>,
          "type": "cta_url",
          "header": {
            "type": "<HEADER_TYPE>",
            "<HEADER_TYPE>": {
              "link": "<MEDIA_ASSET_URL>"
            }
          },

<!-- Card body text is optional -->
          "body": {
            "text": "<CARD_BODY_TEXT>"
          },

          "action": {
<!-- Only if using a URL button -->
            "name": "cta_url",
            "parameters": {
              "display_text": "<URL_BUTTON_LABEL>",
              "url": "<URL_BUTTON_URL>"
            }
<!-- Only if using one or more quick-reply buttons -->
            "кнопки": [
              {
                "тип": "быстрый_ответ",
                "быстрый_ответ": {
                  "id": "<QUICK_REPLY_BUTTON_ID>",
                  "title": "<QUICK_REPLY_BUTTON_LABEL>"
                }
              },
<!-- Additional quick-reply buttons would follow -->
          }
        },
<!-- Additional card objects would follow -->
      ]
    }
  }
}'

Параметры запроса

Заполнитель	Описание	Пример значения
`<ACCESS_TOKEN>` Нить	Обязательно. Токен доступа.	`EAAJB...`
`<API_VERSION>` Нить	Необязательно. Версия API.	`v23.0`
`<BUSINESS_PHONE_NUMBER_ID>` Целое число	Обязательно. Идентификационный номер рабочего телефона.	`106540352242922`
`<CARD_BODY_TEXT>` Нить	Необязательно. Основной текст карточки. Максимум 160 символов, до 2 переносов строк.	`Синяя эхеверия\n\nСуккулент в форме розетки с нежно-голубыми листьями, идеально подходящий для украшения любого помещения.`
`<CARD_INDEX>` Целое число	Обязательно. Нулевой индекс карточек. Карточки будут отображаться слева направо в прокручиваемом режиме, начиная с 0.	`0`
`<HEADER_TYPE>` Нить	Обязательно. Тип заголовка. Возможные значения: `image` — указывает на заголовок изображения карты; `video` — указывает на заголовок видео карты. См. раздел «Поддерживаемые типы носителей».	`изображение`
`<MEDIA_ASSET_URL>` Нить	Обязательно. Общедоступный URL-адрес медиафайла.	`https://www.luckyshrub.com/assets/blue-echeveria.jpeg`
`<MESSAGE_BODY_TEXT>` Нить	Обязательно. Основной текст сообщения. Максимальное количество символов: 1024.	`Конечно! Вот три наших последних поступления, каждое по цене менее 25 долларов:`
`<QUICK_REPLY_BUTTON_ID>` Нить	Обязательно, если используется кнопка быстрого ответа. Идентификатор кнопки быстрого ответа. Максимум 256 символов.	`learn-blue-echeveria`
`<QUICK_REPLY_BUTTON_LABEL>` Нить	Обязательно, если используется кнопка быстрого ответа. Текст подписи кнопки быстрого ответа. Максимум 20 символов.	`Узнать больше`
`<URL_BUTTON_LABEL>` Нить	Обязательно, если используется кнопка с URL-адресом. Текст метки кнопки с URL-адресом. Максимум 20 символов.	`Купить сейчас`
`<URL_BUTTON_URL>` Нить	Обязательно, если используется кнопка с URL-адресом. URL-адрес, который будет загружен в веб-браузере по умолчанию устройства при нажатии пользователем.	`https://shop.luckyshrub.com/latest/blue-echeveria`
`<USER_PHONE_NUMBER>` Нить	Обязательно. Номер телефона пользователя WhatsApp.	`16505551234`

Примеры запросов

Пример кнопок URL

В этом примере запроса отправляется сообщение в виде медиа-карусели, состоящее из 3 карточек, каждая из которых содержит заголовок с изображением, основной текст карточки и кнопку с URL-адресом.

curl'https://graph.facebook.com/v23.0/106540352242922/messages' \
-H'Content-Type: application/json' \
-H'Authorization: Bearer EAAJB...' \
-d'
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "16505551234",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Конечно! Вот три наших последнихпредложения, каждое менее чем за 25 долларов:"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/blue-echeveria.jpeg"
            }
          },
          "body": {
            "text": "*Синяя эхеверия*\n\nСуккулентв форме розетки с нежно-голубыми листьями, идеально подходящийдля украшения любого пространства."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Купить сейчас",
              "url": "https://shop.luckyshrub.com/latest/blue-echeveria"
            }
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/zebra-haworthia.jpeg"
            }
          },
          "body": {
            "text": "*Хавортия «Зебра»*\n\nЯркие белые полосы на темно-зеленых листьях придают этому компактномусуккуленту смелый, современный вид."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Купить сейчас",
              "url": "https://shop.luckyshrub.com/latest/zebra-haworthia"
            }
          }
        },
        {
          "card_index": 2,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/panda-plant.jpeg"
            }
          },
          "body": {
            "text": "*Растение панда*\n\nМягкие, пушистые листья с шоколадно-коричневыми краями — очаровательные и простые в уходе."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Купить сейчас",
              "url": "https://shop.luckyshrub.com/latest/panda-plant"
            }
          } }
        ]
      }
    }
  }
'

Пример кнопок быстрого ответа

В этом примере запроса отправляется сообщение в виде медиа-карусели, состоящее из 3 карточек, каждая из которых содержит заголовок с изображением, основной текст карточки и две кнопки быстрого ответа.

curl'https://graph.facebook.com/v23.0/106540352242922/messages' \
-H'Content-Type: application/json' \
-H'Authorization: Bearer EAAJB...' \
-d'
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "16505551234",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Конечно! Вот три наших последнихпредложения, каждое менее чем за 25 долларов:"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/blue-echeveria.jpeg"
            }
          },
          "body": {
            "text": "*Синяя эхеверия*\n\nСуккулентв форме розетки с нежно-голубыми листьями, идеально подходящийдля украшения любого пространства."
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-blue-echeveria",
                  "title": "Узнать больше"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-blue-echeveria",
                  "title": "Добавить в избранное"
                }
              }
            ]
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/zebra-haworthia.jpeg"
            }
          },
          "body": {
            "text": "*Зебровая хавортия*\n\nЯркие белые полосы на темно-зеленых листьях придают этому суккулентусмелый, современный вид."
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-zebra-haworthia",
                  "title": "Узнать больше"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-zebra-haworthia",
                  "title": "Добавить в избранное"
                }
              }
            ]
          }
        },
        {
          "card_index": 2,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/panda-plant.jpeg"
            }
          },
          "body": {
            "text": "*Растение панда*\n\nМягкие, пушистые листья с шоколадно-коричневыми краями — очаровательные и простые в уходе."
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-panda-plant",
                  "title": "Узнать больше"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-panda-plant",
                  "title": "Добавить в избранное"
                } }
              ]
            }
          }
        ]
      }
    }
  }
'

Пример ответа

{
"messaging_product": "whatsapp",
"contacts": [
    {
"input": "+16505551234",
"wa_id": "16505551234"
    }
  ],
"messages": [
    {
"id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"
    }
  ]
}