The WhatsApp Marketing product provides conversational messages, allowing users to initiate conversations with businesses after the business has sent an initial message. One way to create a conversational flow is to integrate a bot to reply to users' WhatsApp messages.
The Conversational API is designed for connection with WhatsApp bots.
When creating a new template in either marketing or utility categories, you can select the 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.
Before sending Conversational WhatsApp Carousel template messages, make sure you create your carousel template in InOne first. Refer to Create a WhatsApp Business Carousel Template on InOne for step-by-step guidance.
Endpoint and Headers
Visit our Postman collection to test this request.
Headers
Header | Sample Value | Description |
|---|---|---|
X-INS-AUTH-KEY | 1a2b3c4d5e6f | This key is required to authorize your request. Refer to 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 |
|---|---|---|---|
components | This text defines the dynamic sections of the message, such as the body, header, or buttons, for customization. | Array | Yes |
type | Specifies the type of each component (e.g., body, header, button, carousel). | String | Yes |
cards | Represents a collection of interactive cards, each containing its components like headers, body texts, and buttons. | Array | Yes |
card_index | Identifies the position of a specific card in the carousel, starting from 0. | String | Yes |
components | This array, nested within each card, defines the individual elements of the card. Common components are header (e.g., for an image), body (e.g., for text), and button (for actions like quick replies or URLs). | Array | Yes |
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 Request
Below is a sample request to send a conversational WhatsApp carousel template message with multiple cards, images, text, and interactive buttons.
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: *****************************************' \
--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 in your WhatsApp Carousel template messages:
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: *****************************************' \
--data '{
"from": "{{PHONE_NUMBER}}", //Example: +112312312
"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) in your WhatsApp Carousel template messages, you can use the sample request below:
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'x-ins-auth-key: ***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 in your WhatsApp Carousel template messages, you can use the sample request below:
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: ***tiNlcL284J8dwCpfoqdR.gpyLwFG-0fSHPS9+kZYNsI-D2IWFNjlaRDlXJrZjx2_ZPTP37I' \
--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.useinsider.com/vikingsankara/media/whatsapp-business/11521/83rbBaWO7H63VmACSXiZ1716506118.jpg"
}
}
]
},
{
"type": "body",
"sub_type": "",
"index": "",
"parameters": [
{
"type": "text",
"text": "shahla"
}
]
}
]
}
}
}
]
}'Sample Responses
One key information will be returned for each message to be sent. This key will be added to all events related to the message.
{
"keys": [
"whatsapp-*************************"
]
}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:
{
"message": "ip-restricted",
"error": {
"message": "ip-restricted",
"code": 1088
}
}
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.
For more detailed troubleshooting guidance and Cloudflare’s official documentation, refer to the following resources:
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 10 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.