Diyalog Messenger Platform Messaging API Reference

1. Sending Messages

Many types of content can be sent with Diyalog Messenger Platform including text, audio, images, video, files.

There are also some pre-defined messages templates available. You can send structured messages for a good user experience. All these messaging templates are copied from Facebook Messenger 😃 in order to compatibility with fb messenger. Therefore, you can directly integrate your as is facebook bot application to Diyalog Messenger platform.

Supported Templates
  • Generic Template
  • Button Template
  • Quick Reply Template
  • List Template ( not available yet)

1.1 Send API Reference

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":"1231231"
},
"message":{
"text":"hello world",
"quick_replies":[]
}
}' "https://<DIYALOG-SERVER-API-ENDPOINT>/v1/bots/sendmessage/<YOUR-BOT-ACCESS-TOKEN>"
Properties
PropertyTypeDescriptionRequired
recipientObjectrecipient objectyes
messageObjectmessage objecyyes
recipient

It declares the recipient of the message. Request must include one of id, appCustomerId

PropertyTypeDescriptionRequired
recipient.idStringIt is id of user in Diyalog platform. If you know it, you can directly use Diyalog user id.Optional
receipient.appCustomerIdStringYou can use direct customer id of your system. But Diyalog seesion should be created with this customer id. If you are using Token base authentication of DiyalogSDK in your client application, system will create user and save the customer id.Optional
message
PropertyTypeDescriptionRequired
message.messaging_typeStringNot Appicable - It is fb messenger default. It will be used later version of Diyalog Platform.No
message.tagStringNot Appicable - It is fb messenger default. It will be used later version of Diyalog Platform.No
message.textStringit is text message that will send to recipient. If you send text message you should set it, for other type of messages, you shoud set attachment property instead of text.Optional
message.attachmentObjectit is used to define message content other than text messages. If you want to send message other than text you should set attachment property instead of text.Optional
message.quick_repliesArray<quick_reply>it is used to send user quick reply buttons to user. If there is no any button you should send empty array obejct ([]).yes
attachment

The following can be included in the attachment object:

  • Rich media messages including images, audios, videos, or files.
  • Templates including generic template, button template, list template.
PropertyTypeDescriptionRequired
attachment.typeStringType of attachment, may be image, audio, video, file or templateyes
attachment.payloadObjectPayload of the attaachmentyes

1.2 Response

A successful Send API request returns a JSON string containing identifiers for the message and its recipient.

{
"recipient_id": "2074022437",
"message_id": "-7523925115459309081"
}
Properties
PropertyTypeDescription
recipient_idStringUnique user id that message sent in Diyalog platform
message_idObjectUnique id of the sent message in Diyalog Platform

2.Template Reference

2.1 Generic Template Reference

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. For complete implementation details, see Generic Template.

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":"1231231"
},
"message":{
"attachment":{
"type":"template",
"payload":{
"template_type":"generic",
"elements":[
{
"title":"Your Holiday Offer",
"image_url":"https://diyalog.im/app/testmessage/testimages/generictemplate-6.jpg",
"subtitle":"We have a special holiday offer for you. This holiday is for you.",
"default_action":{
"type":"web_url",
"url":"https://defaulaction.com",
"webview_height_ratio":"FULL"
},
"buttons":[
{
"type":"web_url",
"title":"I am interested",
"payload":"https://isbank.com.tr"
},
{
"type":"postback",
"title":"Cancel",
"payload":"cancelled1"
}
]
}
],
"buttons":[]
}
},
"quick_replies":[]
}
}' "https://<DIYALOG-SERVER-API-ENDPOINT>/v1/bots/sendmessage/<YOUR-BOT-ACCESS-TOKEN>"
Example Response
{
"recipient_id": "2074022437",
"message_id": "-7523925115459309081"
}
recipient

It declares the recipient of the message. Request must include one of id, appCustomerId

