Upload Media Files

POST Method

The Media Upload API allows you to upload the media files and generate the media ID that can be utilized while sending WhatsApp media messages from your system drives.

📘

Notes:

  • The media ID is generated after the successfully uploading the media file and it can be utilized multiple times when you want to send the same media file using WhatsApp Media messages to more than one recipients using that media ID.
  • For more information of supported formats and media file size see, Supported Media Types.
  • The WhatsApp account type gets validated (postpaid account or prepaid account) while uploading the media files using this API. A validation check is done to check if the account is postpaid or prepaid. When postpaid, then only request is processed or else a 401 Unauthorised account type error appears.

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 Media Upload

To upload media, use the https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/media endpoint with the following request method:

Request Format

The following is the request format to upload media:

curl --location 'https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/media' \
--header 'api-key: <api-key>' \
--form 'file=@"<file>"' \
--form 'type="<type>"'

Sample Request Format

The following is the sample request format to upload media:

curl --location 'https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/+91XXXXXXXXXX/media' \
--header 'api-key: <api-key>' \
--form 'file=@"2xxxxxxjn/cxxs-trxxxxrs-sxxxxr-sxxe.jpg"' \
--form 'type="image/jpeg"'

Parameter and Data Types

Following is the list of parameters and data types supported for uploading media:

Parameter

Data Type

Description

Example

Mandatory?

sid

String

Account SID (Security Identifier).

HXAP16XXXXXX97IN

Yes

phone_number

String

Phone number of 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.

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.

"@/2xxxxxxjn/cxxs-trxxxxrs-sxxxxr-sxxe.jpg"

Yes

type

Type of media file being uploaded. The following are the supported media:

image/jpeg

Yes

Sample Success Response

In case of successful uploading of the media file, then the following success message appears with the status 200:

200 OK
{
    "id": "10xxxxxxxxxxxx91"
}
📘

Note:

The id is the media ID that will be used to send media messages.


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."
    }
}




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