Send a Media Message through WhatsApp

POST Method

  1. Sign up for free

Before you get started, sign up for a account for free and Create an API Key. To view the API Key and the SID, see View API Key and SID.

  1. Pre-requisites

Below listed are the pre-requisites for using Kalyera WhatsApp APIs:

  • A WhatsApp business number.
  • An associated profile with the business number.
  • A WhatsApp verified and approved profile.

For more details, read what WhatsApp has to say about creating a business account.

  1. Send a media message

You can use the below API’s to send a media message via WhatsApp account

Request Format

cURL -X POST "<SID>/messages" \
     -H "Content-Type: <CONTENT_TYPE>" \
     -H "api-key:<API_KEY>" \
     -d "from=<FROM_NUMBER>" \
     -d "to=<TO_NUMBER>" \
     -d "type=<MESSAGE_TYPE>" \
     -d "channel=<CHANNEL_NAME>" \
     -d "body=<CONTENT>" \
     -d "caption=<MEDIA_CAPTION>"\
     -d "media=<MEDIA_FILE>" \
     -d "callback_url=<CALLBACK_URL>"
     -d "media_url=<MEDIA_URL>"



Replace the placeholders above with relevant values as mentioned below.

SIDAccount SID (Security Identifier). Generated by while creating an API key.HXXXXXXX071USTrue
CONTENT_TYPEThe format in which the data is sent.application/x-www-form-urlencodedTrue
API_KEYYour API Key generated by
FROM_NUMBERThe number registered with WhatsApp business from which the message is to be sent. Ensure that the country code is prefixed to the number. (E164 format).+1202XXXXXXXTrue
TO_NUMBERA valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).

Note: You can add multiple recipients, separate each number using the comma (,) delimiter.
MESSAGE_TYPEMessage format of the message to be sent.

For details on the formats supported, read Messaging on WhatsApp Business.
CHANNEL_NAMEChannel on which message must be sent.whatsappTrue
CONTENTContent of the messageOptional
MEDIA_CAPTIONA caption for the media file.Heading https://kaleyra.ioTrue
MEDIA_FILEThe location of the media file that will be embedded in the message.

Ensure you upload only the formats supported. Refer to
Messaging on WhatsApp Business for more details.
CALLBACK_URLThe URL that should send information to when your number receives a response. This URL can be accessed publicly.
Click here for an example.
MEDIA_URLThe media URL should be public and have a file extension.
Note: URL path is supported for image/video/media instead of uploading it.
If both media and media_url are passed in API request, then only "media_url" will be considered.
  1. Response Format

If your request is successful, the response will be similar to the response shown below:

    "id": "6e77bc24-fc4f-4c87-945f-12990d7342ef",
    "type": "media",
    "body": "Hey Welcome to kaleyra  Media Messaging Platform .",
    "createdDateTime": "2020-01-29 06:23:44+00:00",
    "totalCount": 1,
    "data": [
            "message_id": "6e77bc24-fc4f-4c87-945f-12990d7342ef:0",
            "recipient": "1202XXXXXXX"
    "error": {}

Failure Response

"code": "E438",
"message": " For the type text you cannot send media URL.",
"data": [],
"error": {
"type": " For the type text you cannot send media URL."

"code": "E419",
"message": " For the type media, media/media_url field is mandatory"
"data": [],
"error": {
"type": " For the type media, media/media_url field is mandatory"

Error Codes

The below table provides information about the error codes you would receive when executing the WhatsApp Media Message API.

Error CodeParameterDescription
E13008from_invalidInvalid or in-correct input of the From number.
E13009to_invalidInvalid or in-correct input of the TO number.
E13012invalid_mediaInvalid Media Content
E13014Invalid_mediaFailed to upload the Media file.