PropertyTypeDescriptionRequired
idStringIt is id of user in Diyalog platform. If you know it, you can directly use Diyalog user id.Optional
appCustomerIdStringYou can use direct customer id of your system. But Diyalog seesion should be created with this customer id. If you are using Token base authentication of DiyalogSDK in your client application, system will create user and save the customer id.Optional
message
PropertyTypeDescriptionRequired
attachmentObjectIt contains payload od the generic template contentyes
quick_repliesArray<quick_reply>This property will not used in generic template. It should be set empty array. []yes
message.attachment
PropertyTypeDescriptionRequired
typeStringValue must be templateyes
payloadObjectPayload of the generic templateyes
message.attachment.payload
PropertyTypeDescriptionRequired
template_typeStringValue must be genericyes
elementsArray<element>An array of element objects that describe instances of the generic template to be sent. Specifying multiple elements will send a horizontally scrollable carousel of templates. A maximum of 10 elements is supported.yes
buttonsArray<button>This property will not used in generic template. It should be set empty array. []yes
message.attachment.payload.elements
PropertyTypeDescriptionRequired
titleStringThe title to display in the template.Optional
subtitleStringThe subtitle to display in the template.Optional
image_urlStringThe URL of the image to display in the template.Optional
default_actionObject (default_action)The default action executed when the template is tapped.Optional
buttonsArray<button>An array of buttons to append to the template. A maximum of 3 buttons per element is supported. If you don't add any button you should set empty array [].yes
default_action
PropertyTypeDescriptionRequired
typeStringDefault action is only support url button. Value must be "web_url".yes
urlStringThe url address that will open when tapped to contentyes
webview_height_ratioStringValue must be *FULL"yes
button
PropertyTypeDescriptionRequired
typeStringType of the button. It can be web_url and postbackyes
titleStringButton title that will show in the button text.yes
payload_hiddenBooleanThis flag is valid for postback type button. You may want to signed your postback data by client application secrets. If you set this flag is true, Diyalog client sdk will signed postback by calling your application extension that has signData method.Optional
payloadStringPayload data that you want to turn back to your application. This will only return, if button type is postback. In web url you can set it to empty string.yes

2.2 Button Template Reference

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": "1231231"
},
"message": {
"attachment": {
"type": "template",
"payload": {
"template_type": "button",
"text" : "How can I help you?",
"buttons" : [
{
"type" :"web_url",
"title" : "Send Me Receipt",
"payload" : "https://diyalog.im/sendreceipt"
},
{
"type" :"postback",
"title" : "New Transaction",
"payload" : "start_new_tx"
}
],
"elements" : []
}
},
"quick_replies" : []
}
}' "https://<DIYALOG-SERVER-API-ENDPOINT>/v1/bots/sendmessage/<YOUR-BOT-ACCESS-TOKEN>"
Example Response
{
"recipient_id": "2074022437",
"message_id": "-7523925115459309081"
}
recipient

It declares the recipient of the message. Request must include one of id, appCustomerId

PropertyTypeDescriptionRequired
idStringIt is id of user in Diyalog platform. If you know it, you can directly use Diyalog user id.Optional
appCustomerIdStringYou can use direct customer id of your system. But Diyalog seesion should be created with this customer id. If you are using Token base authentication of DiyalogSDK in your client application, system will create user and save the customer id.Optional
message
PropertyTypeDescriptionRequired
attachmentObjectIt contains payload od the button template contentyes
quick_repliesArray<quick_reply>This property will not used in generic template. It should be set empty array. []yes
message.attachment
PropertyTypeDescriptionRequired
typeStringValue must be templateyes
payloadObjectPayload of the generic templateyes
message.attachment.payload
PropertyTypeDescriptionRequired
template_typeStringValue must be buttonyes
textStringMessage text that will show on top of the templateyes
buttonsArray<button>You can add buttons to your buton template message by adding button property to buttons arrayyes
elementsArray<element>This property will not used in generic template. It should be set empty array. []yes

2.3 Quick Reply Template Reference

Quick replies provide a way to present a set of up to 11 buttons in-conversation that contain a title and optional image, and appear prominently above the composer.

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": "1231232"
},
"message": {
"text" : "Do you want to continue?",
"quick_replies" : [
{
"content_type" : "text",
"title" : "Yes",
"payload" : "yes",
"image_url" : "https://diyalog.im/app/testmessage/testimages/quickreplytemplate-yes.png"
},
{
"content_type" : "text",
"title" : "No",
"payload" : "no",
"image_url" : "https://diyalog.im/app/testmessage/testimages/quickreplytemplate-no.png"
}
]
}
}' "https://<DIYALOG-SERVER-API-ENDPOINT>/v1/bots/sendmessage/<YOUR-BOT-ACCESS-TOKEN>"
Example Response
{
"recipient_id": "2074022437",
"message_id": "-7523925115459309081"
}
recipient

It declares the recipient of the message. Request must include one of id, appCustomerId

PropertyTypeDescriptionRequired
idStringIt is id of user in Diyalog platform. If you know it, you can directly use Diyalog user id.Optional
appCustomerIdStringYou can use direct customer id of your system. But Diyalog seesion should be created with this customer id. If you are using Token base authentication of DiyalogSDK in your client application, system will create user and save the customer id.Optional
message
PropertyTypeDescriptionRequired
textStringMessage text that will show on top of the templateyes
quick_repliesArray<quick_reply>Array of quick reply definitions.yes
quick_reply
PropertyTypeDescriptionRequired
content_typeStringValue must be textyes
titleStringQuick reply button labelyes
payloadStringIt is payload that will return to your application when pressed buttonyes
image_urlStringIf you want to add icon to your quick reply button, you can set icon urlOptional

Made with :heart: by Ayya Co Ltd.