Skip to main content
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.
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.
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

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
});

​
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 and template message send reference for the underlying Cloud API behavior.