Reply Button API

The Reply Button API is used to send interactive reply options (up to 3) in session messages via API. Also, notify you when customers are replying to Quick Reply Messages.

You can send the following messages:

  • Header Object - Image/Text/Document/Video
  • Body
  • Footer (Text)
    Header Type
    Header Value
  • Action - Buttons
    • Type - Reply
    • Button object - ID and Title

📘

  • Reply button messages cannot be used as notifications. Currently, they can only be sent within 24 hours of the last message sent by the user. If you try to send a message outside the 24-hour window, you will be prompt with an error message.
    • Supported platforms: iOS, Android, and Web.

Base URL

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

To access reply button API, perform the following steps:

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

Before you get started, sign up for a Kaleyra.io account for free and create an 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.

2. API command for Reply Button API

Request Format - POST

curl --location --request POST 'https://api.kaleyra.io/v1/<SID>/messages'
--header 'Content-Type: <CONTENT_TYPE>' 
--header 'api-key: <API_KEY>' 
--form 'to="<TO_NUMBER>"' 
--form 'type="<MESSAGE_TYPE>"' 
--form 'channel="<CHANNEL_NAME>"' 
--form 'from="<FROM_NUMBER>"' 
--form 'body="<BODY_TEXT>"' 
--form 'footer="<FOOTER_TEXT>"' 
--form 'action="{
            \"buttons\": [
                {
                    \"type\": \"reply\",
                    \"reply\": {
                        \"id\": \"1\",
                        \"title\": \"First Button Title\"
                    }
                },
                {
                    \"type\": \"reply\",
                    \"reply\": {
                        \"id\": \"2\",
                        \"title\": \"Second Button Title\"
                    }
                },
                {
                    \"type\": \"reply\",
                    \"reply\": {
                        \"id\": \"3\",
                        \"title\": \"Third Button Title\"
                    }
                }
            ]
        }"'
--form 'callback_url="<CALLBACK_URL>"' 
--form 'header_type="<HEADER_TYPE>"' 
--form 'header_value="<HEADER_VALUE>"'

Parameters and Variables

The following table displays the parameter 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

Alphanumeric

Indicates the format of the content the API will be processing.

application/JSON

True

API_KEY

String

Your API Key generated by Kaleyra.io.
Refer to the Creating An API Key and Security Identifier document for steps to create API Key.

Ac4XXXXX21f

True

TO_NUMBER

Integer

Specifies to number to be sent.

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

Text, list, reply and template

True

CHANNEL_NAME

String

Specifies the channel name.

WhatsApp

True

FROM_NUMBER

Integer

The WhatsApp business number registered with Kaleyra.io from which the message is to be sent.

+1202XXXXXXX

True

BODY_TEXT

String

Optional for type product. Required for other message types.
The body of the message. Emojis and markdown are supported. The maximum length is set to 1024 characters.

This is the text message content.

True

FOOTER_TEXT

String

Optional.
The footer of the message. Emojis and markdown are supported. The maximum length is set to 60 characters.

This is the footer content.

True

CALLBACK_URL

Object

The URL you want to receive the status of the message that is sent. This URL can be accessed publicly.

https://webhook.site/3cbfa310-7615-4bf6-b6f3-0e564493a254

True

HEADER_TYPE

String

Optional.
If you decide to include the header text, you must set the header’s type to text and add a text field with the desired content.

This is a header content.

True

Sample Request

Reply Message - with a Text Header

curl --location --request POST 'https://api.kaleyra.io/v1/HXXXXXXXXXX0S/messages' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--header 'api-key: Ac4XXXXX21f' 
--form 'to="91XXXXXXXXXX"' 
--form 'type="reply"' 
--form 'channel="WhatsApp"' 
--form 'from="+91XXXXXXXXXX"' 
--form 'body="Hi Test"' 
--form 'footer="Hey footer"' 
--form 'action="{
\"buttons\": [
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"1\",
\"title\": \"First Button Title\"
}
},
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"2\",
\"title\": \"Second Button Title\"
}
},
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"3\",
\"title\": \"Third Button Title\"
}
}
]
}"' \
--form 'callback_url="https://webhook.site/962dXXXX-2c91-43XX-bd01-513XXXXXXX68"' 
--form 'header_type="text"' 
--form 'header_value="Header text value"

