Add a WhatsApp Template

POST Method

Kaleyra offers an API to add a WhatsApp template. This API is an extension to the User Interface (UI) feature of Add Template. After successful submission of Add WhatsApp Template API, you can view them on Kaleyra UI.

You can add the WhatsApp templates via an API using the following details:

Name
Language (Language code value. For example - "en").
Category

📘
Note:
Starting from March 27th, 2023 template categories Marketing, Authentication, and Utility are supported by Kaleyra. For more information, see the WhatsApp Template Category page.

Header (Optional - Text, Video, Image, Document, or None).
Body (Variable as {{$1}})
Footer (Optional).
- Type - quick_reply
  - quick_reply_1
  - quick_reply_2
  - quick_reply_3
- Type - phone
  - button_text
  - phone_no (With country code).
- Type - URL
  - url_type (static or dynamic)
  - button_text
  - website_url
  - phone (Optional).
    - button_text
    - phone_no (With country code).

📘
Notes:

You have the option to configure buttons, which allows you to get the response from your recipient with simple text or actions.

All the field values in API have the same validations as the UI.

Signup or Login to Kaleyra.io and create your API key.

Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.

📘
Note:
After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in Kaleyra.io.

Prerequisite:

A WhatsApp business number.
An associated profile with the business number.
A WhatsApp verified and approved profile.

For more details, read what WhatsApp has to say about creating a business account.

Base URL

https://<api_domain>/v1/<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 command to Add a WhatsApp Template.

To add WhatsApp template, use the whatsapp/template endpoints.

Request Format

The following is the request format to add a WhatsApp template:

curl --location 'https://<api_domain>/v1/<sid>/whatsapp/template' \
--header 'api-key: <api_key>' \
--form 'name="<template_name>"' \
--form 'category="<category>"' \
--form 'language="<language>"' \
--form 'header="{\"type\":\"<header_type>\"}";type=<content_type>' \
--form 'body="<body>"' \
--form 'sample_body="<sample_body>"' \
--form 'footer="<footer>"' \
--form 'allow_category_change="<category_change_parameter>"' \
--form 'button_data="[{
           \"type\":\"<type>\",
            \"phone_number_text\":\"<phone_number_text>\",
            \"phone_number\":\"<phone_number>\"
}]
]";type=<type>'

Sample Request Format

The following is the sample request format to add a WhatsApp template:

curl --location 'https://api.in.kaleyra.io/v1/HXXXXXXX071IN/whatsapp/template' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--form 'name="whatsapp_template"' \
--form 'category="marketing"' \
--form 'language="en"' \
--form 'header="{\"type\":\"none\"}";type=application/json' \
--form 'body="We are opening new jewelry shop near yekta nagar, get 2 percent offer"' \
--form 'sample_body="Buy Mivi DuoPods F30+ Collar D25(Free) at Just Rs 1299/-"' \
--form 'footer="This is the footer message"' \
--form 'allow_category_change="1"' \
--form 'button_data="[{
           \"type\":\"phone_number\",
            \"phone_number_text\":\"Call\",
            \"phone_number\":\"+91XXXXXXXXXX\"
}]";type=application/json'

📘
Note:
Replace the placeholders above with relevant values as mentioned below.

Parameters and Data Types

The following is the list of parameters and data types supported to add a WhatsApp template:

Parameter	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.	HXXXXXXX071IN	Yes
`api-key`	String	API key generated from kaleyra.io account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3
`name`	String	Indicates the name of the WhatsApp template.	whatsapp_template	Yes
`category`	String	Indicates the business category of the WhatsApp template. For more information, see WhatsApp Template Category page. The supported types are Marketing, Authentication, and Utility.	marketing	Yes
`language`	String	Indicates the language code value for the WhatsApp template language.	en	Yes
`header_type`	String	Indicates the header type for WhatsApp template.	none	No
`content_type`	Alphanumeric	Indicates the format of the content the API will be processing.	application/JSON	Yes
`body`	String	Defines the body content of the WhatsApp template.	We are opening new jewelry shop near yekta nagar, get 2 percent offer	Yes
`sample_body`	String	Defines the sample body content of the WhatsApp template.	Buy Mivi DuoPods F30+ Collar D25(Free) at Just Rs 1299/-	Yes
`footer`	String	Indicates the text footer content for the WhatsApp template.	This is the footer message	No
`allow_category_change`	String	Supported options are 0 and 1.	1	Yes
`button_data`	JSON	Contains an array of values, where each JSON value have button related data.	{ "type":"phone_number", "phone_number_text":"call", "phone_number":"+91XXXXXXXXXX" }	No

The following table lists the button_data attribute:

Parameter	Data Type	Description	Example	Mandatory?
`type`	String	Defines the button type. button type can be quick_reply, phone_number, url, otp, copy_code, catalog, mpm.	phone number	No
`phone_number_text`	String	Defines the phone number text. You can have a maximum of 25 characters. The phone number must be in this format "+<country-code>``<phone-number>".	call	Yes
`phone_number`	String	Defines the phone number.	+91XXXXXXXXXX	No

Success Response

This section provides you the successful JSON response format.

{
  "status": 200,
  "message": "Template created successfully.",
  "data": [],
  "error": {}
}

Failure Response

The template name should not match the existing template's name. Always use a unique template name.

{
    "error": {
        "code": "E996",
        "type": "VALIDATION_ERROR",
        "parameter": "name",
        "message": "Template name already taken!",
        "reference": ""
    }
}

The template name is a mandatory field and cannot be empty. Enter the valid template name.

{
    "error": {
        "code": "E413",
        "type": "VALIDATION_ERROR",
        "parameter": "name",
        "message": "Template name is mandatory",
        "reference": ""
    }
}

The template with the QUICK_REPLY button should have only one button.

{
    "error": {
        "code": "E981",
        "type": "VALIDATION_ERROR",
        "parameter": "button_data",
        "message": "Template having QUICK_REPLY button can have only one button.",
        "reference": ""
    }
}

The template can have maximum two buttons/objects.

{
    "error": {
        "code": "E979",
        "type": "VALIDATION_ERROR",
        "parameter": "button_data",
        "message": "Template button data can have a maximum of two buttons/objects",
        "reference": ""
    }
}

Sample Request

curl --location --request POST '{api-service-url}/v1/{sid}/whatsapp/template' \
--header 'api-key: {api-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name":"test_wa_template",
    "language":"en",
    "category":"marketing",
    "body":"Testing body {{$1}} {{$2}}",
    "header":{
        "type":"Text",
        "content":"This is test header content {{$1}} {{$2}}"
    },
    "footer":"This is test footer content",
    "button_data":[
        {
            "type":"phone_number",
            "phone_number_text":"phone",
            "phone_number":"+13236xxxxx7"
        }
    ]
}'

Other examples for button data

{
    "type":"quick_reply",
    "quick_reply1":"yes",
    "quick_reply2":"no"
}

{
    "type":"url",
    "website_url_type":"dynamic",
    "website_button_text":"avi",
    "website_url":"https://google.com"
}

Error Codes

The following table provides information about the error codes you would receive when executing the Add WhatsApp Template API:

Error Code	Description
E996	Existing template name.
E413	Mandatory template name.
E981	A template having the QUICK_REPLY button can have only one button.
E979	Template button data can have a maximum of two buttons/objects.

Updated about 1 month ago