WhatsApp carousel message template

Use a WhatsApp carousel message template to send a marketing message with up to 10 media cards in a horizontally scrollable sequence through the Messaging API.

Each card can include media, text, and interactive buttons, enabling users to browse options, compare items, or navigate different actions without leaving the conversation.

Use this format to present structured, interactive content in a compact message. Common use cases include:

  • Product catalogs or featured items
  • Promotional events with multiple offers
  • Step-based navigation or guided experiences
  • Content discovery (articles, services, categories)

Carousel message template components

A carousel message template contains a message body and a set of media cards in one horizontally scrollable message. The carousel is defined as a collection of cards:

  • Minimum: 2 cards
  • Maximum: 10 cards

Place your highest-priority cards first because they receive the most visibility.

For the complete description of each component and how to create the message template, see WhatsApp carousel.

Message body

Define the message body once. It appears above the carousel, applies to the entire message, and can include personalized fields (placeholders).

Use only text, placeholders, markdown, and emojis. The body cannot exceed 1024 characters.

Card media header

Every card requires a media header, which appears first and provides the card's primary visual context. Each media header contains one image or video asset.

File typeSupported formatsMaximum file size
Image.jpeg, .jpg, .png5 MB
Video.mp416 MB
  • Images must be 8-bit, RGB or RGBA.
  • Video files must use the H.264 video codec.
  • Keep media headers consistent across all cards: use the same type and similar dimensions.
🚧

WARNING

When you update a card media header (image or video), use a new URL for the updated media file.

If you replace a media file on your server while keeping the same URL, Meta may continue using the previously cached version of the file instead of retrieving the updated resource. The cached version may remain available for more than 40 minutes.

Card body text

Each card can include optional body text below the media header to describe the card's content. Card body text can include personalized fields (placeholders). If one card includes body text, every card must include it.

Card buttons

Cards can include buttons for actions associated with the displayed item. Supported button types include Quick Reply, URL, and Phone number buttons. Each card can include up to 2 buttons.

Every card must use the same button structure: the same number of buttons, types, and order. For example, if one card uses a Quick Reply button followed by a URL button, every card must use that arrangement.

URL buttons can use a static link, which is the same for all recipients, or a dynamic link, which includes a URL suffix value that you replace when you send the message template.

🚧

WARNING

WhatsApp does not allow direct links to WhatsApp in Call-to-Action buttons. Card buttons can only open external websites. If you need to share a WhatsApp link (for example, a wa.me link), include it directly in the message body instead of using a button.

Before you begin

  1. Create the carousel message template in Communications Platform by following Personalize WhatsApp carousel message template, or use the Message Templates API.
  2. Set the message template category to Marketing.
  3. Submit the message template for WhatsApp approval from Communications Platform.
  4. Allow up to 48 hours for WhatsApp to review the message template.
  5. After WhatsApp approves the message template, send it with the Messaging API.
🚧

WARNING

Carousel cards must follow the same internal structure across the entire message template. You cannot add optional components to only some cards and omit them from others.

For example, if one card includes body text, all the remaining cards must include it. The same rule applies to buttons: all cards must define the same number of buttons, using the same button types and in the same order.

WhatsApp validates carousel cards as repeated instances of a single card structure. If one card differs from the others in its component layout, WhatsApp may reject the message template or it may render incorrectly.

Send a carousel message template

When you send a carousel message template, include runtime values only for the placeholders, media headers, and dynamic URL buttons defined in the approved message template. Use each button's original position index when you provide a dynamic URL value.

📘

NOTE

To learn about delivery throughput and how TPS is applied across channels (WhatsApp), go to the Message throughput and rate limits section.

🚧

WARNING

You cannot edit or modify static components, such as phone numbers, static URLs, or Quick Reply buttons, when you send the carousel message template, because these values were already approved by Meta when the message template was created. For this reason, Quick Reply buttons and static URL buttons are not included in the send request.

You can only provide dynamic values for:

  • The card media header (image or video).
  • The placeholders in the message body and in the card body text.
  • The dynamic URL buttons (URL suffix values).

