SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Contact UsKaleyra.io Sign InSupport

Create a WhatsApp Template with Sample Media

POST Method

Suggest Edits

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:

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
- Authentication
- Utility		MarketingYes
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) (Optional)StringIt can be one of the following:

- QUICK_REPLY
- PHONE_NUMBER
- URL		URLNo
website_url_type(Optional)StringStatic/DynamicDynamicNo
website_button_text(Optional)StringThe content you want to display for the button. Call to action.Click hereNo
website_url(Optional)StringURL link that you want to integrate with the website_button_text button. https://kaleyra.ioNo
website_url_sample(Optional)StringSample value for any variable in dynamic URL.https://kaleyra.io/{{channels}}No
phone_number_text (Optional)StringThe content you want to display for the button. Call-to-action.Contact usNo
phone_number(Optional)StringThe phone number you want to integrate with phone_number_text.+1 xxxxxxx12No
sample_media_fileMediaUpload a media file from the following list:

- Image (.JPG, .PNG, or .JPEG)
- Video (.mp4)
- Documents (.pdf)		xxxxxaer.pngConditional (Yes/No) Note: If the header_type is Image/Video/PDF, then the sample_media_file is mandatory.
sample_media_url StringThe 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.pngConditional (Yes/No) Note: If the header_type is Image/Video/PDF, then the sample_media_url is mandatory instead of sample_media_file.
sample_bodyStringSample value for the variable pass in the body field. Hi {{John D}}, This is a test message.Yes
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="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

  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.

Updated 4 months ago