Add 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
  • 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/

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.

📘

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:

Parameter

Variable

Description

Example

Mandatory

SID

String

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXXXXXXX071US

True

API_KEY

String

Your API Key generated by Kaleyra.

Ac4XXXXX21f

True

CONTENT_TYPE

Alphanumeric

Indicates the format of the content the API will be processing.

application/JSON

True

NAME

String

Indicates the name of the WhatsApp template.

test_wa_template

True

LANGUAGE

String

Indicates the language code value for the WhatsApp template language.

en

True

CATEGORY

String

Indicates the category of the WhatsApp template.

Account Update

True

HEADER_TYPE

String

Indicates the header type for WhatsApp template.

text

False

HEADER_CONTENT

String

Indicates the header content in case of text header-type.

{header-content}

False

FOOTER

String

Indicates the text footer content for the WhatsApp template.

{footer-content}

False

BUTTON_DATA

JSON

Contains an array of values, where each JSON value have button related data.

"button_data":[
{
"type":"phone_number",
"phone_number_text":"phone",
"phone_number":"+13236xxxxx7"
}
]

False

PHONE-NUMBER-BUTTON

JSON

Allows 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-BUTTON

JSON

Allows 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-BUTTON

JSON

Allows 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":"account update",
    "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.


Did this page help you?