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

External-bot widget demo on Repl.it

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

{
text: "Hello"
}

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.

Microlanguage

Hello with buttons
* REPLY ONE
* REPLY TWO

JSON

{
type: "text",
text: "Hello with buttons",
attributes: {
attachment: {
type:"template",
buttons: [
{
type: "text",
value: "REPLY ONE"
},
{
type: "text",
value: "REPLY TWO"
}
]
}
}
}

Text message with URL buttons

image

The URL button opens an external or internal (to the widget) browser view. A target option is used to specify where to open the URL content. It can have "self" or "external" values. If a value is not specified it defaults to "external". Buttons of this type have a small arrow icon to help the user understand that tapping on a URL button will open an external link.

Microlanguage

Under development.

JSON

{
type: "text",
text: "Hello with buttons",
attributes: {
attachment: {
type:"template",
buttons: [
{
type: "url",
value: "SITE 1",
link: "http://www.tiledesk.com",
target: "self"
},
{
type: "url",
value: "SITE 2",
link: "http://www.ietf.org",
target: "external"
}
]
}
}
}

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_reply 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.

Microlanguage

Under development.

JSON

{
type: "text",
text: "Hello with buttons",
attributes: {
attachment: {
type:"template",
buttons: [
{
type: "action",
value: "EXECUTE AN ACTION",
action: "my-action-name",
**show_reply**: true
}
]
}
}
}

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

{
type: "text",
text: "This is an action for the backend",
attributes: {
action: "my-action-name"
}
}

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 accordingly the image size in the reply message.

Microlanguage

Images are defined as a line starting with: \image:IMAGE_URL with optional size: \image:WIDTH-HEIGHT:IMAGE_URL

Example:

Hello with image
\image:http://www.tiledesk.com/logo.jpg

With size:

Hello with resized image
\image:100-100:http://www.tiledesk.com/logo.jpg

JSON

{
type: "image",
text: "Hello with image",
metadata = {
src: "http://www.tiledesk.com/logo.jpg",
width: 200,
height: 200
}
}