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.

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.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.na.kaleyra.ai

API Request to send Interactive Message and Media Template

To send the interactive message and media template, use the /messages endpoints.

Request Format

The following is the request format to send Interactive Message and Media Template:

curl --location 'https://<api_domain>/v1/<sid>/messages' \
--header 'api-key: <api-key>' \
--form 'to=<to_number>' \
--form 'type=<message_type>' \
--form 'params=<params>' \
--form 'template_name=<template_name>' \
--form 'channel=<channel_name>' \
--form 'from=<from_number>' \
--form 'param_url=<param_url>' \
--form 'second_param_url=<second_param_url>' \
--form 'callback_url=<callback_url>'

Sample Request Format

The following is the sample request format to send Interactive Message and Media Template:

curl --location 'https://api.in.kaleyra.io//v1/HXIN1783361374IN/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--form 'to=91XXXXXXXXXX,91XXXXXXXXXX' \
--form 'type=mediatemplate' \
--form 'params=John","Doe' \
--form 'template_name=Booking_confirm' \
--form 'channel=whatsapp' \
--form 'from=91XXXXXXXXXX' \
--form 'param_url=login/{kadvanced}' \
--form 'second_param_url=sample/{kadvanced}' \
--form 'callback_url=https://wh7baXXXXXXX263e899f.free.beeceptor.com'

Parameter and Data Types

The following is the list of parameters and data types supported to send Interactive Message and Media Template:

Parameter

Data Type

Description

Example

Mandatory?

sid

String

Account SID (Security Identifier).

HXXXXXXX071IN

Yes

api-key

String

API key generated from kaleyra.io account.

Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3

Yes

to_number

Integer

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

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

Yes

params

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.

"John","Doe"

Yes

template_name

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

Yes

channel_name

String

whatsapp

Yes

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

91XXXXXXXXXX

Yes

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 param_url is used for the button type "dynamic URL".

login/{kadvanced}

No

second_parm_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 param_url is used for the button type "dynamic URL".

sample/{kadvanced}

No

callback_url

String

Specifies the callback URL to receive notifications regarding the WhatsApp message status (sent, delivered, read, and failed). For more information related to callback profiles, see the Callback profiles page.
The URL can be accessed publicly.
Click here for an example.

https://wh7baXXXXXXX263e899f.free.beeceptor.com

No

Sample Success Response

The following success message appears with the status 200 Accepted:

{
    "id": "9XXXXXXX-XXXX-48b9-88f7-XXXXXXXXXXeea",
    "type": "mediatemplate",
    "body": null,
    "createdDateTime": "2024-08-28 14:29:15+00:00",
    "totalCount": 2,
    "data": [
        {
            "message_id": "9aXXXXXX-40d8-XXXX-88f7-eeXXXXXXXXXX:0",
            "recipient": "91XXXXXXXXXX"
        },
        {
            "message_id": "9a5483d1-40d8-48b9-88f7-eXXXXXXXXea1:1",
            "recipient": "91XXXXXXXXXX"
        }
    ],
    "error": {
        "msg": "Callback not initiated as the URL is not Whitelisted."
    }
}

Sample Failure Response

The following is a sample failure response.

{
    "code": "E424",
    "message": "For type template/mediatemplate, template_name is mandatory and cannot be empty!",
    "data": [],
    "error": {
        "error": "For type template/mediatemplate, template_name is mandatory and cannot be empty!"
    }
}




© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.