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.
- A WABA ID onboarded on Kaleyra WhatsApp API V2.

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.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.na.kaleyra.ai

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 7 days ago