Send a Media Template Message through WhatsApp

POST Method

1. Sign up for free

Before you get started, sign up for a Kaleyra.io account for free and create an API key.

2. Pre-requisites

Below listed are the pre-requisites for using Kalyera WhatsApp API’s

  • 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.

3. Send a media template message

You can use the below API’s to send a media template message via WhatsApp account

Request Format

cURL -X POST "https://api.kaleyra.io/v1/<SID>/messages" \
     -H "Content-Type: <CONTENT_TYPE>" \
     -H "api-key:<API_KEY>" \
     -d "from=<FROM_NUMBER>" \
     -d "to=<TO_NUMBER>" \
     -d "type=<MESSAGE_TYPE>" \
     -d "channel=<CHANNEL_NAME>" \
     -d "template_name=<TEMPLATE_NAME>" \
     -d "param_header=<TEMPLATE_HEADER>" \
     -d "params=<TEMPLATE_BODY_PARAMETERS>" \
     -d "media=<MEDIA_FILE>" \
     -d "callback_url=<CALLBACK_URL>"
     -d "param_url=<PARAMETER_URL>"
     -d "media_url=<MEDIA_URL>"

Sample Request Format - media_url

curl --location --request POST 'https://api.kaleyra.io/v1/HXAP1XXXX822XXIN/messages' \
--header 'Content-Type: application/json    ' \
--header 'api-key:AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--form 'to="+XXXXXXXXXXXX"' \
--form 'type="mediatemplate"' \
--form 'params="\"A\",\"B\""' \
--form 'template_name="temp_test_1"' \
--form 'channel="whatsapp"' \
--form 'from="+XXXXXXXXXXXX"' \
--form 'media_url="https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/16148XXXXXXXX14838280906_1dfXXXXXX-XXXXX-45a2-a0fe-3f8619aca7eb_(1).jpg"'

Sample Request Format - media

curl --location --request POST 'https://api.kaleyra.io/v1/HXAP1XXXXX22XXIN/messages' \
--header 'Content-Type: application/json    ' \
--header 'api-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--form 'to="+XXXXXXXXXXXX"' \
--form 'type="mediatemplate"' \
--form 'params="\"A\",\"B\""' \
--form 'template_name="temp_test_1"' \
--form 'channel="whatsapp"' \
--form 'from="+XXXXXXXXXXXX"' \
--form '[email protected]"/Users/John.Quill/Downloads/download (1).png"'

📘

NOTE

Replace the placeholders above with relevant values as mentioned below.

Replace

With

Examples

Mandatory?

SID

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXXXXXXX071US

True

CONTENT_TYPE

The format in which the data is sent.

application/x-www-form-urlencoded

True

API_KEY

Your API Key generated by Kaleyra.io:

Ac4XXXXX21f

True

FROM_NUMBER

The number registered with WhatsApp business from which the message is to be sent. Ensure that the country code is prefixed to the number. (E164 format).

+1202XXXXXXX

True

TO_NUMBER

A valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).

Note: You can add multiple recipients, separate each number using the comma (,) delimiter.

+1202XXXXXXX

True

MESSAGE_TYPE

Message format of the message to be sent.

For details on the formats supported, read Messaging on WhatsApp Business.

mediatemplate

True

CHANNEL_NAME

Channel on which message must be sent.

whatsapp

True

TEMPLATE_NAME

Name of the WhatsApp media template that was created in the Kaleyra.io portal. This name must be approved by WhatsApp before you start using this API.

booking_confirm

True

TEMPLATE_HEADER

Title/Subject of the header

True

TEMPLATE_BODY_PARAMETERS

The values that you will pass when you want to send a message using the template. Since the values are dynamic, it must be passed through the key. Multiple parameters are allowed that must be separated with a comma.

For a template that says: Hi your booking id is for date the params to be passed would be <id_number>, .

"param1","param"

True

MEDIA_FILE

The location of the media file that will be embedded in the message.

Ensure you upload only the formats supported. Refer to
Messaging on WhatsApp Business for more details.

@/C:/Users/company_A/Downloads/videoplayback.mp4

True

CALLBACK_URL

The URL that Kaleyra.io should send information to when your number receives a response. This URL can be accessed publicly.
Click here for an example.

False

PARAM_URL

The values that are set dynamically in a page's URL, and can be accessed by its template and its data sources.

Login

False

MEDIA_URL

The media URL should be public and have a file extension.
Note: URL path is supported for image/video/media instead of uploading it.
If both media and media_url are passed in API request, then only "media_url" will be considered.

https://www.kaleyra.com/wp-content/uploads/kaleyra.png

True

3. Response Format

Response-
{
    "id": "6e77bc24-fc4f-4c87-945f-12990d7342ef",
    "type": "mediatemplate",
    "createdDateTime": "2020-01-29 06:23:44+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "6e77bc24-fc4f-4c87-945f-12990d7342ef:0",
            "recipient": "1202XXXXXXX"
        }
    ],
    "error": {}
}

Failure Response

{
"code": "E438",
"message": " For the type text you cannot send media URL.",
"data": [],
"error": {
"type": " For the type text you cannot send media URL."
}
}

{
"code": "E420",
"message": " For the type template, media or body fields are not allowed.",
"data": [],
"error": {
"type": "For the type template, media or body fields are not allowed."
}
}

Error Codes

The below table provides information about the error codes you would receive when executing the WhatsApp Media Template Message API.

Error Code

Parameter

Description

E13008

from_invalid

Invalid or in-correct input of the From number.

E13009

to_invalid

Invalid or in-correct input of the TO number.

E13004

template_params

The Template params are not matching.

E13005

template_name_missmatch

Invalid template.

📘

NOTE

In case of error, ensure that the above replaceable values are correct. See Standard Error Codes


Did this page help you?