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.

Base URL

<https://api.kaleyra.io/v1/><SID>

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

Before you get started, sign up for a Kaleyra.io account for free and 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.

API command to Add WhatsApp Template.

Request Format - POST

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

curl --location --request POST '{api-service-url}/v1/{SID}/whatsapp/template' \
--header 'api-key: <API_KEY>' \
--header 'Content-Type: <CONTENT_TYPE>' \
--data-raw '{
    "name":"<NAME>",
    "language":"<LANGUAGE>",
    "category":"<CATEGORY>",
    "body":"Hello testing body {{$1}} {{$2}}",
    "header":{
      "type":"<HEADER_TYPE>",
      "content":"<HEADER_CONTENT>"
    },
    "footer":"<FOOTER>",
    "button_data":[
      {
        "type":"phone_number",
        "phone_number_text":"phone",
        "phone_number":"+13236xxxxx7"
      }
    ]  
}'

📘

Note:

Replace the placeholders above with relevant values as mentioned below.

Parameters and Variables

The following table displays the parameter and variables used:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USTrue
API_KEYStringYour API Key generated by Kaleyra.Ac4XXXXX21fTrue
CONTENT_TYPEAlphanumericIndicates the format of the content the API will be processing.application/JSONTrue
NAMEStringIndicates the name of the WhatsApp template.test_wa_templateTrue
LANGUAGEStringIndicates the language code value for the WhatsApp template language.enTrue
CATEGORYStringIndicates the business category of the WhatsApp template. For more information, see WhatsApp Template Category page.Marketing, Authentication, and Utility.True
HEADER_TYPEStringIndicates the header type for WhatsApp template.textFalse
HEADER_CONTENTStringIndicates the header content in case of text header-type.{header-content}False
FOOTERStringIndicates the text footer content for the WhatsApp template.{footer-content}False
BUTTON_DATAJSONContains an array of values, where each JSON value have button related data."button_data":ers]
{
"data": {
"h-0": "Parameter",
"h-1": "Variable",
"h-2": "Description",
"
False
PHONE-NUMBER-BUTTONJSONAllows users to respond calling on click of button. You can update it in the Button_Data array.{
"type":"phone_number",
"phone_number_text":"phone",
"phone_number":"+13236xxxxx7"
}
False
URL-BUTTONJSONAllows the users to get redirected to the website/URL on click of button. You can update it in the Button_Data array.{
"type":"url",
"website_url_type":"dynamic",
"website_button_text":"avi",
"website_url":"https://google.com"
}
False
QUICK-REPLY-BUTTONJSONAllows the user to respond by simple text when button is clicked. You can update it in the Button_Data array.

You can add maximum three quick reply buttons.
{
"type":"quick_reply",
"quick_reply1":"yes",
"quick_reply2":"no",
"quick_reply3":"maybe"
}
False

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 CodeDescription
E996Existing template name.
E413Mandatory template name.
E981A template having the QUICK_REPLY button can have only one button.
E979Template button data can have a maximum of two buttons/objects.