Send a Media Message through WhatsApp

POST Method

Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.

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.

Send a media message.

Base URL

https://<api_domain>/v1/<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

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_domain>/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.in.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:

Parameter	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.	HXXXXXXX071IN	Yes
`api-key`	String	API key generated from kaleyra.io account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3	Yes
`to_number`	String	A 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.	+91XXXXXXXXXX	Yes
`type`	String	The type of message you want to send. For details on the formats supported, read Messaging on WhatsApp Business .	media	Yes
`channel`	String	Defines the channel name.	whatsapp	Yes
`from_number`	String	The 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).	+91XXXXXXXXXX	Yes
`callback_url`	String	The 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.com	No
`media_file`	Media	The 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.mp4	Yes
`media_url`	String	The 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.png	Yes
`caption`	String	A caption for the media file.	Heading https://kaleyra.io	Yes

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 Code	Parameter	Description
E13008	from_invalid	Invalid or in-correct input of the From number.
E13009	to_invalid	Invalid or in-correct input of the TO number.
E13012	invalid_media	Invalid Media Content
E13014	Invalid_media	Failed to upload the Media file.

Updated 7 days ago

What’s Next