Tiledesk Docs
Search…
Widget protocol specs
This document describes the raw JSON protocol specifications used by external chatbots (and by Tiledesk itself) to send messages to the widget. You can use this protocol from an external chatbot to customize messages for your end-users. The JSON protocol allows you to discover what kind of content the widget supports, building enhanced chatbot replies for increased user experience that go beyond simple text messages, adding images, special buttons and interaction.
New features are costantly added to Tiledesk widget so take a constant reference to this section to keep yourself updated with all the supported widget messages, controls and media that can be rendered in widget messages.

Resources

For a live demo of all the supported features described in this document you can refer to this external chatbot project on repl.it that you can use as a showcase of all the wideget features
You can also see a live demo of this chatbot on this tiledesk live page:
Live demo

Reply with a text message

To reply to your user with a text message by your external bot backend you should specify really few fields.
For example:

JSON

1
{
2
text: "Hello"
3
}
Copied!
Optional fields:
type field: optional. the value 'text' is the default one. Use this field to change the message type (e.g. 'image').
senderFullname field: optional, because Tiledesk knows who he is talking to. But this field is useful to set if you want to change the sender name for some reason.

Text message with reply buttons

image
Generally reply buttons are sent by chatbots. Reply buttons allow users to reply with a proposed sentence already built by the sender (generally the chatbot). Pressing the button simply sends the sentence (the text contained in the button) to the recipient (most of the time the external chatbot) on the other side.

JSON

1
{
2
type: "text",
3
text: "Hello with buttons",
4
attributes: {
5
attachment: {
6
type:"template",
7
buttons: [
8
{
9
type: "text",
10
value: "REPLY ONE"
11
},
12
{
13
type: "text",
14
value: "REPLY TWO"
15
}
16
]
17
}
18
}
19
}
Copied!

Text message with URL buttons

image
The URL button opens a link in a new browser tab, the same page hosting the widget or inside the widget itself.
A target option is used to specify where to open the URL content. It can have the blank, parent or self values. If a value is not specified it defaults to "blank".
Buttons of this type have a small arrow icon to help the user understand that tapping on a URL button will open a new window.
The self button is special because it opens the URL content directly inside a special frame of the widget itself. It as a slightly different arrow, pointing to the right orizzontally.
image
"self" buttons open the URL content in the "Widget frame" mode. In this mode the URL content appears into the same widget’s frame with a special header, showing the button title, a button to go back to the conversation and another button to open the content into a full browser window.
image
You can obtain the best results with "self" option if the content you are displaying plays good with the "responsive" mode, because of the small dimension of the widget makes it act with mobile-device-like responsiveness.

"blank" mode JSON

1
{
2
type: "text",
3
text: "Hello with buttons (blank)",
4
attributes: {
5
attachment: {
6
type:"template",
7
buttons: [
8
{
9
type: "url",
10
value: "SITE 1",
11
link: "http://www.tiledesk.com",
12
target: "blank"
13
}
14
]
15
}
16
}
17
}
Copied!

"parent" mode JSON

1
{
2
type: "text",
3
text: "Hello with buttons (parent)",
4
attributes: {
5
attachment: {
6
type:"template",
7
buttons: [
8
{
9
type: "url",
10
value: "SITE 2",
11
link: "http://www.ietf.org",
12
target: "parent"
13
}
14
]
15
}
16
}
17
}
Copied!

"self" (Widget frame) mode JSON

1
{
2
type: "text",
3
text: "Hello with buttons (self)",
4
attributes: {
5
attachment: {
6
type:"template",
7
buttons: [
8
{
9
type: "url",
10
value: "Dante",
11
link: "https://en.m.wikipedia.org/wiki/Dante_Alighieri",
12
target: "self"
13
}
14
]
15
}
16
}
17
}
Copied!

Message with Action buttons

When a user presses an action button, an “action” message is sent to the chatbot. Your chatbot will receive the "action" field value that you can use to execute some specific action. Upon receiving the action value, the chatbot can simply reply with a related-to-the-action reply message. If the show_echo option is set to true the widget will also show in the chat the message in the value field, giving evidence to the user that a real message was sent to the chatbot.

JSON

1
{
2
type: "text",
3
text: "Hello with buttons",
4
attributes: {
5
attachment: {
6
type:"template",
7
buttons: [
8
{
9
type: "action",
10
value: "EXECUTE AN ACTION",
11
action: "my-action-name",
12
show_echo: true
13
}
14
]
15
}
16
}
17
}
Copied!

Action message (replied by the Widget)

This format is used by Tiledesk chat clients (e.g. Web Widget) to send a message that contains an action for the backend. The message can be hidden or not on the widget, it doesn’t affect the message behaviour. The backend that receives messages with the “action” field set in the attributes section can choose to take a corresponding action, then optionally reply to the same message. A button with an action message has the same aspect as the standard reply button, but with a different, longest and evident animation.
JSON
1
{
2
type: "text",
3
text: "This is an action for the backend",
4
attributes: {
5
action: "my-action-name"
6
}
7
}
Copied!

Message with image

If you want to send an image from your external chatbot you should embed the image http source in the reply JSON schema shown below.
type field must be set to image
text field is optional.
metadata.src field is mandatory and must point to a valid image
metadata.width and metadata.height fields are optional. If set they will reduce the image size accordingly in the reply message.

JSON

1
{
2
type: "image",
3
text: "Hello with image",
4
metadata = {
5
src: "http://www.tiledesk.com/logo.jpg",
6
width: 200,
7
height: 200
8
}
9
}
Copied!

Message with content in iframe

You can send content to the web widget that can be easily embeddable into an iframe. For example you can send a youtube video, an external map, and also a mini HTML5 video game!
type must be set to 'frame'
text is optional.
metadata.src is mandatory and must point to a valid http content embaddable into an HTML5 iframe
metadata.width and metadata.height are optional. If set, they will reduce the iframe size accordingly in the reply message.

JSON

1
{
2
type: "frame",
3
text: "This is a video!",
4
metadata = {
5
src: "https://www.youtube.com/embed/H1WfFkp4puw"
6
}
7
}
Copied!

Disable the reply textbox

You can temporarely disable the user input textbox. This feature is useful, for example, when you provided a set of reply buttons and you want the user to press one of these buttons to continue the conversation.
attributes.disableInputMessage if true the reply textbox is disabled
attributes.inputMessagePlaceholder if set the reply textbox placeholder is replaced by this text. Used only when attributes.disableInputMessage is true

JSON

To disable the reply textbox set the above properties in the attributes section, as in the following example:
1
{
2
type: "text",
3
text: "Do you agree? Please press one of the buttons to proceed",
4
attributes = {
5
disableInputMessage: true,
6
inputMessagePlaceholder: 'Press a button to continue',
7
attachment: {
8
type:"template",
9
buttons: [
10
{
11
type: "text",
12
value: "Yes, I do"
13
},
14
{
15
type: "text",
16
value: "No, I do not"
17
}
18
]
19
}
20
}
21
}
Copied!
As you can see in the following image, the input textbox is disabled, until the next message arrives.
image
Last modified 1mo ago