Skip to main content

Carousel Templates

  • Updated

 

Index:

  1. Introduction
  2. Creating the Carousel Template
  3. Sending the Carousel Template

 

Introduction

The carousel message type currently exists only as a template on the WhatsApp channel. The purpose of this document is to describe the Carousel Template and how to use them. This template allows you to send a single text message accompanied by a set of up to 10 Carousel Cards in a horizontal scrollable view.

Note: Since this is a template message type, sending the carousel is charged as an active notification, even if sent as dynamic content within the message flow.

 

Creating the Carousel Template

To create the Carousel Template, the following steps must be taken using the commands listed below, and to execute these commands, you will need your organization's command URL and API key. Click here to learn how to find them.

For illustration, the following template will be created:

1. Add media to be used in the template

The media to be used in the header of the cards must be uploaded beforehand to obtain the handler value, which will then be added when creating the template. The Blip platform will handle calling the Meta API and uploading the media. Here is the detailed command:

ORGANIZATION_ID: is the organization identifier.

YOUR_TOKEN: is your bot's authorization key.

 

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}
{
    "id": "{{$guid}}",
    "method": "set",    
    "to": "postmaster@wa.gw.msging.net",
    "type": "application/vnd.lime.media-link+json",
    "uri": "/message-templates-attachment",
    "resource": {
        "uri": "https://www.blip.ai/wp-content/uploads/2023/06/Blip_General_Thumb.png"
    }
}

The response to this call will contain media information, the most important of which is the fileHandle, which will be used in creating the template.

{
    "type": "application/json",
    "resource": {
        "uploadSessionId": "upload:MTphdHR………………",
        "fileHandle": "4::aW1hZ2UvcG5n:ARb4uJ6m………………..",
        "fileSize": "43122",
        "fileSizeUploaded": "43122"
    },
    "method": “set”,
    "status": “success”,
    "id": “{{$guid}}”,
    "from": “postmaster@wa.gw.msging.net/#msging-gateway-whatsapp”,,
    "to": “botid@msging.net/#msging-server”,
    "metadata": {
        "traceparent": "00-111ss26458-4f584a16e5tr4dd5d55d5d",
        "#command.uri": "lime://botid@msging.net/message-templates-attachment"
    }
}

2. Create Carousel Template

To create the carousel template, the following command should be sent:

ORGANIZATION_ID: is the organization identifier.

YOUR_TOKEN: is your bot's authorization key.

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}
{
    "id": "{{$guid}}",
    "method": "set", 
    "to": "postmaster@wa.gw.msging.net",
    "type": "application/json",
    "uri": "/message-templates",
    "resource": {
        "name": "<TEMPLATE_NAME>", 
        "language": "<TEMPLATE_LANGUAGE>", 
        "category": "<TEMPLATE_CATEGORY>",
        "components": [
    /* Message bubble, required */
        {
            "type": "BODY",
            "text": "<BUBBLE_TEXT>",
            "example": {
                           "body_text": [
                                             [
                                                 "<BUBBLE_TEXT_VAR_EXAMPLE_1>",
                                                 "<BUBBLE_TEXT_VAR_EXAMPLE_2>"
                                             ]
                                  ]
                        }
        },
    /* Carousel cards*/
        {
            "type": "CAROUSEL",
            "cards": [
    /* Begin first carousel card */
                   {
                          "components": [
                                 {
                                     "type": "HEADER",
                                     "format": "<CARD_HEADER_FORMAT>",
                                     "example": {
                                                     "header_handle": [
                                                     "<CARD_HEADER_HANDLE>"
                                                     ]
                                                 }
                                 },
                                 {
                                     "type": "BODY",
                                     "text": "<CARD_BODY_TEXT>",
                                     "example": {
                                                     "body_text": [
                                                           [
                                                                 "<CARD_BODY_TEXT_VAR_EXAMPLE_1>",
                                                                 "<CARD_BODY_TEXT_VAR_EXAMPLE_2>"
                                                           ]
                                                     ]
                                                }
                                 },
                                 /* At least one button required */
                                 {
                                     "type": "BUTTONS",
                                     "buttons": [
                                                   {
                                                        "type": "QUICK_REPLY",
                                                        "text": "<QUICK_REPLY_BUTTON_TEXT>"
                                                   },
                                                   {
                                                          "type": "URL",
                                                          "text": "<URL_BUTTON_TEXT>",
                                                           "url": "<URL_BUTTON_URL>",
                                                           "example": [
                                                                      "<URL_BUTTON_VAR_EXAMPLE>"
                                                             ]
                                                   }
                                               ]
                                 }
                ]
        },
    /* End first carousel card */
                ]
        }
     ]
  }
}

Template

  • TEMPLATE_NAME: name for carousel template.
  • TEMPLATE_LANGUAGE: Template language.
  • TEMPLATE_CATEGORY: Template category.

Message bubble

  • BUBBLE_TEXT: Text. Maximum 1024 characters.
  • BUBBLE_TEXT_VAR_EXAMPLE: Text values, representing variables that are replaced in BUBBLE_TEXT, if applicable. The number of variables should correspond to those included in BUBBLE_TEXT. Example:
{
    "type": "BODY",
    "text": "Use the coupon {{1}} to get discount in {{2}}",
    "example": {
                   "body_text": [
                                    [
                                        "NEWCLIENT",
                                        "SHOES"
                                    ]
                              ]
               }
}

 

Carousel cards

where each  cards  is defined as it will be presented.

  • CARD_HEADER_FORMAT: media format. Must be image or video. (image/video)
  • CARD_HEADER_HANDLE: fileHandle value, returned by Meta in the previous step request. 
  • CARD_BODY_TEXT: Card text, maximum 160 characters.
  • CARD_BODY_TEXT_VAR_EXAMPLE: Text values, referring to variables that are replaced in CARD_BODY_TEXT, if any. The number of variables should match those included in CARD_BODY_TEXT.

