×

Use the create templates API to create & submit templates to WhatsApp for approval. The API supports both single and bulk create.

POST

https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/templates

  • Replace <your_api_key> and <your_api_token> with the API key and token created by you.
  • Replace <your_sid> with your “Account sid”
  • Replace <subdomain> with the region of your account
    1. <subdomain> of Singapore cluster is @api.exotel.com
    2. <subdomain> of Mumbai cluster is @api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

Listed below are the parameters for the POST API.

HTTPRequestObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

waba_id

String

Mandatory

Waba ID

 

Parameter Name

Type

Mandatory/ Optional

Value/ Description

custom_data

String

Optional

If the client wants to send any custom data at the request level. This will be passed back to the customer in the callback.

whatsapp

ChannelObject

Optional

Information related to the messages to be sent out on whatsapp

ChannelObject

Parameter

Type

Mandatory

Notes

custom_data

String

Optional

If the client wants to send any custom data at the channel level. This will be passed back to the customer in the callback.

messages

[]TemplateObject

Mandatory

Array of messages to be sent out

TemplateObject

Parameter Name

Type

Mandatory

Value/ Description

custom_data

String

Optional

If the client wants to send any custom data at the message level. This will be passed back to the customer in the callback.

template

WhatsappTemplateObject

Mandatory

Respective channel specific template body

WhatsappTemplateObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

category

String

Mandatory

Category of the template

name

String

Mandatory

Name of the template

language

String

Mandatory

Language of the template

components

[]ComponentObject

Mandatory

Components of the template

ComponentObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

type

String

Mandatory

Type of the component

text

String

Mandatory/Optional

Mandatory in case of type FOOTER/BODY/URL and TEXT HEADER

format

String

Mandatory/Optional

Mandatory in case of type HEADER

buttons

[]ButtonObject

Mandatory/Optional

Mandatory in case of type BUTTONS

url

String

Mandatory/Optional

Mandatory in case of type URL

example

ExampleObject

Mandatory/Optional

Mandatory in case of dynamic variables or media header

example

[]String

Mandatory/Optional

Mandatory in case of dynamic variables in type URL

 
ButtonObject

Parameter Name

Type

Mandatory/ Optional

Values/ Description

type

String

Optional

Fallback value of datetime

text

Integer

Optional

Day of Week of datetime

phone_number

Integer

Optional

Day of month of datetime

ExampleObject

Parameter Name

Type

Mandatory

Value/ Description

body_text

[][]String

Mandatory

Type of the parameter

header_text

[]String

Optional

Text for the parameter

header_handle

[]String

Optional

Caption for the parameter

 

Create Text Templates

curl --location --request POST 'https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/templates?waba_id=<Your WABA ID>' \

--header 'Content-Type: application/json' \

--data-raw '{
  "whatsapp": {
    "templates": [
      {
        "template": {
          "category": "TRANSACTIONAL",
          "components": [
            {
              "type": "HEADER",
              "format": "TEXT",
              "text": "Greetings from Exotel {{1}}",
              "example": {
                "header_text": [
                  "John Doe"
                ]
              }
            },
            {
              "type": "BODY",
              "text": "Hi {{1}}, your one time password is {{2}}.",
              "example": {
                "body_text": [
                  [
                    "John",
                    "1234"
                  ]
                ]
              }
            },
            {
              "type": "FOOTER",
              "text": "Thanks"
            }
          ],
          "name": "test_template4605",
          "language": "en"
        }
      }
    ]
  }
}'
var https = require('follow-redirects').https;

var fs = require('fs');

var options = {

'method': 'POST',

'hostname': '<Sub domain>',

'path': '/v2/accounts/<Your SID>/templates?waba_id=<Your WABA ID',

'headers': {

'Content-Type': 'application/json'

},

'maxRedirects': 20

};

var req = https.request(options, function (res) {

varchunks= [];

res.on("data", function (chunk) {

chunks.push(chunk);

});

res.on("end", function (chunk) {

varbody=Buffer.concat(chunks);

console.log(body.toString());

});

res.on("error", function (error) {

console.error(error);

});

});

var postData = "{\n \"whatsapp\": {\n \"templates\": [\n {\n \"template\": {\n \"category\": \"TRANSACTIONAL\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"format\": \"TEXT\",\n \"text\": \"Greetings from Exotel {{1}}\",\n \"example\": {\n \"header_text\": [\n \"John Doe\"\n ]\n }\n },\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, your one time password is {{2}}.\",\n \"example\": {\n \"body_text\": [\n [\n \"John\",\n \"1234\"\n ]\n ]\n }\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Thanks\"\n }\n ],\n \"name\": \"test_template4605\",\n \"language\": \"en\"\n }\n },\n \n \n }\n}";

