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

The following is the request format to send Media Message through WhatsApp:

curl --location 'https://api.kaleyra.io/v1/<sid>/messages' \
--header 'api-key: <api_Key>' \
--form 'to="<to_number>"' \
--form 'type="<type>"' \
--form 'channel="<channel_name>"' \
--form 'from="<from_number>"' \
--form 'callback_url="<callback_url>"' \
--form 'media="<media_file>"' \
--form 'media_url="<media_url>"' \
--form 'caption="<media_caption>"'

Sample Request Format

The following is the sample request format to send Media Messages through WhatsApp:

curl --location 'https://api.kaleyra.io/v1/HXAP16XXXXXX97IN/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--form 'to="+91XXXXXXXXXX"' \
--form 'type="media"' \
--form 'channel="whatsapp"' \
--form 'from="+91XXXXXXXXXX"' \
--form 'callback_url="https://callbacktesting2.free.beeceptor.com"' \
--form 'media="@/C:/Users/company_A/Downloads/videoplayback.mp4"' \
--form 'media_url="https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/1614840334KLlogo.png"' \
--form 'caption="This is the capton"'

Parameter and Data Types

The following is the list of parameters and data types supported for sending a media message through WhatsApp:

ParameterData Type DescriptionExampleMandatory?
sidStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USYes
api-keyStringAPI key generated from kaleyra.io account.Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3Yes
to_numberStringA 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.
+91XXXXXXXXXXYes
typeStringThe type of message you want to send.
For details on the formats supported, read Messaging on WhatsApp Business .
mediaYes
channelStringDefines the channel name.whatsappYes
from_numberStringThe 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).+91XXXXXXXXXXYes
callback_urlStringThe 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.
https://callbacktesting2.free.beeceptor.comNo
media_fileMediaThe 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.mp4Yes
media_urlStringThe 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.pngYes
captionStringA caption for the media file.Heading https://kaleyra.ioYes

Sample Success Response

The following success message appears with the status 202 Accepted:

{
    "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": {}
}

Sample 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.