# Carousel template

## Overview  <a href="#description" id="description"></a>

The Carousel template supports two sending formats:

### **Carousel with custom product cards** <a href="#carousel-with-custom-product-cards" id="carousel-with-custom-product-cards"></a>

Maximum flexibility for your use case. Best when you need customization and marketing freedom.

* You define the carousel: number of cards, texts, variables, and buttons
* On send, you supply images and variable values
* Good for custom promotions, special offers, and segment-specific content
* Full control over look and copy of each card

<figure><img src="https://111670956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoRFlPIfSV1Te1UpyuEbn%2Fuploads%2FztAdIn6fXHgcd2vKVTZe%2Fimage.png?alt=media&#x26;token=5770f088-1f12-4503-b3e4-dda5519c3b6b" alt=""><figcaption></figcaption></figure>

***

### **Carousel with product cards from your WhatsApp Catalog** <a href="#carousel-with-product-cards-from-your-whatsapp-catalog" id="carousel-with-product-cards-from-your-whatsapp-catalog"></a>

Fast, automatic, and fewer errors. Best for large sends and regular sales.

* Cards are pulled from your WhatsApp Catalog
* No manual descriptions, images, or button setup
* Data is always up to date: price, name, description, images
* Less manual work and fewer send mistakes

<figure><img src="https://111670956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoRFlPIfSV1Te1UpyuEbn%2Fuploads%2F0VtcMLIo50IYZQ1JpdAr%2Fimage.png?alt=media&#x26;token=5d053cf8-1c2c-4f1e-b009-fee4423cc776" alt=""><figcaption></figcaption></figure>

***

### Description

Carousel templates allow you to send a single text message (1), accompanied by a set of up to 10 carousel cards (2) in a horizontally scrollable view.

The template can be viewed by users both from mobile devices and in the WhatsApp web client.

**Basic rules for creating a template:**

1. A message bubble (1) is required. Message bubbles are text-only and support variables in it.&#x20;
2. Carousel templates support up to 10 carousel cards.
3. The media header format and button types must be the same for all cards.
4. Cards must have a mandatory media header (image or video) and card body text
5. Card should at least have 1 button. Template supports a maximum of up to 2 buttons for each card.
6. The button types supported are Quick Reply, Website URL CTA & Call Phone Number CTA. Buttons can be the same type or a mix of Quick reply buttons, phone number buttons, or URL buttons for each card.

### **Ways to send Carousel**

Carousel can be sent in two ways:

