> For the complete documentation index, see [llms.txt](https://help.1msg.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.1msg.io/docs/russkii/api-1msg/shablony-waba/shablon-karusel.md).

# Шаблон Карусель

## Общее описание

Шаблон  «Карусель» имеет два формата отправки:

### **Карусель с карточками с произвольным заполнением**

Максимальная гибкость под ваш сценарий. Идеально, если важна кастомизация и маркетинговая свобода.

* Вы сами формируете карусель: количество карточек, тексты, переменные и кнопки
* При отправке подставляете изображения и значения переменных
* Подходит для нестандартных акций, спецпредложений и контента под конкретный сегмент
* Полный контроль над визуалом и смыслом каждой карточки

<figure><img src="https://lh7-us.googleusercontent.com/DynBlcrLwlnQ4zF6YbeK695-16sly_eON6hfS7f6xZu-Zrvez0_9E-kGAE8wzoEK9R2xe38OXZpvePW25A91TSoFPlMTsQKy5TF90gEiYtUmEDPGxTJriZvxTDf3Fp20aDASSvGjixGVja-pX23lCmY" alt=""><figcaption><p>Шаблон "Карусель" в WhatsApp</p></figcaption></figure>

### **Карусель с карточками товара  из каталога WhatsApp**&#x20;

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

* Карточки подтягиваются напрямую из каталога WhatsApp
* Не нужно вручную заполнять описания, загружать изображения и настраивать кнопки
* Данные всегда актуальны: цена, название товара, описание, картинки.&#x20;
* Меньше человеческого фактора и ошибок при отправке

<figure><img src="/files/pl0BwUp4daPZhMTGaxmQ" alt=""><figcaption></figcaption></figure>

### **Описание**

Шаблоны карусели позволяют отправлять одно общее текстовое сообщение (1) в сопровождении набора из 10 карточек карусели (2) с горизонтальной прокруткой.

Шаблон пользователи могут просматривать как с мобильных устройств, так и  в веб-клиенте WhatsApp.

**Возможности шаблона Карусель**

* Подборки помогут показать разный ассортимент товаров или услуг либо рассказать об одной интересующей линейке, но с разными вариациями.  Это лучше удовлетворит запрос клиента, а вам увеличит конверсию.&#x20;
* Продвигайте новинки, специальные предложения, акции на праздники и т.д.
* С помощью кнопок ведите вашего клиента к действию - например, предложите записаться на услугу, сделать заказ,  открыть сайт и т.д.&#x20;

### **Способы отправки**

Carousel можно отправлять двумя способами:

* [**Через шаблон**](#kak-otpravit-shablon-karusel) **(Template message)** — используется для отправки **вне 24-часового окна**. Требует предварительного создания и утверждения шаблона WhatsApp. Отправка **платная**.
* [**Как сервисное сообщение** ](#kak-otpravit-shablon-karusel-kak-servisnoe-soobshenie)— используется **внутри 24-часового окна диалога**. Шаблон не требуется. Отправка **бесплатная**.

## **Создание шаблона**

Создание шаблона описано[ в документации API ](https://1msg-docs.web.app/ru#tag/Shablony/operation/addTemplate)в методе /addTemplate.

Отличие от базового создания шаблона в добавлении нового типа CAROUSEL в компоненты и массива cards. Полный пример добавления шаблона Карусель добавлен ниже.&#x20;

#### **Основные правила создания шаблона:**

1. Шаблон обязательно должен иметь  общее и объединяющее по контексту текстовое сообщение (1).
2. Шаблон может содержать от 1 до 10 карточек.
3. Формат медиа-заголовка и типы кнопок должны быть одинаковыми для всех карточек.
4. Медиа-заголовок (изображение или видео) и текстовое сообщение обязательны для каждой карточки.
5. В каждой карточке должно быть не менее 1 кнопки, максимум - две кнопки.
6. Поддерживаются следующие типы кнопок: "Быстрый ответ", "URL" и "Номер телефона". Кнопки могут быть одного типа или сочетать в себе кнопки быстрого ответа, кнопки телефонного номера или кнопки URL для каждой карточки.
7. Не забывайте указывать примеры переменных, если вы добавили их в body, ссылку URL кнопок. Иначе шаблон будет отклонен Meta\*.

<details>

<summary>Пример создания шаблона "Карусель"</summary>

Ссылки указаны тестовые, при копировании не забудьте указать верные.  Пример наполнения взят из источника 360Dialog

```json
POST https://api.1msg.io/{{channel}}/addTemplate
Content-Type: application/json
Body: {
  "name": "marceting_carousel_01_test",
  "allow_category_change": true,
  "category": "MARKETING",
  "language": "en",
  "components": [
    {
      "text": "Summer is here, and we have the freshest produce around! Use code {{1}} to get {{2}} off your next order.",
      "type": "BODY",
      "example": {
        "body_text": [
          [
            "15OFF",
            "15%"
          ]
        ]
      }
    },
    /* Карточки Карусели */
    {
      "type": "CAROUSEL" // новый тип для шаблона Карусель
      "cards": [ 
        {
        /* Первая карточка карусели */
          "components": [ 
            {
              "type": "HEADER",
              "format": "IMAGE", 
              "example": {
                "header_handle": [
                  "https://img.example.com/delicious-background-orange-slices_23-2148231462.jpg"
                ]
              }
            },
            {
              "type": "BODY", 
              "text": "Rare lemons for unique cocktails. Use code {{1}} to get {{2}} off all produce",
              "example": { //Примеры параметров. Количество значений должно соответствовать количеству переменных, включенных в строку.
                "body_text": [
                  [
                    "150FF",
                    "10%"
                  ]
                ]
              }
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Send more like this #1"
                },
                {
                  "type": "URL",
                  "text": "Buy now",
                  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
                  "example": [
                    "summer_lemons_2023"
                  ]
                }
              ]
            }
          ]
        },
        /* Вторая карточка карусели */
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": {
                "header_handle": [
                  "https://img.example.com/top-view-citric-fruit-slices-table_23-2148495686.jpg"
                ]
              }
            },
            {
              "type": "BODY",
              "text": "Exotic fruit for unique cocktails! Use code {{1}} to get {{2}} off all exotic produce",
              "example": {
                "body_text": [
                  [
                    "20OFFEXOTIC",
                    "20%"
                  ]
                ]
              }
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Send more like this #2"
                },
                {
                  "type": "URL",
                  "text": "Buy now",
                  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
                  "example": [
                    "exotic_produce_2023"
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

</details>

<details>

<summary>Пример создания шаблона "Карусель"​ с карточкой товара из WhatsApp </summary>

Ссылки указаны тестовые, при копировании не забудьте указать верные. &#x20;

```json
POST https://api.1msg.io/{{channel}}/addTemplate
Content-Type: application/json
Body: {
  "name": "marceting_carousel_01_test",
  "allow_category_change": true,
  "category": "MARKETING",
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "text": "Hi, {{1}}! Summer is here, and we have the freshest produce around!",
       "example": {
        "body_text": [
          [
            "Anna"
          ]
        ]
      }
    },
    {
      "type": "CAROUSEL",
      "cards": [
      /* Первая карточка карусели c товаром, заполнение ID товара */
      /* будет при отправке шаблона */
        {
          "components": [
            {
              "type": "HEADER",
              "format": "PRODUCT"
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "SPM",
                  "text": "View"
                }
              ]
            }
          ]
        },
         /* Вторавя карточка карусели c товаром, заполнение ID товара */
         /* будет при отправке шаблона */
        {
          "components": [
            {
              "type": "HEADER",
              "format": "PRODUCT"
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "SPM",
                  "text": "View"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

</details>

<table><thead><tr><th width="218">Параметры</th><th width="337.3333333333333">Описание</th><th>Пример</th></tr></thead><tbody><tr><td><p>BUBBLE_TEXT</p><p><em>String</em></p></td><td><p><strong>Обязателен</strong>.</p><p></p><p>Текстовое сообщение, что выводится выше карточек</p><p></p><p>Максимум 1024 символов.</p></td><td>Summer is here, and we've got the freshest produce around! Use code {{1}} to get {{2}} off your next order.</td></tr><tr><td><p>BUBBLE_TEXT_VAR_EXAMPLE</p><p>Array of strings</p></td><td><p>Обязателен, если в  bubble text используются переменные</p><p><br>Массив примеров строк переменных. Количество значений должно соответствовать количеству переменных, включенных в строку.</p></td><td>"15OFF","15%"</td></tr><tr><td><p>CARD_BODY_TEXT</p><p>String</p></td><td><p><strong>Обязателен</strong>.</p><p>Описание карточки. Поддерживает переменные</p><p>Максимум 160 символов.</p></td><td>Rare lemons for unique cocktails. Use code {{1}} to get {{2}} off all produce.</td></tr><tr><td><p>CARD_BODY_TEXT_VAR_EXAMPLE</p><p>Array of strings</p></td><td>Обязателен, если в текст карточки  содержит переменные</td><td>"15OFF","15%"</td></tr><tr><td><p>CARD_HEADER_FORMAT</p><p>Enum</p></td><td><p><strong>Обязателен</strong>.<br>Медиа-формат заголовка </p><p>(IMAGE илиVIDEO)</p></td><td>IMAGE</td></tr><tr><td><p>CARD_HEADER_HANDLE</p><p>Media asset handle</p></td><td><p><strong>Обязателен</strong>.</p><p>Пример отправляемого медиа</p></td><td></td></tr><tr><td><p>QUICK_REPLY_BUTTON_TEXT</p><p>String</p></td><td><p>Обязателен, если используется быстрая кнопка</p><p></p><p>Текст кнопки</p><p></p><p>Максимум 25 символов.</p></td><td>Send more like this #2</td></tr><tr><td><p>TEMPLATE_CATEGORY</p><p>Enum</p></td><td><p><strong>Обязателен</strong>.</p><p></p><p>Категория MARKETING или UTILITY.</p></td><td>MARKETING</td></tr><tr><td><p>TEMPLATE_LANGUAGE</p><p>Enum</p></td><td><p><strong>Обязателен</strong>.</p><p><br></p><p>Язык шаблона</p></td><td>en</td></tr><tr><td><p>TEMPLATE_NAME</p><p>String</p></td><td><p><strong>Обязателен</strong>.</p><p><br></p><p>Наименование шаблона</p><p><br></p><p>Максимум 512 символов.</p></td><td>marceting_carousel_01_test</td></tr><tr><td><p>URL_BUTTON_TEXT</p><p>String</p></td><td><p>Обязателен, если используется URL кнопка </p><p></p><p>Текст URL-кнопки. </p><p></p><p>Максимум 25 символов.</p></td><td>Buy now</td></tr><tr><td><p>URL_BUTTON_URL</p><p>String</p></td><td><p>Обязателен, если используется URL кнопка </p><p></p><p>URL на веб-ресурс, куда будет попадать пользователь при нажатии на кнопку-ссылку.</p><p></p><p>Поддерживает одну переменную в конце строки </p><p></p><p>Максимум 2000 символов.</p></td><td><a href="https://www.luckyshrub.com/shop?promo=%7B%7B1%7D%7D">https://www.luckyshrub.com/shop?promo={{1}}</a></td></tr><tr><td><p>URL_BUTTON_VAR_EXAMPLE</p><p>String</p></td><td><p>Обязателен, если используется URL кнопка </p><p></p><p>Пример URL на веб-ресурс, куда будет попадать пользователь при нажатии на кнопку-ссылку.</p><p></p><p>Поддерживает одну переменную в конце строки </p><p></p><p>Максимум 2000 символов.</p></td><td><a href="https://www.luckyshrub.com/shop?promo=summer_lemons_2023">https://www.luckyshrub.com/shop?promo=summer_lemons_2023</a></td></tr></tbody></table>

## Отправить шаблон Карусель

Отправка шаблона описана в [документации API ](https://1msg-docs.web.app/ru#tag/Shablony/operation/sendTemplate)в методе /sendTemplate.

Вы также можете отправить шаблон через раздел в личном кабинете "Кабинет разработчика" →["Тестирование запросов". ](https://my.1msg.io/testing/test-requests)Чтобы отправить шаблон, необходимо знать namespace, name и language шаблона. Чтобы получить эти данные, вызовите метод "Получить список шаблонов" (/templates).&#x20;

Некоторые свойства, которые могут вызвать вопросы в методе /sendTemplate.

Шаблон Карусель:

* Имеет свой type - CAROUSEL
* Объект с типом CAROUSEL содержит массив cards. Используется только для данного типа шаблона
* Каждая карточка содержит card\_index - порядок появления карточек в карусели карточек.0 означает первую карту, 1 означает вторую карту и т. д

<details>

<summary>Пример как отправить шаблон "Карусель"​</summary>

Пример шаблона из 2-ух карточек. Каждая карточка содержит кнопку быстрого ответа и url-кнопку. Медиа-заголовок - картинка.

```json
POST https://api.1msg.io/{{channel}}/sendTemplate
Content-Type: application/json
Body: {
  "namespace": "{{namespace}}", // Вызовите список шаблонов через метод /templates и найдете namespace для нужного шаблона
  "template": "marceting_carousel_01_test", // name шаблона
  "language": {
    "policy": "deterministic",
    "code": "en" // код language из запроса /templates
  },
  "params": [
    {
   /* Общее текстовое сообщение. Можно опустить, если в тексте нет переменных. */
      "type": "body", 
      "parameters": [
        {
          "type": "text",
          "text": "21OFF" // переменная {{1}} для общего текстового сообщения
        },
        {
          "type": "text",
          "text": "21" // переменная {{2}} для общего текстового сообщения
        }
      ]
    },
    {
      "type": "carousel",
      "cards": [
        /* Первая карточка */
        {
          "card_index": 0,
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "image",
                  "image": {
                    "link": "https://img.freepik.com/free-photo/top-view-citric-fruit-slices-table_23-2148495686.jpg"
                  }
                }
              ]
            },
            {
              "type": "button",
              "sub_type": "url",
              "index": 1,  // положение кнопки, начинается с 0. Тут url-кнопка вторая в последовательности, поэтому index=1
              "parameters": [
                {
                  "type": "text",
                  "text": "summer" // параметр в url ссылке
                }
              ]
            },
            {
             /* Текст карточки. Можно опустить, если в тексте не будет переменных. */
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "10F" // переменная {{1}} в первой карточке
                },
                {
                  "type": "text",
                  "text": "10" // переменная {{2}} в первой карточке
                }
              ]
            }
          ]
        },
        /* Вторая карточка */
        {
          "card_index": 1, 
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "image",
                  "image": {
                    "link": "https://img.freepik.com/free-photo/delicious-background-orange-slices_23-2148231462.jpg"
                  }
                }
              ]
            },
            {
              "type": "button",
              "sub_type": "url",
              "index": 1, // положение кнопки, начинается с 0. Тут url-кнопка вторая в последовательности, поэтому index=1
              "parameters": [
                {
                  "type": "text",
                  "text": "winter" // параметр в url ссылке
                }
              ]
            },
            {
             /* Текст карточки. Можно опустить, если в тексте не будет переменных. */
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "30F" // переменная {{1}} во второй карточке
                },
                {
                  "type": "text",
                  "text": "30" // переменная {{2}}  во второй карточке
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "phone": "+556123122026"
}
```

</details>

<details>

<summary>Пример как отправить шаблон "Карусель"​ с карточкой товара из WhatsApp </summary>

Пример шаблона из 2-ух карточек товара из каталога WhatsApp&#x20;

```json
POST https://api.1msg.io/{{channel}}/sendTemplate
Content-Type: application/json
Body: {
  "namespace": "{{namespace}}", // Вызовите список шаблонов через метод /templates и найдете namespace для нужного шаблона
  "template": "marketing_carousel_01_test", // name шаблона
  "language": {
    "policy": "deterministic",
    "code": "en" // код language из запроса /templates
  },
  "params": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Anna"
        }
      ]
    },
    {
      "type": "carousel",
      "cards": [
        /* Первая карточка */
      {
          "card_index": 0,
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "product",
                  "product": {
                    "product_retailer_id": "0001",
                    "catalog_id": "{{catalog_id}}"
                  }
                }
              ]
            }
          ]
        },
          /* Первая карточка */
        {
          "card_index": 1,
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "product",
                  "product": {
                    "product_retailer_id": "0002",
                    "catalog_id": "{{catalog_id}}"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "phone": "{{phone}}"
}
```

</details>

## Отправить Карусель как сервисное сообщение&#x20;

Для отправки Карусель как сервисное сообщение используйте метол /[sendCarousel](https://1msg-docs.web.app/ru#tag/Obmen-soobsheniyami/operation/sendCarousel)

Для такого способа отправки заранее не надо создавать шаблон Meta.

Структура сообщения во многом аналогична отправке шаблона. Однако в данном случае необходимо **явно указывать все элементы**, которые при работе с шаблонами создаются заранее. Это связано с тем, что сообщение отправляется **без использования шаблона**.

В шаблоне могут быть либо 1 кнопка URL либо одна или несколько кнопок быстрого ответа.&#x20;

<details>

<summary>Пример как отправить "Карусель"​ </summary>

Пример шаблона из 2-ух карточек. Каждая карточка содержит кнопку 2 кнопки быстрого ответа. Медиа-заголовок - картинка.

```json
POST https://api.1msg.io/{{channel}}/sendCarousel
Content-Type: application/json
Body: {
  "phone": "{{phone}}",
  "params": [
    {
      "type": "BODY",
      "parameters": [
        {
          "type": "text",
          "text": "Text Body"
        }
      ]
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "card_index": 0,
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "image",
                  "image": {
                    "link": "https://test-pick.ru/38eff70e116842949fd3019b226d31db.jpg"
                  }
                }
              ]
            },
            {
              "type": "BODY",
              "parameters": [
                {
                  "type": "text",
                  "text": "Description card 1"
                }
              ]
            },
            {
              "type": "button",
              "sub_type": "quick_reply",
              "parameters": [
                {
                  "text": "Кнопка",
                  "id": "Buttons1"
                },
                {
                  "text": "Кнопка 2",
                  "id": "Buttons2"
                }
              ]
            }
          ]
        },
        {
          "card_index": 1,
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "image",
                  "image": {
                    "link": "https://test-pick.ru/38eff70e116842949fd3019b226d31db.jpg"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "Description card 2"
                }
              ]
            },
            {
              "type": "button",
              "sub_type": "quick_reply",
              "parameters": [
                {
                  "text": "Кнопка",
                  "id": "Button3"
                },
                {
                  "text": "Кнопка 2",
                  "id": "Button4"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

</details>

<details>

<summary>Пример как отправить "Карусель"​ с карточкой товара из WhatsApp </summary>

Пример шаблона из 2-ух карточек товара из каталога WhatsApp.

```json
POST https://api.1msg.io/{{channel}}/sendCarousel
Content-Type: application/json
Body: {
  "phone": "{{phone}}",
  "params": [
    {
      "type": "BODY",
      "parameters": [
        {
          "type": "text",
          "text": "Text body"
        }
      ]
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "card_index": 0,
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "product",
                  "product": {
                    "product_retailer_id": "0001",
                    "catalog_id": "{{catalog_id}}"
                  }
                }
              ]
            }
          ]
        },
        {
          "card_index": 1,
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "product",
                  "product": {
                    "product_retailer_id": "0002",
                    "catalog_id": "{{catalog_id}}"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.1msg.io/docs/russkii/api-1msg/shablony-waba/shablon-karusel.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.