If the message body or the card body text does not include placeholders, you must not include them in the send request body.

Identify the message template

Send the message template in one of two ways inside the request object:

  • Include only the unique identifier of the message template. You get this ID in the response once the message template has been created.
{
  "templateId": "4567890987654",
  "from": "1000000001",
  "to": "+1000000002"
}
  • Include only the name and language of the message template.
{
  "templateName": "carousel_demo_template",
  "templateLanguage": "en",
  "from": "1000000001",
  "to": "+1000000002"
}
📘

Priority handling

If you send the ID, name, and language together in one request body, the platform gives priority to the ID. It does not use the name and language in this case.

Replying to a user with a reserved username

The userId from the webhook payload isn't just an identifier for display: you can send message templates directly to it. That means you can reply to a reserved-username user without ever learning their phone number.

A message template addresses the recipient by phone number, using to:

{
  "templateId": "4567890987654",
  "from": "1000000001",
  "to": "+1000000002"
}

To reply to a reserved-username user, replace to with recipient, and set its value to the userId from the webhook payload:

{
  "templateId": "4567890987654",
  "from": "1000000001",
  "recipient": "MX.24983"
}
🚧

WARNING

If the request body includes both to and recipient parameters, Meta always prioritizes the to parameter and delivers to that phone number. The recipient parameter is only used when to is absent.

📘

NOTE

Messages sent through recipient instead of to carry that same identifier into reporting: in Messaging Logs, the Recipient column shows the userId rather than a phone number for that outgoing message.

Personalized fields (placeholders)

Use placeholders in the send request only when you defined personalized fields when you created the message template.

Message body (placeholder value)

If your message template includes placeholders in the message body, include their values in the request object:

"placeholders": {
    "name": "Elizabeth",
    "lastName": "Smith"
}

In the "placeholders" object, use the placeholder name that you configured inside double curly braces {{...}} when you created the carousel message template as the parameter key. Then set the value of the placeholder.

For instance, according to the previous example, the message body of the created carousel message template is as follows:

{
  "type": "BODY",
  "text": "Welcome {{name}} {{lastName}} we have a new offer for you!",
  "example": {
    "body_text": [
      [
        "Elizabeth",
        "Smith"
      ]
    ]
  }
}

The placeholders must be correctly formatted, in the same order in which the message template was created.

Card media header (value)

When the carousel message template includes a media file (image or video) in the card media header, the example payload JSON is as follows:

{
  "cards": [
    {
      "cardIndex": 0,
      "templateHeader": {
        "type": "image",
        "url": "https://example.com?media=image.png"
      }
    }
  ]
}

The "cards.templateHeader.type" parameter includes the header type chosen when you created the carousel message template, in lower case: "image" or "video". Enter the URL of the chosen media in the "cards.templateHeader.url" parameter. In the previous example, the media type is an image.

Card body text (placeholder value)

If your message template includes placeholders in the card body text, include their values in the corresponding card:

{
  "cards": [
    {
      "cardIndex": 0,
      "placeholders": {
        "name": "Julian",
        "date": "02/02/2025"
      }
    }
  ]
}

In the "cards.placeholders" object, use the placeholder name that you configured inside double curly braces {{...}} when you created the message template as the parameter key. Then set the value of the placeholder.

For instance, according to the previous example, the card body text of the created carousel message template is as follows:

{
  "cards": [
    {
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{name}}, would you like to schedule your visit on {{date}}?",
          "example": {
            "body_text": [
              [
                "Julian",
                "02/02/2025"
              ]
            ]
          }
        }
      ]
    }
  ]
}

The placeholders must be correctly formatted, in the same order in which the message template was created.

Position index (buttons)

If your message template includes card buttons with dynamic URLs, provide the dynamic URL value by button position. This send request includes a dynamic URL (cta) button in a carousel card:

{
  "cards": [
    {
      "cardIndex": 0,
      "templateButtons": [
        {
          "type": "cta",
          "values": [
            {
              "index": 1,
              "value": "user-71421"
            }
          ]
        }
      ]
    }
  ]
}

