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

# Carousel

> Send WhatsApp carousel template messages with card headers, bodies, and buttons

Carousel templates use Meta's template send payload directly through Kapso's Meta
proxy. The proxy forwards the `carousel.cards` structure to Meta; it does not
translate per-card body, header, or button components.

This page covers approved template carousel messages. For free-form interactive
carousel messages sent inside the customer service window, use
`client.messages.sendInteractiveCarousel(...)` in the
[interactive message SDK guide](/docs/whatsapp/typescript-sdk/interactive).

<Warning>
  The number of cards you send at runtime must match the number of cards approved in the template. If a template was approved with 10 cards, sending 2 or 3 cards can return Meta error `(#132012)` with the misleading detail `header component parameter should not be empty`.
</Warning>

For variable result counts, create one approved template per supported count, such as `flight_option_single`, `flight_options_carousel_v1_2`, and `flight_options_carousel_v1_3`.

## Send

<CodeGroup>
  ```typescript TypeScript SDK icon="square-js" theme={null}
  import { WhatsAppClient, buildTemplateSendPayload } from '@kapso/whatsapp-cloud-api';

  const client = new WhatsAppClient({
    baseUrl: 'https://api.kapso.ai/meta/whatsapp',
    kapsoApiKey: process.env.KAPSO_API_KEY!
  });

  const template = buildTemplateSendPayload({
    name: 'flight_options_carousel_v1_2',
    language: 'pt_BR',
    cards: [
      {
        cardIndex: 0,
        components: [
          {
            type: 'header',
            parameters: [
              { type: 'image', image: { link: 'https://example.com/flight-a.jpg' } }
            ]
          },
          {
            type: 'body',
            parameters: [
              { type: 'text', text: '12.000,00' }
            ]
          },
          {
            type: 'button',
            subType: 'quick_reply',
            index: 0,
            parameters: [
              { type: 'payload', payload: 'OPT_1' }
            ]
          }
        ]
      },
      {
        cardIndex: 1,
        components: [
          {
            type: 'header',
            parameters: [
              { type: 'image', image: { link: 'https://example.com/flight-b.jpg' } }
            ]
          },
          {
            type: 'body',
            parameters: [
              { type: 'text', text: '13.500,00' }
            ]
          },
          {
            type: 'button',
            subType: 'quick_reply',
            index: 0,
            parameters: [
              { type: 'payload', payload: 'OPT_2' }
            ]
          }
        ]
      }
    ]
  });

  await client.messages.sendTemplate({
    phoneNumberId: '647015955153740',
    to: '5514998062062',
    template
  });
  ```

  ```bash REST API icon="code" theme={null}
  curl -X POST 'https://api.kapso.ai/meta/whatsapp/v24.0/647015955153740/messages' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "messaging_product": "whatsapp",
      "to": "5514998062062",
      "type": "template",
      "template": {
        "name": "flight_options_carousel_v1_2",
        "language": {
          "code": "pt_BR"
        },
        "components": [
          {
            "type": "carousel",
            "cards": [
              {
                "card_index": 0,
                "components": [
                  {
                    "type": "header",
                    "parameters": [
                      { "type": "image", "image": { "link": "https://example.com/flight-a.jpg" } }
                    ]
                  },
                  {
                    "type": "body",
                    "parameters": [
                      { "type": "text", "text": "12.000,00" }
                    ]
                  },
                  {
                    "type": "button",
                    "sub_type": "quick_reply",
                    "index": 0,
                    "parameters": [
                      { "type": "payload", "payload": "OPT_1" }
                    ]
                  }
                ]
              },
              {
                "card_index": 1,
                "components": [
                  {
                    "type": "header",
                    "parameters": [
                      { "type": "image", "image": { "link": "https://example.com/flight-b.jpg" } }
                    ]
                  },
                  {
                    "type": "body",
                    "parameters": [
                      { "type": "text", "text": "13.500,00" }
                    ]
                  },
                  {
                    "type": "button",
                    "sub_type": "quick_reply",
                    "index": 0,
                    "parameters": [
                      { "type": "payload", "payload": "OPT_2" }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    }'
  ```
</CodeGroup>

## Format rules

* Send-time component and parameter types are lowercase: `carousel`, `header`, `body`, `button`, `image`, `text`, and `payload`.
* `card_index` is numeric and zero-based. In the TypeScript SDK helper, use `cardIndex`; it is converted to `card_index` on send.
* `button.index` is numeric and zero-based.
* Media card headers can use `image: { "link": "https://..." }` or `image: { "id": "<MEDIA_ID>" }` from a media upload. Do not use `image.url`.
* The runtime `cards` array must have exactly the same length as the approved carousel template.
* At template creation time, Meta component definitions use uppercase types such as `CAROUSEL`, `HEADER`, `BODY`, and `BUTTONS`. The lowercase rules above are for sending messages.

See Meta's [media card carousel template docs](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/media-card-carousel-templates/) and [template message send reference](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#template-messages) for the underlying Cloud API behavior.