Send a Media Message through WhatsApp

POST Method

  1. Sign up for free

Before you get started, 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 "https://api.kaleyra.io/v1/<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>"

📘

Note:

Replace the placeholders above with relevant values as mentioned below.

ReplaceWithExamplesMandatory?
SIDAccount SID (Security Identifier). Generated by Kaleyra.io 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 Kaleyra.io.Ac4XXXXX21fTrue
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.
+1202XXXXXXXTrue
MESSAGE_TYPEMessage format of the message to be sent.

For details on the formats supported, read Messaging on WhatsApp Business.
mediaTrue
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.
@/C:/Users/company_A/Downloads/videoplayback.mp4True
CALLBACK_URLThe URL that Kaleyra.io should send information to when your number receives a response. This URL can be accessed publicly.
Click here for an example.
False
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.
https://www.kaleyra.com/wp-content/uploads/kaleyra.pngTrue
  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.