Media carousel

media_card_carousel Up to 10 cards with image or video, which the customer swipes below the message.

How it works

The message comes first, and the cards below it. Each card has its own media, its own text and its own buttons. The media you put in at creation is only the sample Meta reviews. At send time, each card’s image or video goes as a parameter, by handle or link, and can be a different one: the same approved carousel serves different campaigns.

Every card needs the same components. If one has text, all do. The set of buttons, type and order, is the same across cards; what changes from one card to the next is the label and the destination.

At creation and at send time

At creation	At send time
The message above the cards	The values of the message variables
The text and buttons of each card	Each card’s image or video
The media sample Meta reviews	Each button destination, when it has a variable

Fields in this model

Field	What it is for	Rule
`category`	Fixed	Always `MARKETING`
`BODY`	The message above the cards	Up to 1024 characters
`CAROUSEL.cards`	The cards	2 to 10, all with the same components
Card `HEADER`	The card media	`IMAGE` or `VIDEO`, and every card needs media
Card `BODY`	The card text	Up to 160 characters
Card `BUTTONS`	The card buttons	Up to 2 per card

Full JSON

Two JSON payloads: one creates the template, and Meta approves it once. The other sends the message, and goes on every dispatch, with that send’s values in the variables marked with braces.

1. Create the template

POST /whatsapp/businesses/{wabaId}/templates — see API reference.

{
  "name": "exemplo_media_card_carousel",
  "category": "MARKETING",
  "language": "en_US",
  "allow_category_change": true,
  "parameter_format": "NAMED",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{customer_name}}, your order {{order_number}} is confirmed and ships today.",
      "example": {
        "body_text_named_params": [
          {
            "param_name": "customer_name",
            "example": "Marina"
          },
          {
            "param_name": "order_number",
            "example": "1042"
          }
        ]
      }
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": {
                "header_handle": [
                  "4::aW1hZ2UvcG5n"
                ]
              }
            },
            {
              "type": "BODY",
              "text": "Item from the new collection"
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Track order"
                }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": {
                "header_handle": [
                  "4::aW1hZ2UvcG5n"
                ]
              }
            },
            {
              "type": "BODY",
              "text": "Item from the new collection"
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Track order"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

2. Send it once approved

POST /v1/channels/{channelId}/messages — see Send template.

{
  "recipient": {
    "identifier": "5511999999999"
  },
  "content": {
    "type": "TEMPLATE",
    "attachments": [
      {
        "template": {
          "name": "exemplo_media_card_carousel",
          "language": {
            "policy": "deterministic",
            "code": "en_US"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "{{customer_name}}"
                },
                {
                  "type": "text",
                  "text": "{{order_number}}"
                }
              ]
            },
            {
              "type": "carousel",
              "cards": [
                {
                  "card_index": 0,
                  "components": [
                    {
                      "type": "header",
                      "parameters": [
                        {
                          "type": "image",
                          "image": {
                            "id": "{{card_1_media_id}}"
                          }
                        }
                      ]
                    },
                    {
                      "type": "button",
                      "sub_type": "quick_reply",
                      "index": 0,
                      "parameters": [
                        {
                          "type": "payload",
                          "payload": "{{quick_reply_payload_1}}"
                        }
                      ]
                    }
                  ]
                },
                {
                  "card_index": 1,
                  "components": [
                    {
                      "type": "header",
                      "parameters": [
                        {
                          "type": "image",
                          "image": {
                            "id": "{{card_2_media_id}}"
                          }
                        }
                      ]
                    },
                    {
                      "type": "button",
                      "sub_type": "quick_reply",
                      "index": 0,
                      "parameters": [
                        {
                          "type": "payload",
                          "payload": "{{quick_reply_payload_1}}"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

What Meta rejects here

Fewer than 2 or more than 10 cards.
A card without media.
One card with text and another without, or different button sets across cards.
The link Meta returns when you read a template (whatsapp.net, fbcdn.net, fbsbx.com domains) sent back as a sample: it comes back as invalid media sample, code 2388215.

Channels

Messages

Templates (WhatsApp)

Flows (WhatsApp)

Webhooks

How it works

At creation and at send time

Fields in this model

Full JSON

1. Create the template

2. Send it once approved

What Meta rejects here

​How it works

​At creation and at send time

​Fields in this model

​Full JSON

​1. Create the template

​2. Send it once approved

​What Meta rejects here

How it works

At creation and at send time

Fields in this model

Full JSON

1. Create the template

2. Send it once approved

What Meta rejects here