Button Template Message

The button template allows you to send a structured message that includes text and buttons.

The button template sends a text message with up to three attached buttons. This template is useful for offering the message recipient options to choose from, such as pre-determined responses to a question, or actions to take.

Request URI

https://<DIYALOG-SERVER-API-ENDPOINT>/v1/bots/sendmessage/<YOUR-BOT-ACCESS-TOKEN>

Example Request

curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"appCustomerId": "123456789"
},
"message": {
"messageId":"messageId-1",
"attachment": {
"type": "template",
"payload": {
"templateType": "button",
"text" : "How can I help you?",
"messageId":"messageId-1",
"buttons" : [],
"buttonsV2" : [
{
"type" :"postback",
"title" : "Send Me Receipt",
"payload" : "211",
"payloadHidden" : true,
"payloadSeenByUser" : "Send me receipt"
},
{
"type" :"postback",
"title" : "Cancel Transaction",
"payload" : "211",
"payloadHidden" : true,
"payloadSeenByUser" : "Cancel my transaction"
},
{
"type" :"web_url",
"title" : "New Transaction",
"payload" : "https://dlgmessenger.com"
}
],
"elements" : []
}
},
"quickReplies" : [],
"quickRepliesV2" : []
}
}' "https://<DIYALOG-SERVER-API-ENDPOINT>/v1/bots/sendmessage/<YOUR-BOT-ACCESS-TOKEN>"

Request Details

recipient

You can pass the user information you want to send the message to api in the recipient object.

PropertyTypeDescriptionMandatory
appCustomerIdStringCustomer id in your systemOptional
appStaffIdStringYour staff id.Optional
idStringUnique DLG user id.Optional

You can pass the the user information that will receive your message with this object. Your request should only have one of the properties that appCustomerId, appStaffId or id.

There are two unique id for a single user in the DLG platform One of them is DLG user id. This id is created randomly when user registering to the system. Besides of this id, according to the user type, one of the customer id or staff id are stored for the user in DLG.

As a result, you can use one of the customer id or staff id and DLG id in order to send message.

If you know the DLG user id, you can use it for customor or staff.

Using customer id and staff id is more applicable than using DLG user id. Because if you want to use DLG id, you should store all DLG user ids in your system.

message

The content of the Button Template message can be given in the attachment property instead of text propeperty to the api.

quickReplies and quicRepliesV2 properties are not applicable for this template. Therefore, the values of them should be set as empty array.

PropertyTypeDescriptionMandatory
messageIdStringThis is a unique id of your message. You should create it in your system and send it to api. If you don't create and sent it to api DLG will create it for you and send it to you in the response of your request. DLG platfrom will feed the events of the messages to your system by this id. You can use it to differenciate events by this id. Therefore, this id is important for following all events of your message by your system.Optional
attachmentObjectattachment object that has content of the message.Yes
quickRepliesArray<quickReply>It should be set as empty array. ("quickReplies" : [])Yes
quickRepliesV2Array<quickReplyV2>It should be set as empty array. ("quickRepliesV2" : [])Yes

attachment

attachment is the property that has content of the messages other then text messages.

PropertyTypeDescriptionMandatory
typeStringIt should be set as "template"Yes
payloadObjectThe payload of the Button template message content.Yes

payload

It is the payload that contains content of the button template messsage.

PropertyTypeDescriptionMandatory
templateTypeStringIt should be set as "button" .Yes
messageIdStringIt is message id that received from the request of your message. When a button pressed in the Button Template message by user, this id will return to your application with the payload of the button. By this way, you will have an additional data that will help you find which button pressed.Yes
textStringText of the message.Yes
buttonsArray<button>It should be set as empty array. ("buttons" : [])Yes
buttonsV2Array<buttonV2>It is the array of the buttons. Button template message supports maximum 3 buttons. You can add maximum 3 button to the array.Yes
elementsArray<element>It is not applicable for Button Template message. It should be sert as empty array ("elements" : [] ).Yes

buttonV2

PropertyTypeDescriptionMandatory
typeStringDetermines the behavior of the button when the button is pressed. There are two types, "postback" and "web_url".Yes
titleStringTitle of the button.Yes
payloadStringIt is the payload of the button. If button type is "postback", the value of this property will return to your application via webhook when pressed the button by the user. If button type is "web_url", the value of it should be a valid uri address. Because when pressed the button, this uri will be open in the user's device.Yes
payloadHiddenBooleanThis property is applicable for postback type of button. If it is set as true, the payload of the button signed with your company's secret keys in the user's device, return to your application via webhook when user pressed the button.Optional
payloadSeenByUserStringThe value of this property will be displayed in the chat screen of the user when pressed the button. If it does not set, the value of the payload will be displayed in the chat screen.Optional
Important Note :

When user pressed a button in a message, the value of the payload property will return to your application via webhook mechanism.

If the value of the payloadHidden is true, the payload of the button signed with your company's secret keys in the user's device, return to your application via webhook when user pressed the button. By this way, you can be sure about the payload return from a valid device. Sure, your application can decrypt and validate the signed payload.

Another critical information is messageId in the payload object. It is important, because it is returned to your application together with payload when user pressed the button. By this way, you can determine which button pressed in which messsage.

Message id will return with payload of the button to your application in the following format.
"[<messageId>]:<payload>" ( when payloadHidden is false)
"[<messageId>]:<signed payload>" ( when payloadHidden is true)

Response

Successful API requests return the json object with the answer code http-2XX.

Sample response

{
"recipient_id": "2074022437",
"message_id": "-7523925115459309081"
}