> ## Documentation Index
> Fetch the complete documentation index at: https://whatsapp-docs.kap.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive media carousel messages

# Interactive media carousel messages

Updated: Oct 21, 2025

This message type will be available for delivery to WhatsApp users on November 11.

The interactive media carousel message enables businesses to send horizontally scrollable cards with images or videos, each with a call-to-action button, within WhatsApp conversations. This format allows users to browse multiple offers or content in a single message, providing a rich and engaging experience via the WhatsApp Business APIs and mobile clients.

## How to build a media carousel message

The media carousel message contains a `card` object. You must add at least 2 card objects to your message, and can add a maximum of 10. Each card exists in a `cards[]` array and must be given a `card_index` value of `0` through `9`.

The type of each card must be set to `"cta_url"`, and all cards must have the same header type (`"image"` or `"video"`). Each card must include a header, a unique index, and a call-to-action button with display text and a URL.

You must add a message body to the message (max 1024 characters). No header, footer, or buttons are allowed outside the cards.

### The `card` object

```
...
\{
  "card_index": 0,
  "type": "cta_url",
  "header": {
    "type": "image",
    "image": {
      "link": "https://example.com/image1.png"
    }
  },
  "body": {
    "text": "Exclusive deal #1"
  },
  "action": {
    "name": "cta_url",
    "parameters": {
      "display_text": "Shop now",
      "url": "https://shop.example.com/deal1"
    }
  }
}
...
```

## Request Syntax

```
curl 'https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "<PHONE_NUMBER>",
    "type": "interactive",
    "interactive": {
      "type": "carousel",
      "body": {
        "text": "Check out our latest offers!"
      },
      "action": {
        "cards": [\
          {\
            "card_index": 0,\
            "type": "cta_url",\
            "header": {\
              "type": "image",\
              "image": {\
                "link": "https://example.com/image1.png"\
              }\
            },\
            "body": {\
              "text": "Exclusive deal #1"\
            },\
            "action": {\
              "name": "cta_url",\
              "parameters": {\
                "display_text": "Shop now",\
                "url": "https://shop.example.com/deal1"\
              }\
            }\
          },\
          {\
            "card_index": 1,\
            "type": "cta_url",\
            "header": {\
              "type": "image",\
              "image": {\
                "link": "https://example.com/image2.png"\
              }\
            },\
            "body": {\
              "text": "Exclusive deal #2"\
            },\
            "action": {\
              "name": "cta_url",\
              "parameters": {\
                "display_text": "Shop now",\
                "url": "https://shop.example.com/deal2"\
              }\
            }\
          }\
        ]
      }
    }
  }'
```

## Request parameters

| Field                                                     | Description                                         | Sample Value                   |
| --------------------------------------------------------- | --------------------------------------------------- | ------------------------------ |
| `&lt;API_VERSION&gt;`<br />*String*                       | **Required**<br />API version to use                | `v19.0`                        |
| `&lt;WHATSAPP_BUSINESS_PHONE_NUMBER_ID&gt;`<br />*String* | **Required**<br />WhatsApp Business phone number ID | `1234567890`                   |
| `&lt;ACCESS_TOKEN&gt;`<br />*String*                      | **Required**<br />Access token for authentication   | `EAAG...`                      |
| `&lt;PHONE_NUMBER&gt;`<br />*String*                      | Recipient’s WhatsApp phone number                   | `16505551234`                  |
| `&lt;MESSAGE_BODY_TEXT&gt;`<br />*String*                 | **Required.** Maximum 1024 characters.              | `Check out our latest offers!` |

## Card Object Parameters

| Field                                          | Description                                                      | Sample Value                       |
| ---------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------- |
| `card_index`<br />*Integer*                    | **Required**<br />Unique index for each card (0-9).              | `0`                                |
| `type`<br />*String*                           | **Required**<br />Must be `"cta_url"`.                           | `"cta_url"`                        |
| `header.type`<br />*String*                    | **Required**<br />`"image"` or `"video"` (all cards must match). | `"image"`                          |
| `header.image.link`<br />*String*              | Required if header.type is `"image"`.                            | `"https://example.com/image1.png"` |
| `header.video.link`<br />*String*              | Required if header.type is `"video"`.                            | `"https://example.com/video1.png"` |
| `body.text`<br />*String*                      | *Optional*<br />Max 160 chars, and up to 2 line breaks.          | `"Exclusive deal #1"`              |
| `action.name`<br />*String*                    | **Required**<br />Must be `"cta_url"`.                           | `"cta_url"`                        |
| `action.parameters.display_text`<br />*String* | Button display text. Max 20 chars.                               | `"Shop now"`                       |
| `action.parameters.url`<br />*String*          | Button URL                                                       | `"https://shop.example.com/deal1"` |

## Example Request

```
\{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "1234567890",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Check out our latest offers!"
    },
    "action": {
      "cards": [\
        {\
          "card_index": 0,\
          "type": "cta_url",\
          "header": {\
            "type": "image",\
            "image": {\
              "link": "https://example.com/image1.png"\
            }\
          },\
          "body": {\
            "text": "Exclusive deal #1"\
          },\
          "action": {\
            "name": "cta_url",\
            "parameters": {\
              "display_text": "Shop now",\
              "url": "https://shop.example.com/deal1"\
            }\
          }\
        },\
        {\
          "card_index": 1,\
          "type": "cta_url",\
          "header": {\
            "type": "image",\
            "image": {\
              "link": "https://example.com/image2.png"\
            }\
          },\
          "body": {\
            "text": "Exclusive deal #2"\
          },\
          "action": {\
            "name": "cta_url",\
            "parameters": {\
              "display_text": "Shop now",\
              "url": "https://shop.example.com/deal2"\
            }\
          }\
        }\
      ]
    }
  }
}
```

## Example Response

```
\{
  "messaging_product": "whatsapp",
  "contacts": [\
    {\
      "input": "+16505551234",\
      "wa_id": "16505551234"\
    }\
  ],
  "messages": [\
    {\
      "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"\
    }\
  ]
}
```

Did you find this page helpful?

![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg)

![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg)

ON THIS PAGE

How to build a media carousel message

The card object

Request Syntax

Request parameters

Card Object Parameters

Example Request

Example Response

***