Send a Media Template Message through WhatsApp
POST Method
- Sign up for free
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
- 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.
- 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.
| 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. | 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 |
developers.kaleyra.io- 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
Updated 6 months ago