Send Interactive Message and Media Template

POST Method

Description

Include interactive buttons to media messages by using below component objects.

There are two types of predefined buttons:

  • Quick Reply — Allows customer to return a simple text message
  • Call-to-Action (CTA) — Allows customer to call a phone number and visit a website

Quick Reply

Refers to a previously created quick reply button that allows the customer to return a predefined message.

Call-to-Action

Allows customers to call a phone number and visit a website.

📘

Note:

  • If the Type of Action is Call Phone Number, the user can add a button text, country code, and number.
  • If Type of Action is Visit Website, the user can add a URL Type.

About Button Type

It is the type of button being created. You can have up to 3 buttons using index values of 0 to 2.
The document media message template type is currently limited to PDF format. You have to create a template in Kaleyra.io with buttons and pass the template name through API.
Example: quick_reply and URL.

Base URL

"https://api.kaleyra.io/v1/"

To Send Dynamic URL, follow the below steps:

1. Signup or Login to Kaleyra.io and create your API key.

Refer to the Create an API Key page for steps to create your API key.

📘

Note:

After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in Kaleyra.io.

API Command to send Dynamic URL

Request Format

To send the Dynamic URL, use the /messages endpoints.

cURL -X POST "https://api.kaleyra.io/v1/<SID>/messages" \
     -H "Content-Type: <CONTENT_TYPE>" \
     -H "api-key:<API_KEY>" \
     -d "to=<TO_NUMBER>" \
     -d "type=<MESSAGE_TYPE>" \
     -d "params=<TEMPLATE_BODY_PARAMETERS>" \ 
     -d "template_name=<TEMPLATE_NAME>" \ 
     -d "channel=<CHANNEL_NAME>" \
     -d "from=<FROM_NUMBER>" \
     -d "callback_url=<CALLBACK_URL>" \
     -d 'param_url=<PARAM_URL>"\

📘

Note:

Ensure to replace the parameter values with the proper inputs in the above code.

Parameters and Variables

The below displays the parameters and variables used:

Parameter

Variable

Description

Example

Mandatory

SID

String

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

HXXXXXXX071US

True

CONTENT_TYPE

String

The format in which the data is sent.

application/x-www-form-urlencoded

True

API_KEY

String

Generate this API Key in the Kaleyra.io.
Refer to the Creating An API Key and Security Identifier document for steps to create API Key.

Ac4XXXXX21f

True

TO_NUMBER

Integer

This is the valid WhatsApp number of the recipient. Ensure to prefix the country code to the number (E164 format).

Note: You can add multiple recipients, separated by comma (,) delimiter.

+1202XXXXXXX

True

MESSAGE_TYPE

String

Format of the message that is to be sent.

For more details on the supported formats, refer to the Messaging on WhatsApp Business document.

mediatemplate

True

TEMPLATE_BODY_PARAMETERS

String

The values that you will pass when you want to send a message using the template. Since the values are dynamic, it must be passed through the key. Multiple parameters are allowed that must be separated with a comma.

For a template that says: Hi your booking id is for date the params to be passed would be <id_number>.

"param1","param"

True

TEMPLATE_NAME

String

Name of the WhatsApp media template that was created in the Kaleyra.io portal. This name must be approved by WhatsApp before you start using this API.

booking_confirm

True

CHANNEL_NAME

String

Channel on which message must be sent.

WhatsApp

True

FROM_NUMBER

Integer

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

CALLBACK_URL

String

The URL that Kaleyra.io should send information to when your number receives a response. This URL can be accessed publicly.

https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345c

False

PARAM_URL

String

The values that are set dynamically in a page's URL, and can be accessed by its template and its data sources. The Call-to-Action button uses param_url.

Login

False

3. Response Format

This section provides you the successful JSON response format.

Success Response

{
    "id": "9xxxxxxx-bxxx-4xxx-9xxx-exxxxxxxxxxx",
    "type": "mediatemplate",
    "body": null,
    "createdDateTime": "2020-12-08 07:09:37+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "9xxxxxxx-bxxx-4xxx-9xxx-exxxxxxxxxxx:x",
            "recipient": "91xxxxxxxxxx"
        }
    ],
    "error": {}
}

📘

Note:

In case of error, ensure that the above replaceable values are correct. See Standard Error Codes

Sample Request

cURL -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages" \
     -H "Content-Type:application/x-www-form-urlencoded" \
     -H "api-key:Ac4XXXXX21f" \
     -d "to=+1XXXXXXXXXX" \
     -d "type=mediatemplate" \
     -d 'params="John","Doe"' \ 
     -d "template_name=imt_dynamic" \ 
     -d "channel=whatsapp" \
     -d "from=+1202XXXXXXX" \
     -d "callback_url=https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345c"
     -d "param_url=https://google.com"
cURL -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages" \
     -H "Content-Type:application/x-www-form-urlencoded" \
     -H "api-key:Ac4XXXXX21f" \
     -d "to=+1XXXXXXXXXX" \
     -d "type=mediatemplate" \
     -d 'params="John","Doe"' \ 
     -d "template_name=imt_dynamic" \ 
     -d "channel=whatsapp" \
     -d "from=+1202XXXXXXX" \
     -d "callback_url=https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345c"
     -d "param_url=https://google.com"
     {
                "type": "button",
                "sub_type" : "quick_reply",
                "index": "0", 
                "parameters": [
                    {
                        "type": "payload",
                        # Business Developer-defined payload
                        "payload":"aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
                    }
                ]
            },

Did this page help you?