Carousel Templates

Carousel templates display a horizontally scrollable series of cards, each with its own image or video header, body text, and action buttons. They are ideal for showcasing multiple products, features, or options in a single message.

Block Structure

A carousel template uses a single whatsapp-carousel block that contains:

Component	Required	Description
Body text	Yes	Main message text displayed above the carousel (max 1024 characters)
Cards	Yes	2--10 cards, each with a header, body, and actions

All cards are defined inline in the template. Dynamic or hybrid card modes (using cardsType or cardsParameterKey) are available in the OpenAPI schema but are not supported for approved WhatsApp templates.

Here's how a carousel template renders on WhatsApp. The body text appears above the cards, and the next card peeks from the right to indicate swipeable content:

Swiping reveals the next card. Each card has its own image header, body text, and action buttons:

Carousel Card Structure

Each card is a whatsapp-carousel-card block:

Component	Required	Max	Description
Header	Yes	1	Image or video (file) -- all cards must use the same header type
Body	Yes	1	Card text (max 160 characters)
Actions	Yes	2	Link, reply, or phone number buttons

Card header

Each card requires an image or file (video) header. All cards within a carousel must use the same header type (all images or all videos).

Image header:

代码示例

{
  "type": "image",
  "image": {
    "mediaUrl": "https://example.com/images/product-1.jpg"
  }
}

Video header:

代码示例

{
  "type": "file",
  "file": {
    "mediaUrl": "https://example.com/videos/product-1.mp4",
    "contentType": "video/mp4"
  }
}

If you need to host media, use the Media Library API to upload files and get a mediaUrl. See Image Template Blocks -- Uploading media for the full upload flow.

Card body

Max 160 characters per card. Supports variables.

代码示例

{
  "type": "text",
  "text": {
    "text": "Premium leather wallet - {{price}}"
  }
}

Card actions

Each card supports 1--2 buttons. All cards must have the same number and types of action buttons.

代码示例

"actions": [
  {
    "type": "link-action",
    "linkAction": {
      "text": "View details",
      "url": "https://example.com/products/{{productId}}"
    }
  },
  {
    "type": "reply-action",
    "replyAction": {
      "text": "Add to cart",
      "payload": "add_to_cart_wallet"
    }
  }
]

Supported action types per card: link-action, reply-action, call-phone-number-action.

Complete Example

代码示例

{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "product_showcase"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "whatsapp-carousel",
          "whatsappCarousel": {
            "body": {
              "type": "text",
              "text": {
                "text": "Check out our latest arrivals! Swipe to browse."
              }
            },
            "cards": [
              {
                "type": "whatsapp-carousel-card",
                "whatsappCarouselCard": {
                  "header": {
                    "type": "image",
                    "image": {
                      "mediaUrl": "https://example.com/images/sneakers.jpg"
                    }
                  },
                  "body": {
                    "type": "text",
                    "text": {
                      "text": "Classic White Sneakers - $89.99"
                    }
                  },
                  "actions": [
                    {
                      "type": "link-action",
                      "linkAction": {
                        "text": "Shop now",
                        "url": "https://example.com/sneakers"
                      }
                    },
                    {
                      "type": "reply-action",
                      "replyAction": {
                        "text": "More info",
                        "payload": "info_sneakers"
                      }
                    }
                  ]
                }
              },
              {
                "type": "whatsapp-carousel-card",
                "whatsappCarouselCard": {
                  "header": {
                    "type": "image",
                    "image": {
                      "mediaUrl": "https://example.com/images/jacket.jpg"
                    }
                  },
                  "body": {
                    "type": "text",
                    "text": {
                      "text": "Denim Jacket - $129.99"
                    }
                  },
                  "actions": [
                    {
                      "type": "link-action",
                      "linkAction": {
                        "text": "Shop now",
                        "url": "https://example.com/jacket"
                      }
                    },
                    {
                      "type": "reply-action",
                      "replyAction": {
                        "text": "More info",
                        "payload": "info_jacket"
                      }
                    }
                  ]
                }
              },
              {
                "type": "whatsapp-carousel-card",
                "whatsappCarouselCard": {
                  "header": {
                    "type": "image",
                    "image": {
                      "mediaUrl": "https://example.com/images/backpack.jpg"
                    }
                  },
                  "body": {
                    "type": "text",
                    "text": {
                      "text": "Canvas Backpack - $59.99"
                    }
                  },
                  "actions": [
                    {
                      "type": "link-action",
                      "linkAction": {
                        "text": "Shop now",
                        "url": "https://example.com/backpack"
                      }
                    },
                    {
                      "type": "reply-action",
                      "replyAction": {
                        "text": "More info",
                        "payload": "info_backpack"
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"]
}

Constraints

Rule	Limit
Cards per carousel	2--10
Card body length	160 characters
Actions per card	1--2
Header type consistency	All cards must use the same header type (all images or all videos)
Action consistency	All cards must have the same number and types of buttons

Text Template Blocks -- Standard text templates
Multi-Product Template Blocks -- Product catalog browsing
Creating WhatsApp Message Templates -- Full template creation workflow