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/>SID>

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. To view the API Key and the SID, see View API Key and SID.

📘

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:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USTrue
CONTENT_TYPEStringThe format in which the data is sent.application/x-www-form-urlencodedTrue
API_KEYStringGenerate this API Key in the Kaleyra.io.
Refer to the Creating An API Key and Security Identifier document for steps to create API Key.
Ac4XXXXX21fTrue
TO_NUMBERIntegerThis 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.
+1202XXXXXXXTrue
MESSAGE_TYPEStringFormat of the message that is to be sent.

For more details on the supported formats, refer to the Messaging on WhatsApp Business document.
mediatemplateTrue
TEMPLATE_BODY_PARAMETERSStringThe 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_NAMEStringName 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_confirmTrue
CHANNEL_NAMEStringChannel on which message must be sent.WhatsAppTrue
FROM_NUMBERIntegerThe 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
CALLBACK_URLStringThe 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-3379b4b3345cFalse
PARAM_URLStringThe 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.LoginFalse
  1. 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"
                    }
                ]
            },