Create Carousel Templates

This section describes limited-time offer templates and how to create them.

This document describes carousel templates and how to use them. Carousel templates allow you to send a single text message accompanied by a set of up to 10 carousel cards in a horizontally scrollable view:

Limitations

  • Only templates categorized as MARKETING are supported.
  • Footer components are not supported.

Carousel Cards

  • Carousel templates support up to 10 carousel cards. Cards must have a media header (image or video), body text, and at least one button. Supports 2 buttons. Buttons can be the same or a mix of quick reply buttons, phone number buttons, or URL buttons.
  • The media header format and button types must be the same across all cards that make up a carousel template.
  • Media assets will be cropped to a wide ratio based on the customer's device.

Example Request

This is an example request to create a limited-time offer template that uses:

  • a bubble text variable
  • card index: Zero-indexed order in which card appears within the card carousel. 0 indicates the first card, 1 indicates the second card, etc (Required)
  • a card body with variable: There is no maximum character limit on this value, but counts against the card body text limit of 160 characters.
  • an image header
  • body text with variables
  • the offer expiration details: Offer code expiration time as a UNIX timestamp in milliseconds (Required)
  • a copy code button: if the template uses a copy code button. Maximum 15 characters (Required)
  • a URL button with a variable
curl --location --globoff 'https://{{AuthKey}}:{{AuthToken}}@{{SubDomain}}/v2/accounts/{{AccountSid}}/templates?waba_id=XXXX' \
--header 'Content-Type: application/json' \
--data '{
    "whatsapp": {
        "templates": [
            {
                "template": {
                    "name": "freshlemons",
                    "language": "en",
                    "category": "MARKETING",
                    "components": [
                        {
                            "type": "BODY",
                            "text": "Summer is here, and we have the freshest produce around! Use code {{1}} to get off your next order.",
                            "example": {
                                "body_text": [
                                    [
                                        "10OFF"
                                    ]
                                ]
                            }
                        },
                        {
                            "type": "CAROUSEL",
                            "cards": [
                                {
                                    "components": [
                                        {
                                            "type": "HEADER",
                                            "format": "IMAGE",
                                            "example": {
                                                "header_handle": [
                                                    "4::aW1hZ2UvanBlZw==:ARZhLHkWRwgoZRYbxSIxQIdstWiwO5FHUkBDI3ooXC-IGD9M_D5hvl3B8PQagOQNGB-rjsYGU8iL6_0kXgnowUWwyhP7bt8YVZfFdB2wtNDKrw:e:1707639843:3157993617821787:100032495207268:ARYY2kQwqaawGbzDgcg"
                                                ]
                                            }
                                        },
                                        {
                                            "type": "BODY",
                                            "text": "Fresh lemons for unique drinks. Use code {{1}} to get off all produce. Rare lemons for unique drinks.",
                                            "example": {
                                                "body_text": [
                                                    [
                                                        "10OFF"
                                                    ]
                                                ]
                                            }
                                        },
                                        {
                                            "type": "BUTTONS",
                                            "buttons": [
                                                {
                                                    "type": "QUICK_REPLY",
                                                    "text": "Send more like this"
                                                },
                                                {
                                                    "type": "URL",
                                                    "text": "Buy now",
                                                    "url": "https://www.luckyshrub.com/shop?promo={{1}}",
                                                    "example": [
                                                        "https://www.luckyshrub.com/shop?promo=summer_lemons_2023"
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "components": [
                                        {
                                            "type": "HEADER",
                                            "format": "IMAGE",
                                            "example": {
                                                "header_handle": [
                                                    "4::aW1hZ2UvanBlZw==:ARbm6XvaVpVMwQQMNt0xFZ5tNgludWS9WOAkrAuL7ki7wbHbqatwGARYrYtvzDoLiZn7nHeU4VqUMpF6RlVdMw8UoQThdl5FI6OsHxxG-AL9EA:e:1707640228:3157993617821787:100032495207268:ARaGMPetuhoCIQfYU8I"
                                                ]
                                            }
                                        },
                                        {
                                            "type": "BODY",
                                            "text": "Exotic fruit for unique cocktails! Use code {{1}} to get off all exotic produce.",
                                            "example": {
                                                "body_text": [
                                                    [
                                                        "20FRUITS"
                                                    ]
                                                ]
                                            }
                                        },
                                        {
                                            "type": "BUTTONS",
                                            "buttons": [
                                                {
                                                    "type": "QUICK_REPLY",
                                                    "text": "Send more like this"
                                                },
                                                {
                                                    "type": "URL",
                                                    "text": "Buy now",
                                                    "url": "https://www.luckyshrub.com/shop?promo={{1}}",
                                                    "example": [
                                                        "https://www.luckyshrub.com/shop?promo=exotic_produce_2023"
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}'

Body Properties

Placeholder Description Example Value

<BUBBLE_TEXT>

String

Required.


Message bubble text string. Supports variables.


Maximum 1024 characters.

Summer is here, and we've got the freshest produce around! Use code {{1}} to get {{2}} off your next order.

<BUBBLE_TEXT_VAR_EXAMPLE>

Array of strings

Required if the message bubble text string uses variables.


Array of example variable strings. Number of strings must match the number of variables included in the string.

"15OFF","15%"

<CARD_BODY_TEXT>

String

Required.


Card body text. Support variables.


Maximum 160 characters.

Rare lemons for unique cocktails. Use code {{1}} to get {{2}} off all produce.

<CARD_BODY_TEXT_VAR_EXAMPLE>

Array of strings

Required if using card body text with variables.


Card body text example variables.

"15OFF","15%"

<CARD_HEADER_FORMAT>

Enum

Required.


Card media header format. Must be IMAGE or VIDEO.

IMAGE

<CARD_HEADER_HANDLE>

Media asset handle

Required.


Uploaded media asset handle. Use the Resumable Upload API to generate an asset handle.


See Carousel Cards for media asset requirements.

4::aW...

<QUICK_REPLY_BUTTON_TEXT>

String

Required if using a quick reply button.


Quick reply button label text.


Maximum 25 characters.

Send more like this

<TEMPLATE_CATEGORY>

Enum

Required.


Must be MARKETING or UTILITY.

MARKETING

<TEMPLATE_LANGUAGE>

Enum

Required.


Template language and locale code.

en_US

<TEMPLATE_NAME>

String

Required.


Template name.


Maximum 512 characters.

summer_carousel_promo_2023

<URL_BUTTON_TEXT>

String

Required if using a URL button.


URL button label text. Supports 1 variable.


25 characters maximum.

Buy now

<URL_BUTTON_URL>

String

Required if using a URL button.


URL of website that loads in the device's default mobile web browser when the URL button is tapped by the app user.


Supports 1 variable, appended to the end of the URL string.


Maximum 2000 characters.

https://www.luckyshrub.com/shop?promo={{1}}

<URL_BUTTON_VAR_EXAMPLE>

String

Required if using a URL button.


URL of website. Supports 1 variable.


If using a variable, add sample variable property to the end of the URL string. The URL loads in the device's default mobile web browser when the customer taps the URL button.


Maximum 2000 characters.

https://www.luckyshrub.com/shop?promo=summer_lemons_2023

Create Limited-Time Offer Templates

This section describes limited-time offer templates and how to use them.

Limited-time offer templates allow you to display expiration dates and running countdown timers for offer codes in template messages, making it easy for you to communicate time-bound offers and drive customer engagement.

Limitations

  • Only templates categorized as MARKETING are supported.
  • Footer components are not supported.
  • Users who view a limited-time offer template message using that WhatsApp web app or desktop app will not see the offer, but will instead see a message indicating that they have received a message but that it's not supported in the client they are using.

Offer Expiration Details

The delivered message can display an offer expiration details section with a heading, an optional expiration timer, and the offer code itself.

The expiration timer is a text string that is not customizable, but it will change to red text if the message is viewed and the offer code is expiring within the next hour. (You include the actual offer code and its expiration timestamp when you send the template in a template message.)

Example Request

This is an example request to create a limited-time offer template that uses:

  • an image header component
  • body text component with variables
  • the limited time offer component
  • a copy code button
  • a button URL with a variable
curl --location 'https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/templates?waba_id=11149XXXXXX' \
--header 'Content-Type: application/json' \
--data '{
  "whatsapp": {
    "templates": [
      {
        "template": {
          "name": "limited_time_offer_test",
          "language": "en",
          "category": "marketing",
          "components": [
            {
              "type": "limited_time_offer",
              "limited_time_offer": {
                "text": "Expiring offer!",
                "has_expiration": false
              }
            },
            {
              "type": "body",
              "text": "Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!",
              "example": {
                "body_text": [
                  [
                    "Kaustubh",
                    "SALE25"
                  ]
                ]
              }
            },
            {
              "type": "buttons",
              "buttons": [
                {
                  "type": "copy_code",
                  "example": "SALE25"
                },
                {
                  "type": "url",
                  "text": "Book now!",
                  "url": "https://awesomedestinations.com/offers?code={{1}}",
                  "example": [
                    "https://awesomedestinations.com/offers?code=n3mtql"
                  ]
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Body Properties

Placeholder Description Example Value

<BODY_TEXT>

String

Required.


Body component text. Supports variables.


Maximum 600 characters.

Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!

<BODY_TEXT_VARIABLE_EXAMPLES>

Array of strings

Required if body component text uses variables.


Array of example variable strings.


Must supply examples for all placeholders in <BODY_TEXT> string.


No maximum, but counts against <BODY_TEXT> maximum.

["Pablo","CARIBE25"]

<HAS_EXPIRATION>

Boolean

Optional.


Set to true to have the offer expiration details appear in the delivered message.

true

<HEADER_ASSET_HANDLE>

Media asset handle

Required if using an image or video header.


Uploaded media asset handle. Use the Resumable Upload API to generate an asset handle.

4::aW...

<HEADER_FORMAT>

Enum

Required if using a header.


Can be IMAGE, or VIDEO.

IMAGE

<LIMITED_TIME_OFFER_TEXT>

String

Required.


Offer details text.


Maximum 16 characters.

Expiring offer!

<OFFER_CODE_EXAMPLE>

String

Required.


Example offer code.


Maximum 15 characters.

CARIBE25

<TEMPLATE_LANGUAGE>

Enum

Required.


Template language and locale code.

en_US

<TEMPLATE_NAME>

String

Required.


Template name.


Maximum 512 characters.

limited_time_offer_caribbean_pkg_2023

<URL_BUTTON_TEXT>

String

Required.


URL button label text. Supports 1 variable.


25 characters maximum.

Book now!

<URL_BUTTON_URL>

String

Required.


URL of website that loads in the device's default mobile web browser when the URL button is tapped by the WhatsApp user.


Supports 1 variable appended to the end of the URL string.


Maximum 2000 characters.

https://awesomedestinations.com/offers?code={{1}}

<URL_EXAMPLE_WITH_VARIABLE_EXAMPLE>

String

Required if URL uses a variable.


Example URL with example variable appended to the end.


No maximum, but value counts against <URL_BUTTON_URL> maximum.

https://awesomedestinations.com/offers?ref=n3mtql

HTTP Response

  • On success, the HTTP response status code will be 200.
{
  "request_id": "72f3624613a84932823f838fcecf7389",
  "method": "POST",
  "http_code": 200,
  "metadata": {
    "failed": 0,
    "total": 1,
    "success": 1
  },
  "response": {
    "whatsapp": {
      "templates": [
        {
          "code": 200,
          "error_data": null,
          "status": "success",
          "data": {
            "id": "903269234317278"
          }
        }
      ]
    }
  }
}

HTTPResponseObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

request_id

String

Mandatory

ID of the request

method

String

Mandatory

HTTP Request Method

http_code

Integer

Mandatory

HTTP Code of the request

metadata

MetadataObject

Mandatory

Metadata pertaining to the request

response

ResponseObject

Mandatory

Response for the request

MetadataObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

total

Integer

Mandatory

Total number of the messages in the request

success

Integer

Mandatory

Number of messages successfully accepted

failed

Integer

Mandatory

Number of messages that couldn’t be accepted

ResponseObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

whatsapp

ChannelResponseObject

Optional

Channel Response for Whatsapp

ChannelResponseObject

Parameter Name

Type

Mandatory/ Optional

Description

templates

[]CreateTemplateResponseObject

Optional

Message Response

CreateTemplateResponseObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

code

Integer

Mandatory

Response code for the message

error_data

ErrorResponseObject

Optional

Error related to message

status

String

Mandatory

Status of the message

data

TemplateResponseObject

Optional

Data for the message

ErrorResponseObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

code

Numeric

Mandatory

Numeric error code

message

String

Mandatory

Brief explanation of error

description

String

Mandatory

Detailed explanation of error

TemplateResponseObject

Parameter Name

Type

Mandatory/ Optional

Value/ Description

id

String

Mandatory

id (Unique identifier) of the template

custom_data

String

Mandatory

Custom data passed in the request