Upload Resumable Media
POST Method
The Kaleyra platform's Upload Resumable Media API enables you to asynchronously upload (and resume interrupted upload sessions without restarting) media files of up to 100 MB, generating a unique media ID. This uploaded media file will be available for 24 hours after creation and the uploaded media will be available for three days after it has been created. You can receive real time update about your uploaded Resumable Media through the Kaleyra callback service. For more information about the callback profile for WhatsApp resumable media status update, see Callback Profile for WhatsApp Resumable Media Status Update.
Validations
The following are the validations to send the request to upload resumable media:
- The request is rejected if the media file exceeds 100 MB in size.
- The rate limit for the API is 20 per WABA per hour.
- Upload resumable media supports only the following file types:
- application/pdf
- image/jpeg
- image/jpg
- image/png
- video/mp4
- The filename should not contain any of these characters:
\
(backslash)/
(forward slash)<
(less than)@
(at symbol)%
(percent symbol)
- The filename must contain at least one character (it cannot be empty) and should not exceed 255 characters in length, including the file extension.
Limitations
The following are the limitations to send the request to upload resumable media:
- The uploaded file will be valid for 24 hours after its creation. After that, the file handle will be considered invalid or expired.
- Data will be available for three days from the time of creation.
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 platform, 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.
- A WABA ID onboarded on Kaleyra WhatsApp API V2.
API Domain and Value
api_domain | Value |
---|---|
IN pod | api.in.kaleyra.io |
SG Pod | api.kaleyra.io |
EU Pod | api.eu.kaleyra.io |
NA pod | api.na.kaleyra.ai |
API request to upload Resumable Media
To upload resumable media, use the https://<api_domain>/v2/<sid>/whatsapp/<waba_id>/resumable_media
endpoint.
The following is the request format to upload resumable media:
curl -L -X POST 'https://<api_domain>/v2/<sid>/whatsapp/<waba_id>/resumable_media' \
-H 'api-key: <api-key>' \
-H 'content-type: <content-type>' \
-F 'file=@"<file>"' \
-F 'type="<type>"'
The following is the sample request format to upload resumable media:
curl -L -X POST 'https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/15044XXXX142241/resumable_media' \
-H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
-H 'content-type: application/json' \
-F 'file=@"/C:/Users/Demo/Downloads/image.png"' \
-F 'type="image/png"'
URL Parameters and Header Parameters
Following is the list of header parameters:
Parameter / Headers | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
| String | Account SID (Security Identifier). | HXAP16XXXXXX97IN | Yes |
| String | WhatsApp business account id. | 15044XXXX142241 | Yes |
| String | Indicates the format of the content the API will be processing. | The only allowed value is application/json. | Yes |
| String | API key generated from Kaleyra platform account. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
| Object | Path to the file stored in your local directory. |
| Yes |
| Type of media file being uploaded. - Upload resumable media supports only the following file types:
| image/png | Yes |
Sample Success Response
The following success message appears with 202 Accepted:
202 Success
{
"code": "WA202",
"message": "Request Processed Successfully",
"data": {
"id": "<id>",
"status": "PENDING"
},
"error": {}
}
The following table contains the parameters in the sample response:
Parameter | Description |
---|---|
code | Response code for the API request. |
message | The response message for the API request. |
id | A unique identifier assigned to the file within the system. This field allows the system to reference the file independently of other attributes like the file name. |
status | The current status of the file upload. This could be any of a predefined set of statuses indicating the state of the file (such as., "UPLOADED" , "PENDING" , or "FAILED" ). |
Sample Failure Responses
The following are the sample failure responses:
401 Unauthorized
{
"code": "RBC001",
"message": "Incorrect SID or API key.",
"data": [],
"error": {
"error": "Incorrect SID or API key."
}
}
401 Wrong account
{
"code": "WA-401",
"message": "API is not available for given customer.Please contact support for more info",
"data": {},
"error": "API is not available for given customer.Please contact support for more info"
}
401 Unauthorized WABA
{
"code": "WA401",
"message": "Waba_Id is not present or does not belong to the account.",
"data": {},
"error": {
"waba_id": "Waba_Id is not present or does not belong to the account."
}
}
401 Unauthorized WABA version
{
"code": "WA401",
"message": "The waba_id you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
"data": {},
"error": {
"waba_id": "The waba_id you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
}
}
400 Incorrect payload
{
"code": "WA-400",
"message": "Refer to correct payload format",
"data": {},
"error": {
"payload": "Incorrect payload format"
}
}
400 Invalid file name
{
"code": "WA400",
"message": "file_name can not contain these special characters '/' (forward slash), '\\' (backward slash),'<' (less than),'@' (at the rate),'%' (percentage),' ' (space). additionaly file_name length must be between 1 to 255 characters",
"data": [],
"error": {
"file_name": "file_name can not contain these special characters '/' (forward slash), '\\' (backward slash),'<' (less than),'@' (at the rate),'%' (percentage),' ' (space). additionaly file_name length must be between 1 to 255 characters"
}
}
429 Too many requests
{
"code": "WA429",
"message": "Too many requests",
"data": {},
"error": {
"error": "Too many requests sent from this waba in a short period of time, please try after sometime"
}
}
500 Internal Server Error
{
"code": "WA-500",
"message": "Please try again later",
"data": {},
"error": {
"error": "Internal server error"
}
}
{
"code": "WA413",
"message": "Request size is too large",
"data": {},
"error": {
"error": "The file size exceeds the 100 MB limit. Please upload a file smaller than 100 MB."
}
}
Updated about 5 hours ago