Create Template
POST Method
The Create Template API allows you to create a WhatsApp template. You can use the WhatsApp template to send a WhatsApp message to an end-user with a predefined format with variables that can be updated based on your choice. Your WhatsApp template must be approved before you can use it to send WhatsApp messages from Meta. For more information on how to create and manage the WhatsApp Templates by Meta, see Create and Manage Templates.
Note:
Marketing, Authentication, and Utility template categories are supported by Kaleyra.
Prerequisites
- Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on kaleyra platform. - To set up a WhatsApp account on kaleyra.io, see Manual Signup
and Embedded Signup. - An active WhatsApp for Business API plan that includes:
- A WhatsApp business number.
- An associated profile with the business number.
- A WhatsApp verified and approved profile.
Limitations
- Rate limit for the Create template API is 100 per WhatsApp Business Account (WABA) per hour.
- The message template name field is limited to 512 characters.
- The message template content field is limited to 1024 characters.
- Templates composed of four or more buttons, or a quick reply button and one or more buttons of another type cannot be viewed on WhatsApp desktop clients. WhatsApp users who receive one of these template messages will be prompted to view the message on a phone instead.
Base URL
https://<api_domain>/v2/<SID>
API Domain and Value
api_domain | Value |
---|---|
IN pod | api.in.kaleyra.io |
SG Pod | api.ap.kaleyra.io |
EU Pod | api.eu.kaleyra.io |
API request to create WhatsApp Template
To create WhatsApp Template, use the https://<api_domain>/v2/<sid>/whatsapp/<waba_id>/message_templates
endpoint with the following request method:
Request Format
The following is the request format to create WhatsApp Template:
curl -L -X POST \
https://<api_domain>/v2/<sid>/whatsapp/<waba_id>/message_templates \
-H 'Content-Type: application/json' \
-H 'api-key: <api-key>' \
-H 'cache-control: no-cache' \
-d '{
"template_object": {
"name": "<name>",
"language": "<language>",
"category": "<category>",
"message_send_ttl_seconds": <message_send_ttl_seconds>,
"components": [
{
"type": "HEADER",
"format": "<format>",
"text": "<text>",
"example": {
"header_text": [
"<header_text>"
]
}
},
{
"type": "BODY",
"text": "<text>",
"example": {
"body_text": [
[
"<body_text>"
]
]
}
},
{
"type": "FOOTER",
"text": "<type>"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "<text>"
},
{
"type": "QUICK_REPLY",
"text": "<text1>"
}
]
}
]
}
}'
Sample Request Format
The following is the sample request format to create a WhatsApp Template:
curl -L -X POST \
https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/1090xxxxxxxxxxxx/message_templates \
-H 'Content-Type: application/json' \
-H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
-H 'cache-control: no-cache' \
-d '{
"template_object": {
"name": "seasonal_promotion",
"language": "en_US",
"category": "marketing",
"message_send_ttl_seconds": 120, // Configure your TTL in seconds below, optional
"components": [
{
"type": "HEADER",
"format": "text",
"text": "Our {{1}} is on!",
"example": {
"header_text": [
"Summer Sale"
]
}
},
{
"type": "BODY",
"text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
"example": {
"body_text": [
[
"the end of August",
"25OFF",
"25%"
]
]
}
},
{
"type": "FOOTER",
"text": "Use the buttons below to manage your marketing subscriptions"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Unsubscribe from Promos"
},
{
"type": "QUICK_REPLY",
"text": "Unsubscribe from All"
}
]
}
]
}
}'
URL Parameters and Headers
Following is the list of parameters and headers to send the outgoing message request:
Parameter / Headers | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
sid | String | Account SID (Security Identifier). | HXAP16XXXXXX97IN | Yes |
waba_id | String | WhatsApp Business Account. For more information, see step 1 to step 3 of Adding a new WABA ID. | 1090xxxxxxxxxxxx | Yes |
Content-Type | String | Indicates the format of the content the API will be processing. | The only allowed value is application/json. | Yes |
api-key | String | API key generated from kaleyra.io account. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
Following is the list of attributes to be used in the payload to send the WhatsApp template:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
template_object | JSON object | Payload is supported only in JSON format. The template_object is the payload that contains the template object as defined by Meta, which can be used to send the WhatsApp message with a predefined format. | See the specific table for details. | Yes |
The following table describes the different attributes used for the template_object
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
name | String | A title for the WhatsApp template. Contain only lowercase alphanumeric characters and underscores (_ ). Other characters or white space are not allowed. | seasonal_promotion | Yes |
language | String | The language in which, you want to create the template. The default is English. | en_US | Yes |
category | String | Select one of the following: - Marketing - Authentication - Utility | marketing | Yes |
message_send_ttl_seconds | String | Specify a custom TTL value for message delivery in seconds. Authentication templates: 30 to 900 seconds (30 secs to 15 mins). Utility templates: 30 to 43200 seconds (30 secs to 12 hours). Marketing templates: 43200 to 2592000 (12 hours to 30 days). For more information, see Time-To-Live (TTL): Customization, Defaults, Min/Max Values, and Compatibility section. | 120 | Yes |
components | JSON object | Components that you want to add to the WhatsApp template. | See the specific table for details. | Yes |
The following table describes the different attributes used for the components
for the HEADER JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
type | String | Headers are optional components that appear at the top of template messages. Headers support text, media (images, videos, documents), and locations. | HEADER | No |
format | String | Format of the Header. If omitted, defaults to text. The supported formats are: - text - images - videos - documents - location | text | No |
text | String | The text you want to display in the header. For Media the format has to be passed as: - images - videos - documents - location | Our {{1}} is on! | No |
header_text | String | The header_text details will replace the variable in text . | "Summer Sale" | No |
The following table describes the different attributes used for the components
for the BODY JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
type | String | Body components are text-only components and are required by all templates. | BODY | Yes |
text | String | The text you want to display in body. Up to 1024 characters are allowed | Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise. | Yes |
body_text | String | The body_text details will replace the variable in text . | "the end of August", "25OFF", "25%" | Yes |
The following table describes the different attributes used for the components
for the FOOTER JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
type | String | Footers are optional text-only components that appear immediately after the body component. Templates are limited to one footer component. | FOOTER | No |
text | String | The text you want to display in footer. | Use the buttons below to manage your marketing subscriptions | No |
The following table describes the different attributes used for the components
for the BUTTONS JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
type | String | It can be one of the following: - QUICK_REPLY - PHONE_NUMBER - URL Note: For adding a CTA based on URL, select URL | QUICK_REPLY | No |
text | String | The text you want to display in button. | Unsubscribe from Promos | No |
phone_number Use only when type is PHONE_NUMBER | String | Phone number buttons call the specified business phone number when tapped by the end-user. Templates are limited to one phone number button. | +91XXXXXXXXXX | No (Mandatory when type is PHONE_NUMBER) |
url Use only when type is URL. | String | URL buttons load the specified URL in the device's default web browser when tapped by the end-user. Templates are limited to two URL buttons. | https://www.google.com/shop | No (Mandatory when type is URL). |
Supported Button Types with Example
Phone number button
Phone number buttons call the specified business phone number when tapped by the app user. Templates are limited to one phone number button.
{
"type": "PHONE_NUMBER",
"text": "Call",
"phone_number": "15550051310"
}
URL button
URL buttons load the specified URL in the device's default web browser when tapped by the end-user. Templates are limited to two URL buttons.
{
"type": "URL",
"text": "Shop Now",
"url": "https://www.google.com/shop",
"example": [
"summer2023"
]
}
Quick reply button
Quick reply buttons are custom text-only buttons that immediately message with the specified text string when tapped by the end-user. Templates are limited to 10 quick reply buttons.
{
"type": "QUICK_REPLY",
"text": "<TEXT>"
}
Copy code button
Copy code buttons copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the end-user. Templates are limited to one copy code button.
{
"type": "COPY_CODE",
"example": "250FF"
}
Sample Success Response
The following success message appears with the status 200 Accepted:
200 Success
{
"code": "WA200",
"message": "Request Processed Successfully",
"data": {
"id": "<ID>",
"status": "<STATUS>",
"category": "<CATEGORY>"
},
"error": {}
}
Sample Failure Response
The following are the failure responses:
401 Unauthorized
{
"code": "RBC001",
"message": "Incorrect SID or API key.",
"data": [],
"error": {
"error": "Incorrect SID or API key."
}
}
401 Wrong account
{
"code": "WA-401",
"message": "API is not available for given customer.Please contact support for more info",
"data": {},
"error": "API is not available for given customer.Please contact support for more info"
}
401 Unauthorized WABA
{
"code": "WA401",
"message": "Waba_Id is not present or does not belong to the account.",
"data": {},
"error": {
"waba_id": "Waba_Id is not present or does not belong to the account."
}
}
401 Unauthorized WABA version
{
"code": "WA401",
"message": "The waba_id you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
"data": {},
"error": {
"waba_id": "The waba_id you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
}
}
400 Incorrect payload
{
"code": "WA-400",
"message": "Refer to correct payload format",
"data": {},
"error": {
"payload": "Incorrect payload format"
}
}
500 Internal Server Error
{
"code": "WA-500",
"message": "Please try again later",
"data": {},
"error": {
"error": "Internal server error"
}
}
429 Too many requests
{
"code": "WA429",
"message": "Too many requests",
"data": {},
"error": {
"error": "Too many requests sent from this waba in a short period of time, please try after sometime"
}
}
Updated about 14 hours ago