Send a Media Message through WhatsApp

POST Method

1. Sign up for free

Before you get started, sign up for a Kaleyra.io account for free and create an API key.

2. Pre-requisites

Below listed are the pre-requisites for using Kalyera WhatsApp API’s

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

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

Replace

With

Examples

Mandatory?

SID

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXXXXXXX071US

True

CONTENT_TYPE

The format in which the data is sent.

application/x-www-form-urlencoded

True

API_KEY

Your API Key generated by Kaleyra.io.

Ac4XXXXX21f

True

FROM_NUMBER

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

+1202XXXXXXX

True

TO_NUMBER

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.

+1202XXXXXXX

True

MESSAGE_TYPE

Message format of the message to be sent.

For details on the formats supported, read Messaging on WhatsApp Business.

media

True

CHANNEL_NAME

Channel on which message must be sent.

whatsapp

True

CONTENT

Content of the message

Optional

MEDIA_CAPTION

A caption for the media file.

Heading https://kaleyra.io

True

MEDIA_FILE

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

True

CALLBACK_URL

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.

False

MEDIA_URL

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://picsum.photos/250/250

True

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


Did this page help you?