Create WhatsApp template with enabled Tracked URL

POST Method

The approved WhatsApp template allows you to send WhatsApp messages with shortened URLs that will be displayed as a Call-to-Action (CTA) on the device for the end-user. While adding a WhatsApp template from the kaleyra.io Add New Template page of the User Interface, you can add a shortened URL by selecting Button Type as URL and URL Type as Dynamic and enable the Enable URL Tracking option for the CTA. After successfully enabling URL tracking, you can track each distinct click when an end customer clicks on the shortened URL button using the approved WhatsApp template. The end customer will receive the WhatsApp message with a short URL displayed as a CTA. Also, you can view each CTA click count through the URL Shortener report.

📘
Note:

In case while requesting to send a WhatsApp message, the URL Shortener service is not available, the message request gets dropped from the system and will not be sent to the end customer.

To edit an existing template's Shortener URL, you need to contact the Kaleyra Support team.

📘
Prerequisites:
The following are the prerequisites for using URL Shortener in WhatsApp API’s templates:

A WhatsApp business number.

An associated profile with the business number.

A WhatsApp verified and approved profile.

A working API key and SID key.

Approved template including a dynamic URL button type.

Before sending the request for a WhatsApp Template with a tracking shortened URL for approval to Meta, you must perform the following steps:

Sign up for free with Kaleyra.io. 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.
Create the WhatsApp Template and Enable URL Tracking. For more information, see Enable URL Tracking.
Create a shortened URL. Create a shortened URL for dynamic URL. For more information, see Create a URL Shortener using Kaleyra.io or Create a URL Shortener using API.

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 request to Create a WhatsApp Template to track URL clicks using CTA

To create a WhatsApp template to track URL send an API request to track URL clicks using WhatsApp template, use the /whatsapp/template endpoint.

Request Format

The following is the request format to create a WhatsApp template to track URL using WhatsApp template CTA:

curl --location --request POST 'https://<api_domain>/v1/<sid>/whatsapp/template'
--header 'api-key: <api-key>'
--form 'name="<name>"' 
--form 'category="<category>"' 
--form 'language="<language>"' 
--form 'header="{\"type\": \"none\"}";type=application/json' 
--form 'body="<body>"' 
--form 'button_data="[
          {  \"type\" : \"<type>\",
            \"phone_number_text\" : \"<phone-number-text>\",
            \"phone_number\" : \"<phone-number>\"
          },
          {
            \"type\":\"url\",
                  \"website_url_type\":\"<website-url-type>\",
                  \"website_button_text\":\"<website-button-text>\",
                  \"website_url\":\"<website-url>\",
                  \"website_url_sample\":\"<website-url-sample>\"
					}
				] ";type=application/json'
 --form 'sample_body="<sample-body>"' 
 --form 'footer="<footer>"' 
 --form 'waba_id="<waba-id>"' 
 --form 'enable_url_tracking="<enable-url-tracking>"'

Sample Request

The following is the sample request for the wrapper message:

curl --location --request POST 'https://api.in.kaleyra.dev/v1/HXXXXXXX071IN/whatsapp/template'
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3'
--form 'name="urltrackingtemlate11"' 
--form 'category="Marketing"' 
--form 'language="en_us"' 
--form 'header="{\"type\": \"none\"}";type=application/json' 
--form 'body="Hi, this is a WhatsApp test message."' 
--form 'button_data="[
          {  \"type\" : \"phone_number\",
            \"phone_number_text\" : \"Contact us\",
            \"phone_number\" : \"+919XXXXXXXX8\"
          },
          {
            \"type\":\"url\",
                  \"website_url_type\":\"dynamic\",
                  \"website_button_text\":\"CLICK TO CALL\",
                  \"website_url\":\"https://klr.bz\",
                  \"website_url_sample\":\"https://klr.bz/{{slug/kadvanced}}\"
					}
				] ";type=application/json'
 --form 'sample_body="Hi, this is a WhatsApp test message."' 
 --form 'footer="This is footer"' 
 --form 'waba_id="12xxxxxxxxxxxx74443"' 
 --form 'enable_url_tracking="true"'

