Create a WhatsApp Template with Sample Media

POST Method

Kaleyra.io allows you to create WhatsApp templates with sample media using the API. After you create a WhatsApp template with sample media, it has to get approved by Meta before you can use the WhatsApp template with sample media to send messages.

Template Category

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

Base URL

https://api.kaleyra.io/v1/

To create the WhatsApp templates with sample media, perform the following:

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

Refer to the Create an API Key page for steps to create your 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.

API Request to Create WhatsApp Templates

To create the WhatsApp templates, use the whatsapp/templates endpoint with the following request method:

Request format

curl --location --request POST '{{url}}o/v1/{{sid}}/whatsapp/template' \
--header 'api-key: {{api-key}}' \
--form 'name="{{name}}"' \
--form 'body="{{body}}"' \
--form 'category="{{category}}"' \
--form 'header="{\"{{header}}\"}";type=application/json' \
--form 'language="{{language}}"' \
--form 'button_data="[
   {
      \"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\":\"phone_number\",
      \"phone_number_text\":\"{{phone_number_text}}\",
      \"phone_number\":\"{{phone_number}}\"
   }
]";type=application/json' \
--form 'sample_media_file=@"{{sample_media_file}}\"' \
--form 'sample_media_url="{{sample_media_url}}\"' \
--form 'sample_body="{{sample_body}}"' \
--form 'footer="{{footer}}"' \
--form 'waba_id="{{waba_id}}"'

The following table displays the parameter used to create a WhatsApp template with a sample media API:

Parameter	Data Type	Description	Example	Mandatory
`sid`	String	Account SID (Security Identifier).	HXXXXXXX071US	Yes
`api-key`	String	API key generated from Kaleyra.io account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3	Yes
`name`	String	Template name.	Kaleyra_01	Yes
`body`	String	Body of the message.	Hi, this is a WhatsApp test message.	Yes
`category`	String	Select one of the following: - Marketing - Authentication - Utility	Marketing	Yes
`header`	JSON/String	Select one of the following: - Image - Video - Document - Text.	{"type":"video"}	Yes
`language`	String	The language in which, you want to create the template.	en_us	Yes
`type`	String	It can be one of the following: - text - template - mediatemplate - location - contacts - list - reply - singleproduct - multiproduct	mediatemplate	Yes
`type` (button_data) (Optional)	String	It can be one of the following: - QUICK_REPLY - PHONE_NUMBER - URL	URL	No
`website_url_type`(Optional)	String	Static/Dynamic	Dynamic	No
`website_button_text`(Optional)	String	The content you want to display for the button. Call to action.	Click here	No
`website_url`(Optional)	String	URL link that you want to integrate with the `website_button_text` button.	https://kaleyra.io	No
`website_url_sample`(Optional)	String	Sample value for any variable in dynamic URL.	https://kaleyra.io/{{channels}}	No
`phone_number_text (Optional)	String	The content you want to display for the button. Call-to-action.	Contact us	No
`phone_number`(Optional)	String	The phone number you want to integrate with `phone_number_text`.	+1 xxxxxxx12	No
`sample_media_file`	Media	Upload a media file from the following list: - Image (.JPG, .PNG, or .JPEG) - Video (.mp4) - Documents (.pdf)	xxxxxaer.png	Conditional (Yes/No) Note: If the header_type is Image/Video/PDF, then the sample_media_file is mandatory.
`sample_media_url`	String	The sample media URL should be public and have a file extension and valid SSL certificate. Note: URL path is supported for image/video/media instead of uploading it. If both media_file and media_url are passed in the API request, then only "media_file" will be considered.	https://www.kaleyra.com/wp-content/uploads/kaleyra.png	Conditional (Yes/No) Note: If the header_type is Image/Video/PDF, then the sample_media_url is mandatory instead of sample_media_file.
`sample_body`	String	Sample value for the variable pass in the body field.	Hi {{John D}}, This is a test message.	Yes
`waba_id`	String	WhatsApp Business Account ID	xxxxxxxxxxxxxx74443	Yes

Sample Request Format

The following is the sample request format to create WhatsApp templates with sample media:

curl --location --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/whatsapp/template' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--form 'name="Kaleyra_01"' \
--form 'body="Hi, this is a WhatsApp test message."' \
--form 'category="marketing"' \
--form 'header="{\"type\":\"video\"}";type=application/json' \
--form 'language="en"' \
--form 'button_data="[
   {
      \"type\":\"url\",
      \"website_url_type\":\"dynamic\",
      \"website_button_text\":\"button\",
      \"website_url\":\"https://www.kaleyra.io\",
      \"website_url_sample\":\"https://www.kaleyra.io/{{channels}}\"
   },
   {
      \"type\":\"phone_number\",
      \"phone_number_text\":\"phone_test\",
      \"phone_number\":\"+1xxxxxx7890\"
   }
]";type=application/json' \
--form 'sample_media_file=@"/path/to/file"' \
--form 'sample_media_url="https://www.kaleyra.com/wp-content/uploads/kaleyra.png"'\
--form 'sample_body="Hi {{John D}}, This is a test message."' \
--form 'footer="Thankyou"' \
--form 'waba_id="xxxxxxxxxxxxxx74443"'

Sample Success Response

The following success message appears with status 200:

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

Sample Error Format

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