Send a Media 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 APIs:
- 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 message
You can use the below API’s to send a media message via WhatsApp account
Request Format
The following is the request format to send Media Message through WhatsApp:
curl --location 'https://api.kaleyra.io/v1/<sid>/messages' \
--header 'api-key: <api_Key>' \
--form 'to="<to_number>"' \
--form 'type="<type>"' \
--form 'channel="<channel_name>"' \
--form 'from="<from_number>"' \
--form 'callback_url="<callback_url>"' \
--form 'media="<media_file>"' \
--form 'media_url="<media_url>"' \
--form 'caption="<media_caption>"'
Sample Request Format
The following is the sample request format to send Media Messages through WhatsApp:
curl --location 'https://api.kaleyra.io/v1/HXAP16XXXXXX97IN/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--form 'to="+91XXXXXXXXXX"' \
--form 'type="media"' \
--form 'channel="whatsapp"' \
--form 'from="+91XXXXXXXXXX"' \
--form 'callback_url="https://callbacktesting2.free.beeceptor.com"' \
--form 'media="@/C:/Users/company_A/Downloads/videoplayback.mp4"' \
--form 'media_url="https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/1614840334KLlogo.png"' \
--form 'caption="This is the capton"'
Parameter and Data Types
The following is the list of parameters and data types supported for sending a media message through WhatsApp:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
sid | String | Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key. | HXXXXXXX071US | Yes |
api-key | String | API key generated from kaleyra.io account. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
to_number | String | 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. | +91XXXXXXXXXX | Yes |
type | String | The type of message you want to send. For details on the formats supported, read Messaging on WhatsApp Business . | media | Yes |
channel | String | Defines the channel name. | Yes | |
from_number | String | 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). | +91XXXXXXXXXX | Yes |
callback_url | String | 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. | https://callbacktesting2.free.beeceptor.com | No |
media_file | Media | 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 | Yes |
media_url | String | 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 | Yes |
caption | String | A caption for the media file. | Heading https://kaleyra.io | Yes |
Sample Success Response
The following success message appears with the status 202 Accepted:
{
"id": "6e77bc24-fc4f-4c87-945f-12990d7342ef",
"type": "media",
"body": "Hey Welcome to kaleyra Media Messaging Platform .",
"createdDateTime": "2020-01-29 06:23:44+00:00",
"totalCount": 1,
"data": [
{
"message_id": "6e77bc24-fc4f-4c87-945f-12990d7342ef:0",
"recipient": "1202XXXXXXX"
}
],
"error": {}
}
Sample 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": "E419",
"message": " For the type media, media/media_url field is mandatory"
"data": [],
"error": {
"type": " For the type media, media/media_url field is mandatory"
}
}
Error Codes
The below table provides information about the error codes you would receive when executing the WhatsApp Media 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. |
E13012 | invalid_media | Invalid Media Content |
E13014 | Invalid_media | Failed to upload the Media file. |
Updated 1 day ago