Parameters and Data Types

Following is the list of parameters and data types supported:

Parameter	Data Type	Description	Example	Mandatory
`sid`	String	Account SID (Security Identifier).	HXXXXXXX071IN	Yes
`api-key`	String	API key generated from Kaleyra.io account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3	Yes
`name`	String	Template name. The template name can have 512 characters in length, lower case alphanumeric with only the special character underscore (_) is supported.	urltrackingtemlate11	Yes
`category`	String	Select one of the following: Marketing Authentication Utility	Marketing	Yes
`language`	String	The language in which, you want to create the template.	en_us	Yes
`header_content`	String	Header text.	Text	Yes
`content-type`	String	The format in which the data is sent.	application/x-www-form-urlencoded	Yes
`body`	String	Body of the message.	Hi, this is a WhatsApp test message.	Yes
`type` (button_data)	String	It can be one of the following: QUICK_REPLY PHONE_NUMBER URLFor adding a CTA based on URL, select URL	URL	No
`phone-number-text`(button_data)	String	The name on the Phone Number Button.	Contact us	No
`phone-number`(button_data)	String	The phone number you want to integrate with `phone_number_text`.	+1 xxxxxxx12	No
`website-url-type` (when `type` is url)	String	It can be one of the following: Static Dynamic	dynamic	No
`website-button-text`(when `type` is url)	String	The content you want to display for the button. Call to action displayed on the end customer device to open the URL. Note*: You can use one or two buttons based on your requirements. In the case of two buttons, the end-user will receive two buttons one for a call other to access the URL.	Click for more information.	No
`website-url`(when `type` is url)	String	URL link that you want to integrate with the `website_button_text` button. Note*: If you want to track the URL based on the pods (IN and SG) then you must use the respective domain `klr.bz` for EU pod se `klyr.bz`.	`https://klr.bz`	No
`website-url-sample`(when `type` is url)	String	Sample value for any variable in dynamic URL.	`https://klr.bz/{{slug/kadvanced}}`	No
`sample-body`(when `type` is url)	String	The message within the body of the sample template is not related to the URL type.	Hi, this is a WhatsApp test message.	No
`footer`	String	Footer text.	This is footer	No
`header_content_type`	String	Select one of the following: Text Image Video Document None	Text	Yes
`waba_id`	String	WhatsApp Business Account ID.	xxxxxxxxxxxxxx74443	Yes
`enable-url-tracking`	Boolean	This field holds a boolean value true or false, When set to true the templates are identified as they use URL shortener service on dynamic URL button types. You will be able to track total number of views, last viewed, and unique clicks.	True	No

Sample Success Response

The following success message appears with the status 200 Accepted:

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

Sample Failure Response

In the case of enable_url_tracking is set to True and when no Dynamic URL button type while creating the template, the following validation error response is generated:

{
    "error": {
        "code": "WAE0025",
        "type": "VALIDATION_ERROR",
        "parameter": "enable_url_tracking",
        "message": "Enabled URL tracking is applicable for Dynamic URL type of buttons",
        "reference": ""
    }
}

Sample validation error when API is unable to create the WhatsApp templates with sample media:

{
    "error": {
        "code": "E996",
        "type": "VALIDATION_ERROR",
        "parameter": "message",
        "message": "Unable to create the Template.",
        "reference": ""
    }
}

Sample validation error when body and sample_body don't have the same content in the WhatsApp templates with sample media:

{
    "error": {
        "code": "E996",
        "type": "VALIDATION_ERROR",
        "parameter": "message",
        "message": "The body and sample_body don't have the same content. Please verify and try again.",
        "reference": ""
    }
}

Sample validation error when template name already exists in the WhatsApp templates with sample media:

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

Error Codes

For information related to the WhatsApp error code, see WhatsApp Error Codes.

Updated about 1 month ago