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

To access the 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. 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.

  1. 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:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USTrue
CONTENT_TYPEAlphanumericIndicates the format of the content the API will be processing.application/JSONTrue
API_KEYStringYour API Key generated by Kaleyra.io.
Refer to the Creating An API Key and Security Identifier document for steps to create API Key.
Ac4XXXXX21fTrue
TO_NUMBERIntegerSpecifies to number to be sent.+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.
Text, list, reply and templateTrue
CHANNEL_NAMEStringSpecifies the channel name.WhatsAppTrue
FROM_NUMBERIntegerThe WhatsApp business number registered with Kaleyra.io from which the message is to be sent.+1202XXXXXXXTrue
BODY_TEXTStringOptional 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_TEXTStringOptional.
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_URLObjectThe 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-0e564493a254True
HEADER_TYPEStringOptional.
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 CodeDescription
'E413'Invalid/incorrect inputs.