SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Guides
Contact UsKaleyra.io Sign InSupport

Upload Media Files

POST Method

Suggest Edits

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.ap.kaleyra.io
EU Podapi.eu.kaleyra.io

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:

ParameterData TypeDescriptionExampleMandatory?
sidStringAccount SID (Security Identifier).HXAP16XXXXXX97INYes
phone_numberStringPhone number of end customer you want to send a message to.+91XXXXXXXXXXYes
(valid phone numbers only)
content_typeStringIndicates the format of the content the API will be processing.Only allowed value is application/jsonYes
api-keyStringAPI key generated from Kaleyra platform account.Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3Yes
fileObjectPath to the file stored in your local directory."@/2xxxxxxjn/cxxs-trxxxxrs-sxxxxr-sxxe.jpg"Yes
typeType 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/jpegYes

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 about 16 hours ago