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_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 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 image/png For more information about supported media types, see Supported Media Types.	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."
    }
}

Updated 2 days ago