Reply Message - with an Image Header

curl --location --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--header 'api-key: Ac4XXXXX21f' 
--form 'to="91XXXXXXXXXX"' 
--form 'type="reply"' 
--form 'channel="WhatsApp"' 
--form 'from="91XXXXXXXXXX"' 
--form 'body="Hi Test"' 
--form 'footer="Hey footer"' 
--form 'action="{
\"buttons\": [
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"1\",
\"title\": \"First Button Title\"
}
},
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"2\",
\"title\": \"Second Button Title\"
}
},
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"3\",
\"title\": \"Third Button Title\"
}
}
]
}"' 
--form 'callback_url="https://webhook.site/9XXXXX48-2XXc-XXXX-XXXX-XXXXXXXX516c"' 
--form 'header_type="image"' 
--form
'header_value="https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/XXXXXX1334KLlogo.png"'

--form 'caption="atul_image-Caption"'

Reply Message - with Video Header

curl --location --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--header 'api-key: Ac4XXXXX21f' 
--form 'to="91XXXXXXXXXX"' 
--form 'type="reply"' 
--form 'channel="WhatsApp"' 
--form 'from="+91XXXXXXXXXX"' 
--form 'body="Hi Test"' 
--form 'footer="Hey footer"' 
--form 'action="{
\"buttons\": [
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"1\",
\"title\": \"First Button Title\"
}
},
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"2\",
\"title\": \"Second Button Title\"
}
},
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"3\",
\"title\": \"Third Button Title\"
}
}
]
}"' 
--form 'callback_url="https://webhook.site/XXXXXXXX-2c91-4XXX-bd01-51XXXXXX3a6c"' 
--form 'header_type="video"' 
--form 'header_value="http://techslides.com/demos/sample-videos/small.mp4"' 
--form 'caption="testfilename"'

Reply Message - with Document Header

curl --location --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--header 'api-key: Ac4XXXXX21f' 
--form 'to="91XXXXXXXXXX"' 
--form 'type="reply"' 
--form 'channel="WhatsApp"' 
--form 'from="+91XXXXXXXXXX"' 
--form 'body="Hi Test"' 
--form 'footer="Hey footer"' 
--form 'action="{
\"buttons\": [
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"abc\",
\"title\": \"First Button Test\"
}
},
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"111\",
\"title\": \"Second Button Test\"
}
},
{
\"type\": \"reply\",
\"reply\": {
\"id\": \"3\",
\"title\": \"Third Button Test\"
}
}
]
}"' 
--form 'callback_url="https://webhook.site/XXXXXX98-2c91-4320-bd01-513XXXXXXXXX"' 
--form 'header_type="document"' 
--form
'header_value="https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/1614XXXXXXtestdoc.pdf"'
--form 'caption="fileNametest"'

Success Response

{
    "id": "fXXXXX8e-4e7d-4621-a36a-43XXXXXX7fbb",
    "type": "reply",
    "body": "Hi akshay",
    "createdDateTime": "2021-11-19 08:47:16+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "fXXXXXXX-4XXX-4XXX1-a36a-43XXXXXXXXb7:0",
            "recipient": "91XXXXXXXX89"
        }
    ],
    "error": {}
}

Failure Response

{
    "code": "E413",
    "message": "Invalid/incorrect inputs",
    "data": [],
    "error": {
        "type": "type field is mandatory"
    }
}
{
    "code": "E413",
    "message": "Invalid/incorrect inputs",
    "data": [],
    "error": {
        "body": "For the type reply, body field is mandatory and cannot be empty!"
    }
}

Error Codes

The following table provides information about the error codes you would receive when executing the List Message API.

Error Code

Description

'E413'

Invalid/incorrect inputs.


Did this page help you?