The WhatsApp Marketing product provides conversational messages, allowing users to initiate conversations with businesses after the business has sent an initial message. To create a conversational flow, one of the ways is to integrate a bot to reply to users' WhatsApp messages.
The Conversational API is designed for WhatsApp Bot connection.
Refer to the visual below for an example of how a conversational WhatsApp template message is displayed.
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 |
|---|---|---|---|
| messages | All messages are contained in the messages key. You can send multiple messages with a single request. | Array | Yes |
| from | Use only if you are using multiple phone numbers. If you have only one phone number, you do not need to add this. | String | No |
| phoneNumber | Phone number for the person you want to send a message to. Your title goes here 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 | Yes |
| message | Message object | Object | Yes |
| type | Must be “template” for this message type. | String | Yes |
| name | Template name to be sent | String | Yes |
| language | - | Object | Yes |
code | Template language | String | Yes |
| policy | It must be deterministic. | String | Yes |
| message variable components | - | Array | Yes |
| type | body | String | Yes |
| body parameters | - | Array | Yes |
| type | text | String | Yes |
| text | Parameter value | String | Yes |
| button components | - | Array | Yes |
| type | button | String | Yes |
| sub_type | Quick_reply, URL, PHONE_NUMBER | String | Yes |
| index | - | String | Yes |
| parameters | - | Array | Yes |
| type | payload | String | Yes |
| payload | Payload value | String | Yes |
| header | Header component object | Object | No |
| type | Must be "header". | String | Yes |
| parameters | - | Array | Yes |
| type | One of: text, image, video, document | String | Yes |
| text | Header text (used if type = text) | String | Yes (if type = text) |
| image | - | Object | Yes (if type = image) |
| link | Image URL | String | Yes |
| video | - | Object | Yes (if type = video) |
| link | Video URL | String | Yes |
| document | - | Object | Yes (if type = document) |
| link | Document URL | String | Yes |
| filename | File name | String | No |
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
You can find sample requests below for different header types (text, image, video, and document) as well as for all button options you can use when creating your conversational WhatsApp template messages.
Header Samples
You can use these sample requests to add different header components to your conversational template messages:
Image Header
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************************' \
--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": "header",
"parameters": [
{
"type": "image",
"image":{
"link": "{{IMAGE_URL}}"
}
}
]
}
]
}
}
}
]
}'Video Header
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************************' \
--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": "header",
"parameters": [
{
"type": "video",
"video":{
"link": "{{VIDEO_URL}}"
}
}
]
}
]
}
}
}
]
}'Document Header
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************************' \
--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": "header",
"parameters": [
{
"type":"document",
"document":{
"link":"{{DOCUMENT_LINK}}",
"filename":"{{FILE_NAME}}"
}
]
}
]
}
}
}
]
}'Button Samples
You can use these sample requests if you want to include buttons in your template messages:
Quick Reply Buttons
Select the Quick Reply button while creating your template message, then enter the text you want to display on each button.
Refer to the visual below for an example of how Quick Reply buttons are displayed in a conversational WhatsApp template.
You can use the sample request below if you want to use the quick reply buttons:
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************************' \
--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"
}
]
}
]
}
}
}
]
}'After sending the request above, proceed to create your quick reply responses. Refer to the sample response below to create responses for each quick reply button:
Refer to the Send Conversational WhatsApp Message with Button Reply (Quick Reply) to learn more about the Button Reply parameters.
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************' \
--data '{
"messages": [
{
"phoneNumber": "+1**********",
"message": {
"type": "interactive",
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "HEADER_TEXT"
},
"body": {
"text": "BUTTON_TEXT"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "UNIQUE_BUTTON_ID_1",
"title": "BUTTON_TITLE_1"
}
},
{
"type": "reply",
"reply": {
"id": "UNIQUE_BUTTON_ID_2",
"title": "BUTTON_TITLE_2"
}
}
]
}
}
}
}
]
}'Call to Action Buttons
You can add call-to-action (CTA) buttons, such as "call us" or "visit the website," to your conversational message template (promotional use case) to increase user engagement. You can only include 2 CTAs - one to direct to a link and the other one to call a phone number; it cannot be two buttons with links.
Refer to the visual below for an example of how a CTA button is displayed in a transactional WhatsApp template.
If you want to use CTA buttons in your Conversational WhatsApp template message, you can use the sample request below:
curl --location 'https://whatsapp.useinsider.com/v1/conversational/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"
}
]
}
]
}
}
}
]
}'No Buttons
If you don’t want to include a button in your Conversational WhatsApp template message, select None when creating the template.
To use the None option, refer to the sample request below:
curl --location 'https://whatsapp.useinsider.com/v1/conversational/send' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.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.
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.