The "cards.templateButtons.values.index" parameter indicates the position index of the button, as it was defined when you created the carousel message template (0, 1). To clarify the position index, review the position of the buttons in the request body used to create the message template:

{
  "cards": [
    {
      "components": [
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "QUICK_REPLY",
              "text": "Accept"
            },
            {
              "type": "URL",
              "text": "New Offer",
              "url": "https://www.elipackagedomain.com/{{offer}}",
              "example": [
                "https://www.elipackagedomain.com/user-71421"
              ]
            }
          ]
        }
      ]
    }
  ]
}

In this example:

  • The Quick Reply button with the keyword "Accept" is in the first position (0).
  • The dynamic URL button is in the second position (1).

Maintain these button position indexes when you send the message template. The "cards.templateButtons.values.value" parameter contains the URL suffix value defined for the dynamic URL button. The platform propagates the URL suffix as an extension of the registered URL address.

🚧

WARNING

The personalized fields (placeholders) you set when you created the carousel message template are editable when you send it.

When you create the message template, only provide example placeholder values for each component if the message template includes placeholders. This helps Meta understand what kind of message you plan to send during the review and approval process. Make sure these are examples and do not include any confidential or personal information.

Once the message template is approved and ready to be sent, replace the placeholders with the actual (real) placeholder values.

Dynamic URLs (card buttons)

Use dynamic URLs to provide each recipient with a personalized button destination. Define the dynamic portion as a placeholder (URL suffix) when you create the message template, then provide its value (URL suffix value) when you send it.

Creating the carousel message template

When you create a carousel message template with a dynamic URL button, you specify the URL suffix in the "url" parameter of the card button. This is an example of how the payload might look during message template creation:

{
  "cards": [
    {
      "components": [
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "URL",
              "text": "To locate your order, click Here!",
              "url": "https://www.packageorders.com/{{order}}",
              "example": [
                "https://www.packageorders.com/hj07taw12"
              ]
            }
          ]
        }
      ]
    }
  ]
}

In this payload:

  • "url": Includes a URL suffix ({{order}}) for the dynamic portion of the URL.
  • "example": Provides a sample of the final URL after replacing the URL suffix with a URL suffix value (for example, "hj07taw12").

Sending the carousel message template

When you send the carousel message template, you must replace the URL suffix ({{order}}) with an actual value (URL suffix value) in the payload. The payload includes the "templateButtons" field, which specifies the type of button for dynamic URLs ("cta") and the URL suffix value ("hj07taw12"):

{
  "cards": [
    {
      "cardIndex": 0,
      "templateButtons": [
        {
          "type": "cta",
          "values": [
            {
              "index": 0,
              "value": "hj07taw12"
            }
          ]
        }
      ]
    }
  ]
}

In this payload:

  • type: Indicates a call-to-action (cta) button.
  • index: Specifies the position of the button in the message template. In this example, the dynamic URL button was placed in the first position when the message template was created, so the index is 0.
  • value: Provides the actual URL suffix value to replace the URL suffix.

This dynamic URL system enables personalized and actionable buttons tailored to each recipient, improving engagement and usability.

Request

After you create and get approval for the carousel message template, send it with the Messaging API. Send a POST request to POST /notification with the following body:

{
  "channel": "WHATSAPP",
  "request": {
    "from": "525500000000",
    "to": "+525511111111",
    "templateName": "carousel_demo_template",
    "templateLanguage": "en",
    "type": "carousel",
    "placeholders": {
      "customer_name": "John"
    },
    "cards": [
      {
        "cardIndex": 0,
        "templateHeader": {
          "type": "image",
          "url": "https://example.com/image1.png"
        },
        "placeholders": {
          "order_id": "#12345",
          "order_date": "March 10"
        },
        "templateButtons": [
          {
            "type": "cta",
            "values": [
              {
                "index": 1,
                "value": "12345"
              }
            ]
          }
        ]
      },
      {
        "cardIndex": 1,
        "templateHeader": {
          "type": "image",
          "url": "https://example.com/image2.png"
        }
      }
    ]
  },
  "callbacks": [
    "http://www.mycallback.com?id=123"
  ]
}

