Generic Template Message

The generic template allows you to send a structured message that includes an image, text and buttons. A generic template with multiple templates described in the elements array will send a horizontally scrollable carousel of items, each composed of an image, text and buttons.

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": "generic",
"elements": [
{
"title": "Your Holiday Offer",
"imageUrl": "https://diyalog.im/app/testmessage/testimages/generictemplate-6.jpg",
"subtitle": "We have a special holiday offer for you. This holiday is for you.",
"messageId": "messageid-of-element-0",
"buttons" : [],
"buttonsV2" : [
{
"type" :"postback",
"title" : "I am interested22",
"payload" : "campaing1-approved",
"payloadHidden": true,
"payloadSeenByUser": "I am interested"
},
{
"type" :"postback",
"title" : "Cancel",
"payload" : "cncl",
"payloadHidden": false,
"payloadSeenByUser": "Cancel"
}
]
},
{
"title": "Flight Ticket Offer",
"imageUrl": "https://diyalog.im/app/testmessage/testimages/generictemplate-5.jpg",
"subtitle": "You can take flight ticket with big discount.",
"messageId": "messageid-of-element-1",
"buttons" : [],
"buttonsV2" : [
{
"type" :"web_url",
"title" : "Open Offer",
"payload" : "http://dlgmessenger.com"
},
{
"type" :"postback",
"title" : "Cancel",
"payload" : "cncl",
"payloadHidden": false,
"payloadSeenByUser": "Cancel"
}
]
}
],
"buttons" : [],
"buttonsV2": []
}
},
"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 Generic Template message can be given in the attachment property instead of text propeperty to the api.

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 generic template messsage.

PropertyTypeDescriptionMandatory
templateTypeStringIt should be set as "generic" .Yes
elementsArray<element>It is array of the generic message (element).Yes
buttonsArray<button>It should be set as empty array. ("buttons" : [])Yes
buttonsV2Array<buttonV2>It should be set as empty array. ("buttonsV2" : [])Yes

element

Element is one of the building blocks of the generic template message. Messages of the generic template type can consist of one or more elements.

An element consists of an image, text title, text and at least 0 and 3 buttons at most.

The appearance of an element is as follows.

PropertyTypeDescriptionMandatory
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.Optional
titleStringTitle of the element.Optional
subtitleStringSubtitle of the element.Optional
imageUrlStringUrl of the image that will be add messsage.Optional
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

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"
}