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

  1. 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.
  2. To set up a WhatsApp account on kaleyra.io, see Manual Signup
    and Embedded Signup.
  3. 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_domainValue
IN podapi.in.kaleyra.io
SG Podapi.ap.kaleyra.io
EU Podapi.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 / HeadersData TypeDescriptionExampleMandatory?
sidStringAccount SID (Security Identifier).HXAP16XXXXXX97INYes
waba_idStringWhatsApp Business Account. For more information, see step 1 to step 3 of Adding a new WABA ID.1090xxxxxxxxxxxxYes
Content-TypeStringIndicates the format of the content the API will be processing.The only allowed value is application/json.Yes
api-keyStringAPI key generated from kaleyra.io account.Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3Yes

Following is the list of attributes to be used in the payload to send the WhatsApp template:

ParameterData TypeDescriptionExampleMandatory?
template_objectJSON objectPayload 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:

ParameterData TypeDescriptionExampleMandatory?
nameStringA title for the WhatsApp template. Contain only lowercase alphanumeric characters and underscores (_). Other characters or white space are not allowed.seasonal_promotionYes
languageStringThe language in which, you want to create the template. The default is English.en_USYes
categoryStringSelect one of the following:

- Marketing
- Authentication
- Utility
marketingYes
message_send_ttl_secondsStringSpecify 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.
120Yes
componentsJSON objectComponents 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:

ParameterData TypeDescriptionExampleMandatory?
typeStringHeaders are optional components that appear at the top of template messages. Headers support text, media (images, videos, documents), and locations.HEADERNo
formatStringFormat of the Header. If omitted, defaults to text. The supported formats are:

- text
- images
- videos
- documents
- location
textNo
textStringThe 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_textStringThe 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:

ParameterData TypeDescriptionExampleMandatory?
typeStringBody components are text-only components and are required by all templates.BODYYes
textStringThe text you want to display in body. Up to 1024 characters are allowedShop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.Yes
body_textStringThe 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:

ParameterData TypeDescriptionExampleMandatory?
typeStringFooters are optional text-only components that appear immediately after the body component. Templates are limited to one footer component.FOOTERNo
textStringThe text you want to display in footer.Use the buttons below to manage your marketing subscriptionsNo

The following table describes the different attributes used for the components for the BUTTONS JSON object:

ParameterData TypeDescriptionExampleMandatory?
typeStringIt can be one of the following:

- QUICK_REPLY
- PHONE_NUMBER
- URL
Note: For adding a CTA based on URL, select URL
QUICK_REPLYNo
textStringThe text you want to display in button.Unsubscribe from PromosNo
phone_number
Use only when type is PHONE_NUMBER
StringPhone number buttons call the specified business phone number when tapped by the end-user. Templates are limited to one phone number button.+91XXXXXXXXXXNo (Mandatory when type is PHONE_NUMBER)
url
Use only when type is URL.
StringURL 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/shopNo (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"
    }
}