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)
    • (space)
  • 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

  1. 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.
  2. To set up a WhatsApp account on Kaleyra platform, see Manual Signup
    and Embedded Signup.
  3. 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.

Base URL

https://<api_domain>/v2/<SID>

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.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.

Request Format

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>"'

Sample Request Format

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?

sid

String

Account SID (Security Identifier).

HXAP16XXXXXX97IN

Yes

waba-id

String

WhatsApp business account id.

15044XXXX142241

Yes

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

file

Object

Path to the file stored in your local directory.

/C:/Users/Demo/Downloads/image.png

Yes

type

Type of media file being uploaded. - Upload resumable media supports only the following file types:

  • "application/pdf"
  • "image/jpeg"
  • "image/jpg"
  • "image/png"
  • "video/mp4"

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:

ParameterDescription
codeResponse code for the API request.
messageThe response message for the API request.
idA 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.
statusThe 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."
    }
}




© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.