Send Transactional WhatsApp Template Message

Transactional WhatsApp API enables you to send targeted transactional WhatsApp messages to your users. You can trigger these WhatsApp messages once a user takes a specific action on your platform.

Refer to the visual below for an example of how a transactional WhatsApp template message is displayed.

Endpoint and Headers

Headers

Body Parameters

Sample Requests

You can find sample requests below for different header types (text, image, video, and document) as well as for all button options available when creating your transactional WhatsApp template messages.

Header Samples

You can use these sample requests to add different header components to your transactional template messages:

Image Header

curl --location 'https://whatsapp.useinsider.com/v1/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/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/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.

See the visual below for an example of how Quick Reply buttons are displayed in a transactional 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/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"
                                }
                            ]
                        }
                    ]
                }
            }
        }
    ]
}'

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 Transactional WhatsApp Message with Button Reply (Quick Reply) to learn more about the Button Reply parameters.

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": "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 promotional message template 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.

See 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 Transactional WhatsApp template message, you can use the sample request below:

curl --location 'https://whatsapp.useinsider.com/v1/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": "url",
                            "index": "0",
                            "parameters": [
                                {
                                    "type": "text",
                                    "text": ""
                                }
                            ]
                        }
                    ]
                }
            }
        }
    ]
}'

Meta does not allow the URL to be empty when creating a template. For this reason, at least the domain part of the URL must be entered during template creation. Alternatively, you can enter the entire URL you want to send.

If you want to send the same URL to all users, select "Custom Link" while creating the template and define the shared URL. Make sure to leave the text field empty in the message payload, as shown in the example below:

{
  "type": "button",
  "sub_type": "url",
  "index": "0",
  "parameters": [
    {
      "type": "text",
      "text": ""
    }
  ]
}

Leaving the text field empty ensures that the URL defined during template creation is sent exactly as-is to the end user. If you want to customize the URL path for each user, you must provide the remaining part of the URL dynamically in the message payload. For example, suppose you want to send the following URL, where the part products?userId=1000 is unique for each user: https://inone.useinsider.com/products?userId=1000

To achieve this:

1. While creating the template, select "Custom Link" and define only the common domain part of the URL (e.g., https://inone.useinsider.com/).

2. At the message sending stage, include the rest of the path as a parameter value.

{
   "type": "button",
   "sub_type": "url",
   "index": "0",
   "parameters": [
       {
           "type": "text",
           "text": "products?userId=1000"
       }
   ]
}

Meta will automatically concatenate the base domain defined in the template (https://inone.useinsider.com/) with the value provided in the message payload (products?userId=1000). As a result, the full URL sent to the user will be: https://inone.useinsider.com/products?userId=1000

No Buttons

If you don’t want to include a button in your Transactional 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/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-*************************"
    ]
}

401 Unauthorized

If you use the wrong key, you will see the following error:

{
    "message": "unauthorized"
}

429 Rate Limit

If you send more than 1000 requests per second, you will see the following error:

{
    "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:

{
  "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:

• 403 Error Troubleshooting Guide

• User-Agent Blocking Documentation

• Security Events (Firewall Events) Dashboard

• 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.