Card buttons. At least one is mandatory.

  • QUICK_REPLY_BUTTON_TEXT: quick reply button text. Maximum 25 characters.
  • URL_BUTTON_TEXT: URL label text. Supports only 1 variable. Maximum 25 characters. 
  • URL_BUTTON_URL: URL with parameters. Supports only 1 variable. Maximum 2000 characters.
  • URL_BUTTON_VAR_EXAMPLE: URL with example parameter filled, referring to variables that are replaced in URL_BUTTON_URL, if any. 

The response to this call will contain information such as the ID of the  carousel  template created and the  status of the request, if  successful, the template was created successfully.

{
    "type": "application/json",
    "resource": {
    "id": "1854……"
},
    "method": "set",
    "status": "success",
    "id": "{{$guid}}",
    "from": “postmaster@wa.gw.msging.net/#msging-gateway-whatsapp”,,
    "to": “botid@msging.net/#msging-server”,
    "metadata": {
    "traceparent": "00-9cee92d86c62fcc09189d6c61186d5b6-b0fcf66ee873c1b3-01",
    "#command.uri": "lime://botid@msging.net/message-templates"
  }
}

You still can't see your new template on Blip, but you'll be able to view your template created in the Wabas management.

 

Send Carousel Template

After the carousel template has been created, you can send the message containing the carousel. There are two ways to send it: as an active notification and within the builder flow using dynamic content. Remember that regardless of how it's sent, since it's a template, it will be charged as an active notification.

  1. Active Notification

To send active notifications, you must first execute the number verification command, as per the documentation.

ORGANIZATION_ID: is the organization identifier.

YOUR_TOKEN: is your bot's authorization key.

USER_PHONE_NUMBER: phone number of the user who will receive the carousel message template, as consulted in the documentation.

CAROUSEL_TEMPLATE_NAME: name of the carousel template that was created

POST https://{ORGANIZATION_ID}.http.msging.net/messages HTTP/1.1

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}
{
    "id": "{{$guid}}",
    "to": "{USER_PHONE_NUMBER}@wa.gw.msging.net",
    "type": "application/json",
    "content": {
        "type": "template",
        "template": {
            "name": "<TEMPLATE_NAME>",
            "language": {
                "code": "<TEMPLATE_LANGUAGE>"
            },
            "components": [
 /* Message bubble; can omit if template message bubble has no variables */
                {
                    "type": "BODY",
                    "parameters": [
                        {
                            "type": "TEXT",
                            "text": "20OFF"
                        },
                        {
                            "type": "TEXT",
                            "text": "20%"
                        }
                    ]
                },
/* Carousel cards */
                {
                    "type": "CAROUSEL",
                    "cards": [
                        {
                            "card_index": 0,
                            "components": [
                                {
                                    "type": "HEADER",
                                    "parameters": [
                                        {
/* Required if template uses image header, otherwise omit */
                                            "type": "IMAGE",
                                            "image": {
                                                "link": "https://www.blip.ai/wp-content/uploads/2023/06/Blip_General_Thumb.png"
                                            }
/* Required if template uses video header, otherwise omit */
                                            "type": "VIDEO",
                                            "video": {
                                                "id": "12345678978569"
                                            }
                                        }
                                    ]
                                },
/* Can be omitted if card body text in template has no variables */
                                {
                                    "type": "BODY",
                                    "parameters": [
                                        {
                                            "type": "TEXT",
                                            "text": "10OFF"
                                        },
                                        {
                                            "type": "TEXT",
                                            "text": "10%"
                                        }
                                    ]
                                },
                                {
                                    "type": "BUTTON",
                                    "sub_type": "QUICK_REPLY",
                                    "index": "0",
                                    "parameters": [
                                        {
                                            "type": "PAYLOAD",
                                            "payload": "59NqSd"
                                        }
                                    ]
                                },
                                {
                                    "type": "BUTTON",
                                    "sub_type": "URL",
                                    "index": "1",
                                    "parameters": [
                                        {
                                            "type": "PAYLOAD",
                                            "payload": "last_chance_2023"
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "card_index": 1,
                            "components": [
                                {
                                    "type": "HEADER",
                                    "parameters": [
                                        {
                                            "type": "IMAGE",
                                            "image": {
                                                "id": "24230790383178626"
                                            }
                                        }
                                    ]
                                },
                                {
                                    "type": "BODY",
                                    "parameters": [
                                        {
                                            "type": "TEXT",
                                            "text": "30OFF"
                                        },
                                        {
                                            "type": "TEXT",
                                            "text": "30%"
                                        }
                                    ]
                                },
                                {
                                    "type": "BUTTON",
                                    "sub_type": "QUICK_REPLY",
                                    "index": "0",
                                    "parameters": [
                                        {
                                            "type": "PAYLOAD",
                                            "payload": "7C4xhY"
                                        }
                                    ]
                                },
                                {
                                    "type": "BUTTON",
                                    "sub_type": "URL",
                                    "index": "1",
                                    "parameters": [
                                        {
                                            "type": "PAYLOAD",
                                            "payload": "summer_blues_2023"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

 

  1. As Dynamic Content

To send the carousel as dynamic content, you must add the dynamic content component to the flow, as per the documentation, where:

Type: application/json

Content: JSON, the same value assigned to the "content" field in the message sending request for active notification. Example: 

Note: Remember that even when set as dynamic content in the conversation flow, it will be billed as an active notification, as it is a template.

 

 

For more information, check out the discussion on this topic in our community or the videos on our channel.😃

Related articles