--- title: "Send Transactional WhatsApp Carousel Template Message" slug: "send-transactional-whatsapp-carousel-template-message" description: "Learn how to send a transactional WhatsApp carousel template message using the Insider One Transactional API including request structure carousel cards and sample API calls." tags: ["transactional whatsapp api", "whatsapp carousel"] updated: 2026-10-13T13:23:05Z published: 2026-10-13T13:23:05Z canonical: "academy.insiderone.com/send-transactional-whatsapp-carousel-template-message" --- > ## Documentation Index > Fetch the complete documentation index at: https://academy.insiderone.com/llms.txt > Use this file to discover all available pages before exploring further. # Send Transactional WhatsApp Carousel Template Message Transactional WhatsApp API enables you to send targeted transactional WhatsApp Carousel messages to your users. You can trigger these WhatsApp messages once a user takes a specific action on your platform. When creating a new template in either the marketing or utility categories, you can select the [Carousel template](/docs/create-a-whatsapp-carousel-template) type. This feature enables the creation of multi-card messages, with each card displaying unique content, images, and interactive buttons. Carousel templates offer an engaging way to showcase multiple options or pieces of information within a single message, making it easier to capture user attention and encourage interaction. > [!WARNING] > Before sending Transactional WhatsApp Carousel template messages, make sure you create your carousel template in InOne first. Refer to [Create a WhatsApp Business Carousel Template on InOne](/v1/docs/create-a-whatsapp-business-carousel-template-on-inone) for step-by-step guidance. ## Endpoint and Headers > **POST** https://whatsapp.useinsider.com/v1/send [](https://developers.insiderone.com/#9de80776-e762-4fdd-9b01-a6f8b8f004b7) > Visit our Postman collection to test this request. | Header | Sample Value | Description | | --- | --- | --- | | X-INS-AUTH-KEY | 1a2b3c4d5e6f | This key is required to authorize your request. Refer to [API Authentication Tokens](https://academy.insiderone.com/docs/api-authentication-tokens) to generate your token. | | Content-Type | application/json | This header specifies the media type of the resource. | ## Body Parameters | Column | Description | Data Type | Required | | --- | --- | --- | --- | | from | Specifies the sender phone number ID. Only required when multiple phone numbers are configured for the account. If not specified, the default phone number is used. This applies to both Transactional and Conversational WhatsApp APIs. | String | Optional | | phoneNumber | Phone number for the person you want to message. > [!WARNING] > The value of the phoneNumber must follow the E.164 format (e.g., +1234567). Each phone number must begin with a plus sign (**+**) followed by the country code. | String | Conditional. Required if recipient is not sent. | | recipient | Specifies the recipient’s **WhatsApp Business-Scoped User ID (BSUID)**. For example, TR.2124566744990207. Use this identifier to send messages without providing the recipient’s phone number. Pass the complete BSUID, including its country prefix. | String | Conditional. Required if phoneNumber is not provided. | | components | Components can define the message's body, buttons, header, footer, or additional interactive elements like carousels. | Array | Yes | | type | In this example, it is set to "carousel", which enables a set of cards with multiple interactive features. | String | Yes | | cards | An array of cards in a carousel. | Array | Yes | | card_index | Indicates the position of a specific card in a multi-card setup. | String | Yes | | components | Nested within each card, this array defines the individual elements of the card. | Array | Yes | | bid_spec | Opt-in for dynamic pricing. Only valid for MARKETING templates. | Object | No | Meta doesn't support adding emojis to the button ID. ### WhatsApp Status Callback The Status Callback allows you to track the delivery status of your WhatsApp messages in real time. When you send a message, the system sends status updates to the API URL you’ve specified in the **callback** parameter. If you don't respond to code between 200 and 300, the system automatically retries the request up to **10 times** following this schedule: | Retry Attempt | Time After First Attempt | | --- | --- | | 1st retry | 1 minute | | 2nd retry | 2 minutes | | 3rd retry | 3 minutes | | 4th retry | 8 minutes | | 5th retry | 13 minutes | | 6th retry | 18 minutes | | 7th retry | 28 minutes | | 8th retry | 38 minutes | | 9th retry | 48 minutes | | 10th retry | 1 hour | ## Sample Requests Below is a sample request to send a WhatsApp Carousel template message. ```bash curl --location 'https://whatsapp.useinsider.com/v1/send' \  --header 'Content-Type: application/json' \  --header 'x-ins-auth-key: INS.**************************************' \  --data '{    "from": "{{FROM}}",    "messages": [      {        "phoneNumber": "{{TO}}",        "message": {          "type": "template",          "template": {            "name": "{{TEMPLATE_NAME}}",            "language": {              "code": "{{LANG_CODE}}",              "policy": "deterministic"            },            "components": [              {                "type": "body",                "parameters": [                  {                    "type": "text",                    "text": "{{BODY_1}}"                  }                ]              },              {                "type": "carousel",                "cards": [                  {                    "card_index": 0,                    "components": [                      {                        "type": "header",                        "parameters": [                          {                            "type": "image",                            "image": {                              "id": "{{IMG_ID_1}}"                            }                          }                        ]                      },                      {                        "type": "body",                        "parameters": [                          {                            "type": "text",                            "text": "{{CARD_TEXT_1}}"                          }                        ]                      },                      {                        "type": "button",                        "sub_type": "quick_reply",                        "index": "0",                        "parameters": [                          {                            "type": "payload",                            "payload": "{{PAYLOAD_1}}"                          }                        ]                      },                      {                        "type": "button",                        "sub_type": "url",                        "index": "1",                        "parameters": [                          {                            "type": "text",                            "text": "{{URL_1}}"                          }                        ]                      }                    ]                  },                  {                    "card_index": 1,                    "components": [                      {                        "type": "header",                        "parameters": [                          {                            "type": "image",                            "image": {                              "id": "{{IMG_ID_2}}"                            }                          }                        ]                      },                      {                        "type": "body",                        "parameters": [                          {                            "type": "text",                            "text": "{{CARD_TEXT_2}}"                          }                        ]                      },                      {                        "type": "button",                        "sub_type": "quick_reply",                        "index": "0",                        "parameters": [                          {                            "type": "payload",                            "payload": "{{PAYLOAD_2}}"                          }                        ]                      },                      {                        "type": "button",                        "sub_type": "url",                        "index": "1",                        "parameters": [                          {                            "type": "text",                            "text": "{{URL_2}}"                          }                        ]                      }                    ]                  }                ]              }            ]          }        }      }    ]  }' ``` You can use the sample request below if you want to use the **quick reply buttons**: ```bash curl --location 'https://whatsapp.useinsider.com/v1/send' \  --header 'Content-Type: application/json' \  --header 'x-ins-auth-key: INS.1a2b3c4d5e6f' \  --data '{    "messages": [      {        "phoneNumber": "+1**********",        "message": {          "type": "template",          "template": {            "name": "{{TEMPLATE_NAME}}",            "language": {              "code": "{{TEMPLATE_LANGUAGE_CODE}}"              "policy": "deterministic",            },            "components": [              {                "type": "body",                "parameters": [                  {                    "type": "text",                    "text": "{{PARAMETER_VALUE}}"                  }                ]              },              {                "type": "button",                "sub_type": "quick_reply",                "index": "0",                "parameters": [                  {                    "type": "payload",                    "payload": "1"                  }                ]              },              {                "type": "button",                "sub_type": "quick_reply",                "index": "1",                "parameters": [                  {                    "type": "payload",                    "payload": "2"                  }                ]              }            ]          }        }      }    ]  }' ``` If you want to use **CTA (Call to Action)**, you can use the sample request below: ```bash curl --location 'https://whatsapp.useinsider.com/v1/send' \  --header 'x-ins-auth-key: INS.kjQu-+bL4HpeZqvgr1j0.d4IVgHl9GcE+_eaKxNA3P8M3q8-emrO3-zalg9GSF29mK+Jz5k' \  --header 'Content-Type: application/json' \  --data '{    "messages": [      {        "phoneNumber": "+994558964184",        "message": {          "type": "template",          "template": {            "name": "mert_masterfile_media_with_button",            "language": {              "code": "en",              "policy": "deterministic"            },            "components": [              {                "type": "header",                "sub_type": "",                "index": "",                "parameters": [                  {                    "type": "image",                    "image": {                      "link": "https://inshoppingcart.com/seleniumautomation/wp-content/uploads/2018/08/cap-2.jpg"                    }                  }                ]              },              {                "type": "body",                "sub_type": "",                "index": "",                "parameters": [                  {                    "type": "text",                    "text": "https://vikingsankara.com?abc=sha"                  }                ]              },              {                "type": "button",                "sub_type": "url",                "index": "0",                "parameters": [                  {                    "type": "text",                    "text": "https://vikingsankara.com"                  }                ]              }            ]          }        }      }    ]  }' ``` If you don't want to use CTA, you can use the sample request below: ```bash curl --location 'https://whatsapp.useinsider.com/v1/send' \  --header 'Content-Type: application/json' \  --header 'x-ins-auth-key: INS.**************************************' \  --data '{    "messages": [      {        "phoneNumber": "+994558964184",        "message": {          "type": "template",          "template": {            "name": "7_image_header_no_button_copy",            "language": {              "code": "fi",              "policy": "deterministic"            },            "components": [              {                "type": "header",                "sub_type": "",                "index": "",                "parameters": [                  {                    "type": "image",                    "image": {                      "link": "https://image.insiderone.com/media/whatsapp-business/11521/83rbBaWO7H506118.jpg"                    }                  }                ]              },              {                "type": "body",                "sub_type": "",                "index": "",                "parameters": [                  {                    "type": "text",                    "text": "shahla"                  }                ]              }            ]          }        }      }    ]  }' ``` ### Send a Marketing template with WhatsApp Dynamic Pricing (Max-Price) To enable the WhatsApp Maximum Price (Max-Price) feature for a template, include the **bid_spec** object in the template request. The following example allows you to send a marketing template with Maximum Price bidding enabled. > [!NOTE] > Use **per_message_bid_multiplier** only with templates that have Maximum Price bidding enabled through the **bid_spec** object. The **bid_amount** is defined during template creation, and **per_message_bid_multiplier** can be used at send time to increase or decrease the effective maximum price for a specific message delivery. #### Calculate bid_amount values The **bid_amount** value represents your maximum price per 1,000 deliveries in the smallest unit of your WABA currency. To calculate the value: - Convert your desired per-delivery price to the smallest unit of your WABA currency. - Multiply the result by 1,000 to express the value per 1,000 deliveries. For example, to set a maximum price of ₹0.87 per delivery: - Convert to paise: 0.87 rupees = 87 paise. - Multiply by 1,000: 87 × 1,000 = 87,000. Set bid_amount to 87000. For example, to set a maximum price of $0.05 USD per delivery: - Convert to cents: $0.05 = 5 cents. - Multiply by 1,000: 5 × 1,000 = 5,000. Set bid_amount to 5000. > [!NOTE] > For more information about the feature, see [WhatsApp Maximum Price Feature](/docs/whatsapp-maximum-price-feature). ```bash curl --location 'https://whatsapp.useinsider.com/v1/send' \  --header 'Content-Type: application/json' \  --header 'x-ins-auth-key: INS.**************************************' \  --data '{    "from": "{{FROM}}",    "messages": [      {        "phoneNumber": "{{TO}}",        "message": {          "type": "template",          "template": {            "name": "{{TEMPLATE_NAME}}",            "language": {              "code": "{{LANG_CODE}}",              "policy": "deterministic"            },            "components": [              {                "type": "body",                "parameters": [                  {                    "type": "text",                    "text": "{{BODY_1}}"                  }                ]              },              {                "type": "carousel",                "cards": [                  {                    "card_index": 0,                    "components": [                      {                        "type": "header",                        "parameters": [                          {                            "type": "image",                            "image": {                              "id": "{{IMG_ID_1}}"                            }                          }                        ]                      },                      {                        "type": "body",                        "parameters": [                          {                            "type": "text",                            "text": "{{CARD_TEXT_1}}"                          }                        ]                      },                      {                        "type": "button",                        "sub_type": "quick_reply",                        "index": "0",                        "parameters": [                          {                            "type": "payload",                            "payload": "{{PAYLOAD_1}}"                          }                        ]                      },                      {                        "type": "button",                        "sub_type": "url",                        "index": "1",                        "parameters": [                          {                            "type": "text",                            "text": "{{URL_1}}"                          }                        ]                      }                    ]                  },                  {                    "card_index": 1,                    "components": [                      {                        "type": "header",                        "parameters": [                          {                            "type": "image",                            "image": {                              "id": "{{IMG_ID_2}}"                            }                          }                        ]                      },                      {                        "type": "body",                        "parameters": [                          {                            "type": "text",                            "text": "{{CARD_TEXT_2}}"                          }                        ]                      },                      {                        "type": "button",                        "sub_type": "quick_reply",                        "index": "0",                        "parameters": [                          {                            "type": "payload",                            "payload": "{{PAYLOAD_2}}"                          }                        ]                      },                      {                        "type": "button",                        "sub_type": "url",                        "index": "1",                        "parameters": [                          {                            "type": "text",                            "text": "{{URL_2}}"                          }                        ]                      }                    ]                  }                ]              }            ],            "bid_spec": {              "per_message_bid_multiplier": 1.5            }          }        }      }    ]  }' ``` ## Sample Responses One key piece of information will be returned for each message to be sent. This key will be added to all events related to the message. ```json { "keys": [ "whatsapp-*************************" ] } ``` ### 401 Unauthorized If you use the wrong key, you will see the following error: ```json { "message": "unauthorized" } ``` ### 429 Rate Limit If you send more than 1000 requests per second, you will see the following error: ```json { "message": "rate limited" } ``` ### 403 Forbidden This error occurs when requests are blocked by Cloudflare’s security mechanisms, which act as an additional protection layer for Insider’s infrastructure. As part of this setup, Insider complies with Cloudflare’s automated security policies. In certain cases, these mechanisms may block specific **User-Agent** values or IP addresses. If the client IP is denied or restricted, the API will return the following response: ```json { "message": "ip-restricted", "error": { "message": "ip-restricted", "code": 1088 } } ``` > [!WARNING] > **Notes**: > > - **403 Forbidden** error occurs when the IP address is not whitelisted for you. > - **Error code 1088** is specific to IP restriction errors. #### How to Troubleshoot a 403 Forbidden Error If you encounter a **403 Forbidden** error when making API requests, for example, through the **Conversational** or **Transactional API**, please check the following: - Verify the **User-Agent header** used in your HTTP client (especially default or empty values such as Java’s default `User-Agent`). - Review blocked requests under **Security** > **Events** in your Cloudflare dashboard to identify whether they were rejected due to User-Agent or WAF rules. > [!NOTE] > For more detailed troubleshooting guidance and Cloudflare’s official documentation, refer to the following resources: > > - [403 Error Troubleshooting Guide](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/4xx-client-error/error-403/) > - [User-Agent Blocking Documentation](https://developers.cloudflare.com/waf/tools/user-agent-blocking/) > - [Security Events (Firewall Events) Dashboard](https://developers.cloudflare.com/waf/analytics/security-events/) > - [WAF Troubleshooting FAQ](https://developers.cloudflare.com/waf/troubleshooting/faq/) ## Limitations - All functions must be executed with a simple **HTTPS POST** request. - Only new WhatsApp messages can be sent via this API. No data can be retrieved. - The **API Key** should be provided as the authorization key in the request header. If the key is incorrect, the operation will not be executed, and an authorization error will be returned in the response. - The rate limit is **1000 requests per second**. - Each card in the carousel template must include at least one button. - All cards should have buttons of the same type and quantity. - The template supports a minimum of 2 cards and a maximum of 6 cards per message. > The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team. We can adjust it to fit your needs. ## Related - [Send Transactional WhatsApp Text Message](/send-transactional-whatsapp-text-message.md) - [Send Transactional WhatsApp Message with Button Reply (Quick Reply)](/send-transactional-whatsapp-message-with-button-reply.md) - [Send Transactional WhatsApp Media Message (Document)](/send-transactional-whatsapp-media-message-document.md) - [Send Transactional WhatsApp Media Message (Image)](/send-transactional-whatsapp-media-message-image.md) - [Send Transactional WhatsApp Media Message (Location)](/send-transactional-whatsapp-media-message-location.md) - [API Authentication Tokens](/api-authentication-tokens.md) - [API Rate Limits](/api-rate-limits.md) - [API Status and Error Codes](/api-status-and-error-codes.md) - [Insider One APIs in Postman](/insider-apis-in-postman.md)