In this example, only the placeholders from the message body and the card body text, the card media header (image), and the dynamic URL button with its URL suffix value were included in the send request body, because only these elements require personalized values at runtime.

Although the message template may define Quick Reply buttons, or a static URL button, they are not included in the send request, because they do not require dynamic values and were already approved as part of the message template structure by Meta. Likewise, if the message body or the card body text does not contain placeholders, do not include them in the send request body.

The send request contains two main sections:

  • Main parameters: Outline the essential information needed to send a carousel message template: the message template, the sender and recipient, the language, and the placeholders for the message body, only if you defined them when you created the message template.
  • Carousel cards parameters: Define the only fields that you can include in the request body to customize a carousel message template at send time. These parameters apply exclusively when the message template includes the card media header (image or video), placeholders in the card body text, and URL suffix values for dynamic URL buttons. No other components should be provided in the request payload.

Main parameters

Parameter Required Description
channel Yes

Specifies the type of delivery channel through which the notification message will be sent: "SMS", "EMAIL", "RCS", "WHATSAPP".

In this case, enter the "WHATSAPP" value to send the WhatsApp message.

request Yes

Message content.

request.
from
Yes

Phone number of the sender.

The phone number provided during the WABA account setup is used as the sender of the notification message.

Only numeric characters are accepted. Do not include the "+" sign.

request.
to
Conditional

Determines the destination phone number for your message. Numbers are specified in E.164 format → ('+' and a country code).

Required if you do not send recipient. If both to and recipient are included, to takes priority.

request.
recipient
Conditional

Identifies a recipient with a reserved username, using the userId value from their webhook payload instead of a phone number.

Use this instead of to when the recipient's phone number is not available. If both to and recipient are included, to takes priority.

Required if you do not send to. For more information, see Reserved usernames.

request.
templateId
Conditional

Unique identifier of the message template. You get this ID in the response once the message template has been created.

Send it instead of templateName and templateLanguage. If templateId, templateName and templateLanguage are all included, templateId takes priority and the name and language are not used.

Required if you do not send templateName and templateLanguage.

request.
templateName
Conditional

Name of the message template created in your WhatsApp Business Account.

Required if you do not send templateId.

request.
templateLanguage
Conditional

Message template language you set when creating the message template. Currently, the API supports 3 languages: English, Spanish, and Portuguese. Required if you want to send message templates in languages other than English.

  • English: "en"
  • Spanish: "es"
  • Portuguese: "pt_BR", "pt_PT"

Required if you do not send templateId.

request.
type
Yes

Specifies the type of message template being sent. For carousel message templates, this value must be set to "carousel".

request.
placeholders
Conditional

Only applies if the "BODY" type (Message Body) contains personalized fields (placeholders).

Object of personalized fields (placeholders) containing the message body. In the placeholders object, use the placeholder name that you configured inside double curly braces {{...}} when creating the message template as the parameter key, and set its value to the text that replaces the placeholder. The placeholders must be correctly formatted, in the same order as they appear in the message template.

For example, for a message body like Here is your {{code}}, you would set the placeholder as "code": "34871".

request.
externalId
No

Alphanumeric identifier used for reporting purposes.

request.
clientId
No

Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.

callbacks No

Indicate one or more webhook URLs to notify about the status of the message delivery. That is, if you want to receive the status of the message you've sent to your contacts, you need to specify your endpoint.

Your endpoint must have a HTTP POST access method and receive a JSON body.

The URL is the external callback where the events of the message will be registered and published. Once a message is processed, its status will be posted to your callback URL.

To view the full list and meaning of each status, please refer to the WhatsApp Status section.

Carousel cards parameters

The Required column of a nested parameter applies when you send its parent object.

Parameter Required Description
request.
cards
Yes

Array that defines the content of each card in the carousel at send time. Each object in this array corresponds to a card defined in the message template and must follow the same order.

request.
cards.
cardIndex
Yes

