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_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.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 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.




© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.