* [**Via a template** ](#send-a-carousel-template)**(Template message)** — used for sending **outside the 24-hour window**. Requires prior creation and approval of the WhatsApp template. Sending is **paid**.
* [**As a service message**](#sending-the-carousel-as-a-service-message) — used **within the 24-hour conversation window**. No template is required. Sending is **free**.

## Create a template

Creating a template is described in [the API documentation](https://my.1msg.io/documentation/1msg) in the /addTemplate method.

The difference from the basic template creation is the addition of a new CAROUSEL type to the components and cards array..

You can also create a template from the 'Dev Toolkit' →[ 'Test requests'](https://my.1msg.io/testing/test-requests) section of your personal cabinet. The example below was created using this section. Don't forget to specify examples of variables if you have added them to the body, link URL of buttons. Otherwise the template will be rejected by Meta\*.

<details>

<summary>Example of creating a Carousel template</summary>

The links are test links, be sure to use the correct ones when copying. The filling example is taken from the 360Dialog source.

```json
POST https://api.1msg.io/{{channel}}/addTemplate
Content-Type: application/json
Body: {
  "name": "marketing_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%"
          ]
        ]
      }
    },
     /* Carousel cards */
    {
      "type": "CAROUSEL" // new type for Carousel template
      "cards": [ 
        {
        /* First carousel card */
          "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"
                  ]
                }
              ]
            }
          ]
        },
       /* Second carousel card */
        {
          "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>Example of creating a Carousel template with WhatsApp Catalog product cards</summary>

*Example are for testing; replace with real ones. Product IDs are filled when sending the template.*

```json
POST https://api.1msg.io/{{channel}}/addTemplate
Content-Type: application/json

{
   "name": "marketing_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": [
        {
          "components": [
            { "type": "HEADER", "format": "PRODUCT" },
            {
              "type": "BUTTONS",
              "buttons": [{ "type": "SPM", "text": "View" }]
            }
          ]
        },
        {
          "components": [
            { "type": "HEADER", "format": "PRODUCT" },
            {
              "type": "BUTTONS",
              "buttons": [{ "type": "SPM", "text": "View" }]
            }
          ]
        }
      ]
    }
  ]
}
```

</details>

<table><thead><tr><th width="287">Placeholder</th><th width="279">Description</th><th>Example Value</th></tr></thead><tbody><tr><td><p>BUBBLE_TEXT</p><p>String</p></td><td><p><strong>Required</strong>..<br></p><p>Message bubble text string. Supports variables.<br></p><p>Maximum 1024 characters.</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><strong>Required</strong> if the message bubble text string uses variables.<br></p><p>Array of example variable strings. Number of strings must match the number of variables included in the string.</p></td><td>"15OFF","15%"</td></tr><tr><td><p>CARD_BODY_TEXT</p><p>String</p></td><td><p><strong>Required</strong>.</p><p></p><p>Card body text. Support variables.<br></p><p>Maximum 160 characters.</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><p><strong>Required</strong> if using card body text with variables.</p><p><br></p><p>Card body text example variables.</p></td><td>"15OFF","15%"</td></tr><tr><td><p>CARD_HEADER_FORMAT</p><p>Enum</p></td><td><p><strong>Required</strong>.</p><p>Card media header format. Must be IMAGE or VIDEO.</p></td><td>IMAGE</td></tr><tr><td>CARD_HEADER_HANDLE</td><td><strong>Required</strong>.</td><td></td></tr><tr><td><p>QUICK_REPLY_BUTTON_TEXT</p><p>String</p></td><td><p><strong>Required</strong> if using a quick reply button.<br></p><p>Quick reply button label text.<br></p><p>Maximum 25 characters.</p></td><td>Send more like this #2</td></tr><tr><td><p>TEMPLATE_CATEGORY</p><p>Enum</p></td><td><p><strong>Required</strong>.</p><p>Must be MARKETING or UTILITY.</p></td><td>MARKETING</td></tr><tr><td><p>TEMPLATE_LANGUAGE</p><p>Enum</p></td><td><p><strong>Required</strong>.</p><p>Template language and locale code.</p></td><td>en</td></tr><tr><td><p>TEMPLATE_NAME</p><p>String</p></td><td><p><strong>Required</strong>.</p><p>Template name.</p><p>Maximum 512 characters.</p></td><td>marceting_carousel_01_test</td></tr><tr><td><p>URL_BUTTON_TEXT</p><p>String</p></td><td><p><strong>Required</strong> if using a URL button.</p><p>URL button label text. </p><p>25 characters maximum.</p></td><td>Buy now</td></tr><tr><td><p>URL_BUTTON_URL</p><p>String</p></td><td><p><strong>Required</strong> if using a URL button.</p><p></p><p>URL of website that loads in the device's default mobile web browser when the URL button is tapped by the app user.</p><p></p><p>Supports 1 variable, appended to the end of the URL string.</p><p></p><p>Maximum 2000 characters.</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><strong>Required</strong> if using a URL button.</p><p></p><p>URL of website. Supports 1 variable.</p><p></p><p>If using a variable, add sample variable property to the end of the URL string. The URL loads in the device's default mobile web browser when the customer taps the URL button.</p><p></p><p>Maximum 2000 characters.</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>

***

## Send a Carousel

### Send a Carousel template

Carousel template:

* Has its own type - CAROUSEL
* An object with type CAROUSEL contains an array of cards. It is used only for this template type
* Each card contains card\_index - the order of appearance of cards in the card carousel. 0 - means the first card, 1 - means the second card, etc.

<details>

<summary>Example of how to send the ‘Carousel’ template</summary>

An example of a 2-card template. Each card contains a quick reply button and a url button. The media header is an image.

```json
POST https://api.1msg.io/{{channel}}/sendTemplate
Content-Type: application/json
Body: {
  "token": "{{token}}",
  "namespace": "{{namespace}}", // Call the list of templates via the /templates method and find the namespace for the required template
  "template": "marceting_carousel_01_test", // name template
  "language": {
    "policy": "deterministic",
    "code": "en" // language from the /templates method
  },
  "params": [
    {
   /* /* Common text message. Can be omitted if there are no variables in the text. */ */
      "type": "body", 
      "parameters": [
        {
          "type": "text",
          "text": "21OFF" // variable {{1}}
        },
        {
          "type": "text",
          "text": "21" // variable {{2}}
        }
      ]
    },
    {
      "type": "carousel",
      "cards": [
        /* The first card */
        {
          "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,  // button position, starting from 0. Here url-button is the second in the sequence, so index=1
              "parameters": [
                {
                  "type": "text",
                  "text": "summer" // parameter in url link
                }
              ]
            },
            {
             /* Card text. Can be omitted if there are no variables in the text. */
              "parameters": [
                {
                  "type": "text",
                  "text": "10F" // variable {{1}} in the first card
                },
                {
                  "type": "text",
                  "text": "10" // variable {{2}} in the first card
                }
              ]
            }
          ]
        },
        /* Вторая карточка */
        {
          "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, // button position, starting from 0. Here url-button is the second in the sequence, so index=1
              "parameters": [
                {
                  "type": "text",
                  "text": "winter" // parameter in url link
                }
              ]
            },
            {
               /* Card text. Can be omitted if there are no variables in the text. */
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "30F" // variable {{1}} in the second card
                },
                {
                  "type": "text",
                  "text": "30" // variable {{2}} in the second card
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "phone": "+556123122026"
}
```

</details>

<details>

<summary>Example of how to send the ‘Carousel’ template with WhatsApp Catalog product cards</summary>

An example of a 2-card template.

```json
POST https://api.1msg.io/{{channel}}/sendTemplate
Content-Type: application/json

{
  "namespace": "{{namespace}}",
  "template": "marketing_carousel_01_test",
  "language": { "policy": "deterministic", "code": "en" },
  "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>

***

### Send a Carousel as a service message <a href="#sending-the-carousel-as-a-service-message" id="sending-the-carousel-as-a-service-message"></a>

To send a Carousel **as a service message** (without a pre-created Meta template), use the **`/sendCarousel`** method in [the API documentation](https://docs.1msg.io/#tag/Messaging/operation/sendCarousel) .

You do **not** need to create a Meta template in advance.

The payload is similar to template sending, but you must **specify all elements explicitly**, because the message is sent **without a template**.

<details>

<summary>Example: Sending a Carousel via /sendCarousel (custom cards)</summary>

2 cards. Each card: 2 Quick Reply buttons. Header: image.

```json
POST https://api.1msg.io/{{channel}}/sendCarousel
Content-Type: application/json

{
  "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": "Button", "id": "Buttons1" },
                { "text": "Button 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": "Button", "id": "Button3" },
                { "text": "Button 2", "id": "Button4" }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

</details>

<details>

<summary>Example: Sending a Carousel via /sendCarousel with WhatsApp Catalog product cards</summary>

2 product cards from the WhatsApp Catalog.

```json
POST https://api.1msg.io/{{channel}}/sendCarousel
Content-Type: application/json

{
  "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>
