Send Whatsapp Carousel Template API

Updated October 02, 2025

Before we start, here are what you need:

Read the documentation here
Qiscus App ID and Qiscus Secret Key
Channel ID, Template Name, Language, & Namespace from your approved template

[GET] List Template

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm?name=testingcarousel1212&page=1&limit=1' \
--header 'Qiscus-App-Id: {{AppCode}}' \
--header 'Qiscus-Secret-Key: {{SecretKey}}'

Headers

Qiscus-App-Id	`{{AppCode}}`
Qiscus-Secret-Key	`{{SecretKey}}`

Params

name	WhatsApp template name
page	page number
limit	limit per page (max 5)

Response:

{
  "data": {
    "hsm_quota": 0,
    "hsm_templates": [
      {
        "appeal_category_status": 0,
        "category": "marketing",
        "channel_id": 778,
        "channel_name": "Sandbox 5",
        "hsm_details": [
          {
            "approval_status": 1,
            "button_type": null,
            "buttons": null,
            "cards": [
              {
                "body_sample": null,
                "buttons": [
                  {
                    "text": "Tertarik Banget",
                    "type": "QUICK_REPLY"
                  }
                ],
                "content": "barang 1",
                "header_default_value": "https://dnlbo7fgjcc7f.cloudfront.net/ramo-29lun8b1ulepsaio/image/upload/bv51l4VIzF/2317583b-1ac7-4a33-af93-f6bbacda11ba.jpg",
                "header_type": "image",
                "number_of_arguments": 0
              },
              {
                "body_sample": null,
                "buttons": [
                  {
                    "text": "Tertarik aja",
                    "type": "QUICK_REPLY"
                  }
                ],
                "content": "barang 2",
                "header_default_value": "https://dnlbo7fgjcc7f.cloudfront.net/ramo-29lun8b1ulepsaio/image/upload/Fy1xuxD2LX/WhatsApp-Interactive-2024-12-12-at-4.53.26-PM.jpeg",
                "header_type": "image",
                "number_of_arguments": 0
              }
            ],
            "content": "Halo ini adalah barang baru kami",
            "footer": null,
            "header_content": null,
            "header_default_value": null,
            "header_type": null,
            "id": 690645,
            "is_carousel": true,
            "is_optimize": false,
            "language": "id",
            "number_of_arguments": 0,
            "rejection_reason": "NONE",
            "tested": false
          }
        ],
        "id": 636167,
        "is_optimize": false,
        "name": "testingcarousel1212",
        "namespace": "6616bb93_d895_41e7_8bbe_2c528219e56e",
        "previous_category": null,
        "type": 2
      }
    ]
  },
  "meta": {
    "limit": 1,
    "page": 1,
    "total": 2,
    "total_page": 2
  },
  "status": 200
}

[POST] Send Carousel Message with Default Media

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/broadcast/client' \
--header 'Qiscus-App-Id: {{AppCode}}' \
--header 'Qiscus-Secret-Key: {{SecretKey}}' \
--header 'Content-Type: application/json' \
--data '{
  "channel_id": 2905,
  "name": "sample broadcast carousel",
  "template_name": "testingcarousel1212",
  "template_detail_id": 690645,
  "namespace": "6616bb93_d895_41e7_8bbe_2c528219e56e",
  "language": "id",
  "variables": [],
  "phone_number": "{{phone_number}}",
  "button_params": null,
  "started_at": null,
  "card_payload": [
    null,
    null
  ],
  "card_button": []
}'

Headers

Qiscus-App-Id	`{{AppCode}}`
Qiscus-Secret-Key	`{{SecretKey}}`

Body

channel_id	optional, if null will use first wa channel
name	broadcast name, optional
template_name	required
template_detail_id	required, get from response API list template hsm_details
namespace	required
language	string, required
variables	array of string, required
phone_number	string, required
button_params	null if use carousel template
card_payload	array, fill with null to use default card payload. The length of the array should match the number of cards in the template.
card_button	array, fill with empty array [] to use default card button

Response:

