Send Video Messages
Using the 'Video Message API' message, you can send video messages to customers as part of continuous business engagements. When a video message is sent, a thumbnail preview of the video is displayed on the customer's phone. When the customer taps the thumbnail preview, the video is displayed.
The messaging_object of the payload contains the video ID or the public link to the video that should be displayed.
The extra_info part of the payload contains any additional information related to the API requests.
Prerequisites
- Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on kaleyra platform. - To set up a WhatsApp account on kaleyra.io, see Manual Signup
and Embedded Signup. - An active WhatsApp for Business API plan that includes:
- A WhatsApp business number.
- An associated profile with the business number.
- A WhatsApp verified and approved profile.
Base URL
https://<api_domain>/v2/<SID>
API Domain and Value
api_domain | Value |
---|---|
IN pod | api.in.kaleyra.io |
SG Pod | api.ap.kaleyra.io |
EU Pod | api.eu.kaleyra.io |
API Request to Send a Video Message
To send a video message, use the https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages
endpoint with the following request method:
Request Format
The following is the request format to send a video message:
curl -X POST \
https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages \
-H 'Content-Type: application/json' \
-H 'api-key: <api-key>' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object": {
"messaging_product": "messaging_product",
"recipient_type": "recipient_type",
"to": "<wa-user-phone-number>",
"type": "<type>",
"video": {
"id": "<media_id>",
"link": "<media_url>",
"caption": "<video_caption_text>"
}
},
"extra_info": {
"ref": "<ref>",
"ref1": "<ref1>",
"ref2": "<ref2>",
"wa_source": "<wa_source>"
}
}'
Sample Request Format
The following is the sample request format to send a Video message:
curl -X POST \
https://api.in.kaleyra.io/v2/HAXP2142XX/whatsapp/+91863XXX5920/messages \
-H 'Content-Type: application/json' \
-H 'api-key: xxxxCFSAFS53215634XXXXX4ac' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object": {
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "+91xxxxxxxxx",
"type": "video",
"video": {
"id" : "1166846181421424",
"caption": "Splendid festive celebrations"
},
"extra_info": {
"ref": "customer1",
"ref1": "marketing",
"ref2": "dictionary",
"wa_source": "api"
}
}'
URL Parameters and Headers
Following is the list of parameters and headers to send the outgoing message request:
Parameter / Headers | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
sid | String | Account SID (Security Identifier). | HXAP16XXXXXX97IN | Yes |
phone_number | String | Phone number of the end customer you want to send a message to. | +91XXXXXXXXXX | Yes (valid phone numbers only) |
Content-Type | String | Indicates the format of the content the API will be processing. | The only allowed value is application/json. | Yes |
api-key | String | API key generated from kaleyra platform account. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
Following is the list of attributes to be used in the payload to send the outgoing message:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
messaging_object | JSON object | Payload is supported only in JSON format. The messaging_object is the payload which contains the message object as defined by Meta which is used to send the WhatsApp message. | See the specific table for details. | Yes |
extra_info | JSON object | This object will contain additional details that a user can send for certain functionalities. | See the specific table for details. | No |
The following table describes the different attributes used for the messaging_object
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
messaging_product | String | Messaging service used for the request. | Only allowed value is whatsapp | Yes |
recipient_type | String | Currently, you can only send messages to individuals. Default is individual. | Only allowed value is individual | No |
to | String | WhatsApp end-user phone number. It should include country code prefix following E.164 format. | +16XXXXXX234 | Yes |
type | String | The type of message you want to send. | Video | No |
video | JSON Object | The video object that you want to send in the WhatsApp message. | See the specific table for details. | Yes |
The following table describes the different attributes used for the video JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
id | String | The ID number of the uploaded media asset. This is the recommended option sending a video message. Note: Either the id or the link for the video is required. See, obtain the media id for more details on media ID. | 1166846181421424 | Yes |
link | String | The link to the media asset. This is not recommended option for sending a video message. Note: Either the id or the link for the video is required. | https://www.awesomeview.com/assets/awesome-view.mp4 | Yes |
caption | String | WhatsApp end-user phone number. It should include country code prefix following E.164 format. | Video caption text. The maximum value allowed is 1024 characters. | No |
The following table describes the different attributes used for the extra_info
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
ref | String | Include any contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | customer1 | No |
ref1 | String | Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | marketing | No |
ref2 | String | Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | dictionary | No |
wa_source | String | Indicates the source from where the API has been triggered. Supported values for wa_source are "api", "clevertap", "zoho", "webengage", "shopify", "leadsquared", "responsys", "braze", "hubspot", "salesforce", "zapier", "eloqua", and "moengage". Note: If the customer passes any other value other than above-specified values, then the system will override that as the "API". | api | No |
Sample Success Response
The following success message appears with the status 202 Accepted:
202 Accepted
{
"code":"WA202"
"message":"Request Accepted",
"data":{
"message_id":"AXXXXXXXXXXXXXXXXXXX"
}
"error":{}
}
Failure Responses
Following are the error responses for the API level and the business level validations.
Sample Failure Response
The following are the failure responses:
401 Unauthorized
{
"code": "RBC001",
"message": "Incorrect SID or API key.",
"data": [],
"error": {
"error": "Incorrect SID or API key."
}
}
401 Unauthorized phone number
{
"code": "WA401",
"message": "Phone number is not present or does not belong to the account.",
"data": {},
"error": {
"phone_number": "Phone number is not present or does not belong to the account."
}
}
400 Incorrect payload
{
"code": "WA400",
"message": "Refer to correct payload format",
"data": {},
"error": {
"payload": "Incorrect payload format"
}
}
500 Internal Server Error
{
"code": "WA500",
"message": "Please try again later",
"data": {},
"error": {
"error": "Internal server error"
}
}
400 Low balance
{
"code": "E110",
"message": "Please check your balance, You have a low balance!",
"data": {},
"error": {
"balance": "Please check your balance, You have a low balance!"
}
}
401 Unauthorised Account type
{
"code": "WA-401",
"message": "API is not available for given customer.Please contact support for more info",
"data": {},
"error": {
"account": "API is not available for given customer.Please contact support for more info"
}
}
401 Unauthorized phone number version
{
"code": "WA-401",
"message": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
"data": {},
"error": {
"phone_number": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
}
}
Updated about 12 hours ago