> For the complete documentation index, see [llms.txt](https://docs.taqnyat.sa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taqnyat.sa/api-reference/templates/create-template/media-carousel-template.md).

# Media Carousel Template

Use this endpoint to create a WhatsApp **media carousel template** containing multiple cards.

Each carousel card can contain its own media header, body text, and supported buttons.

### Endpoint

```
POST /templates/
```

Full URL:

```
https://api.taqnyat.sa/wa/v2/templates/
```

### Authentication

Include your API token in the request header:

```
Authorization: <YOUR_TOKEN>Content-Type: application/json
```

### Request Parameters

| Parameter               | Type   | Required        | Description                                                     |
| ----------------------- | ------ | --------------- | --------------------------------------------------------------- |
| `name`                  | String | Yes             | Unique name of the template.                                    |
| `language`              | String | Yes             | Language code of the template.                                  |
| `category`              | String | Yes             | Template category, such as `UTILITY` or `MARKETING`.            |
| `components`            | Array  | Yes             | Contains the main template body and carousel component.         |
| `components[].type`     | String | Yes             | Component type, such as `body` or `carousel`.                   |
| `cards`                 | Array  | Yes             | Contains the individual carousel cards.                         |
| `cards[].components`    | Array  | Yes             | Defines the content of each carousel card.                      |
| `format`                | String | For header      | Media format used in the card header. In this example, `image`. |
| `example.header_handle` | Array  | For header      | Contains the media reference used as the card header example.   |
| `buttons`               | Array  | When applicable | Contains the buttons configured for the carousel card.          |

### Example Payload

```json
{
  "name": "product_carousel",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "body",
      "text": "Choose one of the following options."
    },
    {
      "type": "carousel",
      "cards": [
        {
          "components": [
            {
              "type": "header",
              "format": "image",
              "example": {
                "header_handle": [
                  "<IMAGE_LINK_1>"
                ]
              }
            },
            {
              "type": "body",
              "text": "First carousel card"
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Select"
                }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "header",
              "format": "image",
              "example": {
                "header_handle": [
                  "<IMAGE_LINK_2>"
                ]
              }
            },
            {
              "type": "body",
              "text": "Second carousel card"
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Select"
                }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "header",
              "format": "image",
              "example": {
                "header_handle": [
                  "<IMAGE_LINK_3>"
                ]
              }
            },
            {
              "type": "body",
              "text": "Third carousel card"
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Select"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

### Example Request

```bash
curl --location 'https://api.taqnyat.sa/wa/v2/templates/' \
--header 'Authorization: <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "product_carousel",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "body",
      "text": "Choose one of the following options."
    },
    {
      "type": "carousel",
      "cards": [
        {
          "components": [
            {
              "type": "header",
              "format": "image",
              "example": {
                "header_handle": [
                  "<IMAGE_LINK_1>"
                ]
              }
            },
            {
              "type": "body",
              "text": "First carousel card"
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Select"
                }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "header",
              "format": "image",
              "example": {
                "header_handle": [
                  "<IMAGE_LINK_2>"
                ]
              }
            },
            {
              "type": "body",
              "text": "Second carousel card"
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Select"
                }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "header",
              "format": "image",
              "example": {
                "header_handle": [
                  "<IMAGE_LINK_3>"
                ]
              }
            },
            {
              "type": "body",
              "text": "Third carousel card"
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Select"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'
```

### Main Body

The first `body` component contains the main message text that appears with the carousel:

```json
{
  "type": "body",
  "text": "Choose one of the following options."
}
```

### Carousel Component

The carousel itself is defined using:

```json
{
  "type": "carousel",
  "cards": []
}
```

Each object inside `cards` represents one carousel card.

### Card Structure

Each card in the Postman example contains three components:

#### Media Header

```json
{
  "type": "header",
  "format": "image",
  "example": {
    "header_handle": [
      "<IMAGE_LINK>"
    ]
  }
}
```

#### Card Body

```json
{
  "type": "body",
  "text": "Card text"
}
```

#### Card Button

```json
{
  "type": "buttons",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Select"
    }
  ]
}
```

### Adding More Cards

Additional cards are added as separate objects inside the `cards` array.

Each card follows the same component structure:

```
Carousel
- Card 1
  - Header
  - Body
  - Buttons
- Card 2
  - Header
  - Body
  - Buttons
- Card 3
  - Header
  - Body
  - Buttons
```

### Notes

* The carousel is defined using a `carousel` component containing a `cards` array.
* Each card has its own `components` array.
* In the current Postman example, each card contains an image header, body text, and a Quick Reply button.
* The image reference for each card is provided through `example.header_handle`.
* Each card can use a different image and body text.
* The template must be approved before it can be used to send carousel template messages.