🚧
API token & Name space
Please refer to this page to fine the API Token and the name space: https://developer.cequens.com/reference/whatsapp-business-ver2

💡
Tip: Looking for example requests? Click the dropdown in the top-right corner of the "Request body" section to see pre-built examples you can use.

Overview

WhatsApp carousel templates are specialized message templates that display multiple cards (3-10 cards) that users can swipe through horizontally. Each card can contain:

An image header
Body text with variables
Interactive buttons (URL or quick reply)

Carousels are ideal for:

Product Catalogs: Showcase multiple products with images, descriptions, and purchase links
Service Offerings: Present different service packages or options
Event Promotions: Display multiple events or dates
Menu Items: Show food items, services, or offerings with details and ordering options

✅
No 24-Hour Window Restriction
Like all template messages, carousel templates can be sent at any time, even if the customer hasn't messaged you recently.

Before You Start

Create and Register Carousel Template: Carousel templates must be created and approved in WhatsApp Business Manager
Card Limit: Carousels must contain between 2 and 10 cards
Consistent Structure: All cards in a carousel must have the same component structure
Image Required: Each card must have an image header.

Components Structure

Carousel templates require two main components:

Body Component (optional): Text that appears above the carousel
Carousel Component: Contains the array of cards

Body Component (Optional)

{
    "type": "body",
    "parameters": [
        {
            "type": "text",
            "text": "Check out our latest collection"
        }
    ]
}

Carousel Component

Parameter	Type	Description	Required
type	string	Must be set to "carousel"	Yes
cards	array	Array of card objects (3-10 cards)	Yes

Card Object

Each card in the carousel contains:

Parameter	Type	Description	Required
card_index	integer	Index of the card (starting from 0)	Yes
components	array	Array of components for this card	Yes

Card Components

Each card must have the same structure with these components:

Header Component (required): Image for the card
Body Component (optional): Text with variables
Button Component (optional): URL or quick reply button

Card Header (Image)

{
    "type": "header",
    "parameters": [
        {
            "type": "image",
            "image": {
                "link": "https://example.com/product1.jpg"
            }
        }
    ]
}

Card Body

{
    "type": "body",
    "parameters": [
        {
            "type": "text",
            "text": "Product Name"
        },
        {
            "type": "text",
            "text": "$99.99"
        }
    ]
}

Card Button

{
    "type": "button",
    "sub_type": "URL",
    "index": "0",
    "parameters": [
        {
            "type": "text",
            "text": "https://example.com/product/12345"
        }
    ]
}

Common Errors and Troubleshooting

Error	Cause	Solution
Invalid card count	Less than 3 or more than 10 cards	Ensure carousel has 3-10 cards
Inconsistent card structure	Cards have different component structures	All cards must have identical component types
Missing image header	Card doesn't have image header	Each card must include an image header
Invalid card_index	Card indices not sequential or starting from wrong number	Start card_index from 0 and increment sequentially
Image download failed	Image URL not accessible	Ensure all image URLs are publicly accessible via HTTPS
Button URL parameter missing	Dynamic URL button missing parameter	Provide URL parameter for dynamic URL buttons

Carousel vs. Standard Templates

Feature	Standard Template	Carousel Template
Cards	Single message	3-10 swipeable cards
Images	Optional	Required for each card
Use Case	Single product/message	Multiple products/options
Buttons	Up to 3 buttons	1 button per card
Complexity	Simple	More complex structure
Best For	Single CTA	Product catalogs, comparisons