{
  "data": {
    "broadcast_job_id": 343963960,
    "broadcast_logs": [
      {
        "card_button": "[[{\"button_text\":\"Tertarik Banget\",\"index\":0,\"payload\":\"Tertarik Banget\",\"type\":\"quick_reply\"}],[{\"button_text\":\"Tertarik aja\",\"index\":0,\"payload\":\"Tertarik aja\",\"type\":\"quick_reply\"}]]",
        "card_header": "[{\"type\":\"image\",\"value\":\"https://dnlbo7fgjcc7f.cloudfront.net/ramo-29lun8b1ulepsaio/image/upload/bv51l4VIzF/2317583b-1ac7-4a33-af93-f6bbacda11ba.jpg\"},{\"type\":\"image\",\"value\":\"https://dnlbo7fgjcc7f.cloudfront.net/ramo-29lun8b1ulepsaio/image/upload/Fy1xuxD2LX/WhatsApp-Interactive-2024-12-12-at-4.53.26-PM.jpeg\"}]",
        "card_payload": "[null,null]",
        "header_value": null,
        "id": 650851362,
        "is_carousel": true,
        "is_optimize": false,
        "is_retried": false,
        "message_id": "wamid.HBgMNjI4MTU3OTA5MDgwFQIAERgSNjI5MjAyQTQ5NjI1OTJCRThDAA==",
        "notes": null,
        "phone_number": "628157909080",
        "sent_at": "2024-12-16T04:18:34Z",
        "status": "sent",
        "variables": "[]"
      }
    ],
    "language": "id",
    "name": "testingcarousel1212",
    "namespace": "6616bb93_d895_41e7_8bbe_2c528219e56e"
  },
  "status": 200
}

[POST] Send Carousel Message with Media ID

Request:

curl --location --globoff 'https://omnichannel.qiscus.com/whatsapp/v1/{{AppCode}}/{{channel_id}}/messages' \
--header 'Qiscus-App-Id: {{AppCode}}' \
--header 'Qiscus-Secret-Key: {{SecretKey}}' \
--header 'Content-Type: application/json' \
--data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{phone_number}}",
  "type": "template",
  "template": {
    "name": "testingcarousel1212",
    "language": {
      "code": "id"
    },
    "components": [
      {
        "type": "carousel",
        "cards": [
          {
            "card_index": 0,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "image",
                    "image": {
                      "id": "{{mediaID1}}"
                    }
                  }
                ]
              },
              {
                "type": "body",
                "parameters": []
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                  {
                    "type": "payload",
                    "payload": "payload1"
                  }
                ]
              }
            ]
          },
          {
            "card_index": 1,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "image",
                    "image": {
                      "id": "{{mediaID2}}"
                    }
                  }
                ]
              },
              {
                "type": "body",
                "parameters": []
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                  {
                    "type": "payload",
                    "payload": "payload2"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}'

Headers

Qiscus-App-Id	`{{App Id}}`
Qiscus-Secret-Key	`{{Secret Key}}`

Body

messaging_product	Messaging product to use, must be `"whatsapp"`.
recipient_type	Type of recipient, `"individual"`.
to	Recipient's phone number in international format.
type	Type of message, must be `"template"`.
template	Object containing message template details.

Template Object

`name`	Name of the message template.
`language`	Language object specifying the language code.
`components`	Array of components to customize the template.

Language Object

code

Language code (e.g., "en").

Components Array

`type`	Type of component (`"body"`, `"carousel"`, etc.).
`parameters`	Array of parameters for the component.
`cards`	Array of card objects (used with `"carousel"` type).

Card Object

`card_index`	Index of the card within the carousel (starting from `0`).
`components`	Array of components within the card (header, body, button).

Header Component

`type`	Must be `"header"`.
`parameters`	Array of parameters for the header component.

Header Parameters

`type`	Type of header, `"image"`. or `"video"`
`image / video`	Object of image or video

Media Image / Video Object (for Header)

`id`	Media ID of the image. Use API upload media to get media ID.

Body Component

`type`	Must be `"body"`.
`parameters`	Parameters for the body component.

Button Component

`type`	Must be `"button"`.
`sub_type`	Subtype of button, `"quick_reply"` or `"url"`
`index`	Index of the button (starting from `0`).
`parameters`	Array of parameters for the button component.

Button Parameters

`type`	Type of parameter, `"payload"`.
`payload`	Payload value for the button (e.g., `"Chat"`).

Response:

{
  "contacts": [
    {
      "input": "628157xxxx80",
      "wa_id": "628157xxxx80"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgMNjI4MTU3OTA5MDgwFQIAERgSMTM0N0VFMjJGMzU0NTM2RkVGAA==",
      "message_status": "accepted"
    }
  ],
  "messaging_product": "whatsapp"
}

Before we start, here are what you need:

[GET] List Template

[POST] Send Carousel Message with Default Media

[POST] Send Carousel Message with Media ID

Need further assistance?