Specifies the position of the card within the carousel. This value is zero-based, meaning the first card starts at 0, the second at 1, and so on.

Each cardIndex must match the order in which the cards were defined in the approved template, ensuring that the correct content, placeholders, and dynamic values are applied to the corresponding card.

request.
cards.
templateHeader
Yes

Only applies if the carousel message template created contains the "HEADER" type (Card Media Header).

Defines the media content (Image or Video) chosen when creating the message template.

request.
cards.
templateHeader.
type
Yes

Only applies if the carousel message template created contains the "HEADER" type (Card Media Header).

Enter the media header option chosen when creating the message template in lower case: "image", "video".

request.
cards.
templateHeader.
url
Yes

Only applies if the carousel message template created contains the "HEADER" type (Card Media Header).

If you set the Video or Image as Media Header option when creating the message template, enter the URL of the chosen media.

The URL of the card media header (image or video) must be a valid URL that starts with "https://…" and provides a direct download. Redirects are not supported.

request.
cards.
placeholders
Conditional

Only applies if the "BODY" type (Card Body Text) contains personalized fields (placeholders).

Object of personalized fields (placeholders) containing the card body text. In the placeholders object, use the placeholder name that you configured inside double curly braces {{...}} when creating the message template as the parameter key, and set its value to the text that replaces the placeholder. The placeholders must be correctly formatted, in the same order as they appear in the message template.

For example, for a body text like Here is your {{code}}, you would set the placeholder as "code": "34871".

request.
cards.
templateButtons
Conditional

Only applies if the message template created contains the "BUTTONS" type (card buttons) with a Dynamic URL.

Array of card button objects used to provide URL suffix values for dynamic URL buttons defined in the message template.

Quick Reply card buttons and static URL card buttons must not be included in the send request body, as they are already part of the approved message template structure.

request.
cards.
templateButtons.
type
Yes

Only applies if the message template created contains the "BUTTONS" type (card buttons) with a Dynamic URL.

Specifies the type of dynamic button being sent. For dynamic URL card buttons, this value must be set to "cta".

request.
cards.
templateButtons.
values
Yes

Only applies if the message template created contains the "BUTTONS" type (card buttons) with a Dynamic URL.

Array of values (URL suffix value) used to replace the URL suffix defined in the dynamic URL button.

request.
cards.
templateButtons.
values.
index
Yes

Only applies if the message template created contains the "BUTTONS" type (card buttons) with a Dynamic URL.

The index parameter specifies the position of a button as defined during the message template creation process. This index determines the order of the buttons within the message template and is crucial for correctly mapping the button actions when sending the message template.

The index value corresponds to the button's position in the message template, starting from 0 for the first button, 1 for the second.

The order defined during message template creation must be maintained when sending the message template.

For detailed information on setting the position index of the button when sending WhatsApp carousel message templates, refer to Position index (buttons).

request.
cards.
templateButtons.
values.
value
Yes

Only applies if the message template created contains the "BUTTONS" type (card buttons) with a Dynamic URL.

Enter the URL suffix value to replace the URL suffix in the dynamic URL. This URL suffix value corresponds to the dynamic portion of the URL suffix defined during the message template creation process.

Remember, dynamic URLs in WhatsApp message templates allow for the inclusion of personalized links in buttons, making it possible to provide unique URLs for each recipient. These dynamic URLs are defined using the (URL suffix) (e.g., {{orderID}}), which is replaced with the actual value (URL suffix value) (e.g., "141518") when sending the message template.

For detailed information on setting dynamic URLs when sending WhatsApp carousel message templates, refer to Dynamic URLs (card buttons).

Response

When you send a carousel message template, the response body contains the following data:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

The following table describes the response body parameters:

Parameter Description
meta "meta" segment is dedicated to metadata regarding the call itself.
meta.
timestamp

Call’s time mark.

Sequence of characters identifying when the message has been sent.

meta.
transactionId
Call’s transaction ID, this will help our teams to locate issues faster if arose.
meta.
explain
Useful message regarding the operation or the call.