Create WhatsApp Templates 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, then you can use the WhatsApp template with sample media to send WhatsApp messages.

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 '[email protected]"{{sample_media_file}}\"' \
--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:

ParameterData TypeDescriptionExampleMandatory
sidStringAccount SID (Security Identifier).HXXXXXXX071USYes
api-keyStringAPI key generated from Kaleyra.io account.Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3Yes
nameStringTemplate name.Kaleyra_01Yes
bodyStringBody of the message.Hi, this is a WhatsApp test message.Yes
categoryStringSelect one of the following:

- Marketing
- OTP
- Transaction
OTPYes
headerJSON/StringSelect one of the following:

- Image
- Video
- Document
- Text.
{"type":"video"}Yes
languageStringThe language in which, you want to create the template.en_usYes
typeStringIt can be one of the following:

- text
- template
- mediatemplate
- location
- contacts
- list
- reply
- singleproduct
- multiproduct
mediatemplateYes
type (button_data)StringIt can be one of the following:

- QUICK_REPLY
- PHONE_NUMBER
- URL
URLConditional (Yes/No)
website_url_typeStringStatic/DynamicDynamicConditional (Yes/No)
website_button_textStringThe content you want to display for the button. Call to action.Click hereConditional (Yes/No)
website_urlStringURL link that you want to integrate with the website_button_text button. https://kaleyra.ioConditional (Yes/No)
website_url_sampleStringSample value for any variable in dynamic URL.https://kaleyra.io/{{channels}}Conditional (Yes/No)
phone_number_textStringThe content you want to display for the button. Call-to-action.Contact usConditional (Yes/No)
phone_numberStringThe phone number you want to integrate with phone_number_text.+1 xxxxxxx12Conditional (Yes/No)
sample_media_fileMediaUpload a media file from the following list:

- Image (.JPG, .PNG, or .JPEG)
- Video (.mp4)
- Documents (.pdf)
xxxxxaer.pngConditional (Yes/No)
sample_bodyStringSample value for the variable pass in the body field. Hi {{John D}}, This is a test message.Conditional (Yes/No)
waba_idStringWhatsApp Business Account IDxxxxxxxxxxxxxx74443Yes

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="OTP"' \
--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 '[email protected]"/path/to/file"' \
--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

  1. 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": ""
    }
}
  1. 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": ""
    }
}
  1. 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.