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.

Send exactly as many cards as the template was approved with.

If a template was approved with 10 cards, sending 2 or 3 returns 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

TypeScript SDK

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.