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. To view the API Key and the SID, see View API Key and SID.

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

  1. 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 'media=@"/Users/John.Quill/Downloads/download (1).png"'

📘

NOTE:

Replace the placeholders above with relevant values as mentioned below.

ReplaceWithExamplesMandatory?
SIDAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USTrue
CONTENT_TYPEThe format in which the data is sent.application/x-www-form-urlencodedTrue
API_KEYYour API Key generated by Kaleyra.io:Ac4XXXXX21fTrue
FROM_NUMBERThe 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).+1202XXXXXXXTrue
TO_NUMBERA 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.
+1202XXXXXXXTrue
MESSAGE_TYPEMessage format of the message to be sent.

For details on the formats supported, read Messaging on WhatsApp Business.
mediatemplateTrue
CHANNEL_NAMEChannel on which message must be sent.whatsappTrue
TEMPLATE_NAMEName 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_confirmTrue
TEMPLATE_HEADERTitle/Subject of the headerTrue
TEMPLATE_BODY_PARAMETERSThe 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_FILEThe 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.mp4True
CALLBACK_URLThe 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_URLThe values that are set dynamically in a page's URL, and can be accessed by its template and its data sources.LoginFalse
MEDIA_URLThe 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.pngTrue
  1. 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 CodeParameterDescription
E13008from_invalidInvalid or in-correct input of the From number.
E13009to_invalidInvalid or in-correct input of the TO number.
E13004template_paramsThe Template params are not matching.
E13005template_name_missmatchInvalid template.

📘

NOTE

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