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 (https://developer.tiledesk.com/external-chatbot/integrate-your-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 constantly added to the Tiledesk widget — keep this section as a reference to stay updated with all supported widget messages, controls and media that can be rendered in widget messages.

Resources

For a live demo of many supported features, see this external chatbot project on repl.it:

• External-bot widget demo on Repl.it: https://repl.it/@andreasponziell/tiledesk-widget-protocol-example#index.js

Live demo page:

• https://widget.tiledesk.com/v4/assets/twp/index.html?project_name=Widget+showcase+demo&tiledesk_projectid=5f8474e99c9f0200125b01c0

Text message

Sending a text to the widget requires a minimal JSON. Example — send "Hello":

JSON

{
    "text": "Hello"
}

Options:

• type: optional. The value "text" is the default. Use to change message type (e.g. image).

• senderFullname: optional. Useful if you want to change the sender name.

Quick replies

Quick Replies (generally sent by chatbots) allow users to quickly reply with a proposed option. Pressing the button sends the text contained in the button label to the recipient (often the chatbot).

Image preview: https://developer.tiledesk.com/~gitbook/image?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F32564846%2F95662490-abe5c100-0b37-11eb-8621-bfb7f324845c.png&width=768&dpr=4&quality=100&sign=97d5cbf4&sv=2

JSON

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

URL buttons

The URL button opens a link in a new browser tab, the same page hosting the widget, or inside the widget itself.

• target: optional, can be "blank", "parent" or "self" (defaults to "blank" if omitted).

• "self" opens the URL content inside the widget frame (see Widget frame below).

• URL buttons show a small arrow icon indicating they open a new window. "self" buttons have a horizontal arrow.

Images:

• https://developer.tiledesk.com/~gitbook/image?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F32564846%2F95662652-c9675a80-0b38-11eb-8bf7-a489dfb7e9ce.png&width=768&dpr=4&quality=100&sign=70e5d1aa&sv=2

• https://developer.tiledesk.com/~gitbook/image?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F32564846%2F140601014-e3967820-7dce-492a-b4f0-353dfbd57188.png&width=768&dpr=4&quality=100&sign=a8edf646&sv=2

• https://developer.tiledesk.com/~gitbook/image?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F32564846%2F140600868-c3093864-d02d-4c72-ba09-acb2b767e7d8.png&width=768&dpr=4&quality=100&sign=1be151f5&sv=2

"blank" mode JSON

{
    "type": "text",
    "text": "Hello with buttons (blank)",
    "attributes": {
        "attachment": {
            "type": "template",
            "buttons": [
                {
                    "type": "url",
                    "value": "SITE 1",
                    "link": "http://www.tiledesk.com",
                    "target": "blank"
                }
            ]
        }
    }
}

"parent" mode JSON

{
    "type": "text",
    "text": "Hello with buttons (parent)",
    "attributes": {
        "attachment": {
            "type": "template",
            "buttons": [
                {
                    "type": "url",
                    "value": "SITE 2",
                    "link": "http://www.ietf.org",
                    "target": "parent"
                }
            ]
        }
    }
}

"self" (Widget frame) mode JSON

{
    "type": "text",
    "text": "Hello with buttons (self)",
    "attributes": {
        "attachment": {
            "type": "template",
            "buttons": [
                {
                    "type": "url",
                    "value": "Dante",
                    "link": "https://en.m.wikipedia.org/wiki/Dante_Alighieri",
                    "target": "self"
                }
            ]
        }
    }
}

Action buttons

When a user presses an action button, an "action" message is sent to the chatbot. The chatbot receives the action field value and can execute a corresponding action. If show_echo is true, the widget will also show the value as a message in the chat to indicate to the user that a real message was sent.

JSON

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

Action message (replied by the Widget)

This format is used by Tiledesk chat clients to send a message that contains an action for the backend. The backend receiving messages with the attributes.action field can take a corresponding action and optionally reply.

JSON

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

Image attachment

To send an image, set type to "image". metadata.src is mandatory and must point to a valid image URL. metadata.width and metadata.height are optional.

JSON

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

File attachment

To send a document, set type to "file". metadata.src is mandatory and must be a valid HTTP URL pointing to the binary file. metadata.type is mandatory (content-type). metadata.name is optional.

JSON

{
    "type": "file",
    "text": "My document is sent as attachment",
    "metadata": {
        "name": "sales-report.pdf",
        "src": "http://www.mywebsite.com/sales-report.pdf",
        "type": "application/pdf"
    }
}

iframe content messages

Send content embeddable in an HTML iframe (e.g. YouTube video, map, mini HTML5 game).

• type: "frame"

• metadata.src: mandatory and must point to content embeddable in an iframe

• metadata.width, metadata.height: optional to set iframe size

JSON

{
    "type": "frame",
    "text": "This is a video!",
    "metadata": {
        "src": "https://www.youtube.com/embed/H1WfFkp4puw"
    }
}

Disable the reply textbox

Temporarily disable the user input textbox. Useful when providing reply buttons and you want the user to choose one.

• attributes.disableInputMessage: if true, the reply textbox is disabled

• attributes.inputMessagePlaceholder: used only when disableInputMessage is true; replaces the textbox placeholder

JSON

{
    "type": "text",
    "text": "Do you agree? Please press one of the buttons to proceed",
    "attributes": {
        "disableInputMessage": true,
        "inputMessagePlaceholder": "Press a button to continue",
        "attachment": {
            "type": "template",
            "buttons": [
                {
                    "type": "text",
                    "value": "Yes, I do"
                },
                {
                    "type": "text",
                    "value": "No, I do not"
                }
            ]
        }
    }
}

Image preview: https://developer.tiledesk.com/~gitbook/image?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F32564846%2F144202116-3035b6e0-ba89-4fbb-b15c-fa24ec7825bb.png&width=768&dpr=4&quality=100&sign=914f2721&sv=2

Update user metadata

Update the widget user's fullname and email so subsequent messages use updated info.

• attributes.updateUserFullname: updates the user's full name

• attributes.updateUserEmail: updates the user's email

JSON example

{
    "text": "Thanks Andrea, we got your data and will take care of it!",
    "attributes": {
        "updateUserEmail": "[email protected]",
        "updateUserFullname": "Andrea"
    }
}

Hidden messages

To send messages hidden to end-users (useful to trigger chatbot actions without showing the triggering text), use info messages. Info messages are hidden in end-user channels but visible in teammate chat.

• attributes.subtype: set to "info" to hide the message from end-users.

JSON

{
    "type": "text",
    "text": "start",
    "attributes": {
        "subtype": "info"
    }
}

Splitted messages

Instead of sending multiple separate messages from the server (which can arrive out of order), you can send a single message containing a sequence of commands (message and wait) in attributes.commands. The widget will render them in order and preserve timing.

Example: send a long chatbot reply split into several messages with delays.

Image preview: https://developer.tiledesk.com/~gitbook/image?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F32564846%2F169641648-4271e7bf-0e20-4356-ab58-e61391ee25f7.png&width=768&dpr=4&quality=100&sign=aa610231&sv=2

JSON

{
  "text": "Hello 👋. I'm a bot 🤖 I'm beautiful Do you need help I can really help you with joy!",
  "attributes": {
    "commands": [
      {
        "type": "message",
        "message": {
          "text": "Hello 👋. I'm a bot 🤖",
          "type": "text"
        }
      },
      {
        "type": "wait",
        "time": 500
      },
      {
        "type": "message",
        "message": {
          "text": "I'm beautiful",
          "type": "text"
        }
      },
      {
        "type": "wait",
        "time": 1000
      },
      {
        "type": "message",
        "message": {
          "text": "Do you need help?",
          "type": "text"
        }
      },
      {
        "type": "wait",
        "time": 2000
      },
      {
        "type": "message",
        "message": {
          "text": "I can really help you with joy!",
          "type": "text",
          "attributes": {
            "attachment": {
              "type": "template",
              "buttons": [
                {
                  "type": "url",
                  "value": "Get Help",
                  "link": "https://gethelp.tiledesk.com/articles/install-widget-on-your-website/",
                  "target": "self"
                },
                {
                  "type": "url",
                  "value": "Wikipedia",
                  "link": "https://it.m.wikipedia.org/wiki/E_Street_Band",
                  "target": "self"
                }
              ]
            }
          }
        }
      }
    ]
  }
}

Commands reference (use the stepper for clarity)

1

message

• type: "message"

• Carries a complete message object in message property (text, type, attributes, etc.).

• The widget displays this as the next piece of the split content.

2

wait

• type: "wait"

• time: number — delay in milliseconds before processing the next command.

• Used to emulate typing pauses/delays between split messages.

HTML messages

The widget can receive messages containing HTML and render them inside the conversation. Set type to "html" and put your HTML code in the text field. Link buttons and basic styling are supported.

Image preview: https://developer.tiledesk.com/~gitbook/image?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F47848430%2F173019659-69e0e537-54ee-4d5b-8049-56ebd03abe7e.png&width=768&dpr=4&quality=100&sign=b1de0079&sv=2

JSON example (trimmed for readability)

{
    "attributes": {},
    "type": "html",
    "text": "<html>\n  <head>\n    <style>\n      .text-html { font-size: 14px; }\n      .button-html { font-size: 10px !important; }\n    </style>\n  </head>\n  <body>\n    <div>\n      <p class=\"text-html\"><b>This is an HTML message type example</b></p>\n      <p class=\"text-html\"> Place any html tag to be loaded here... </p>\n    </div>\n    <br><br>\n    <div><p class=\"text-html\"> Button example below 👇🏻</p></div>\n    <button type=\"button\" class=\"button-html url\" onclick=\"window.open('https://www.tiledesk.com', '_blank')\">Button 1</button>\n    <button type=\"button\" class=\"button-html url\" onclick=\"window.open('https://developer.tiledesk.com/widget/web-sdk', '_blank')\">Button 2</button>\n    <button type=\"button\" class=\"button-html url\" onclick=\"window.open('https://developer.tiledesk.com/widget/advanced', '_blank')\">Button 3</button>\n    <br><br>\n    <div><p class=\"text-html\"> Image example below 👇🏻</p></div>\n    <div class=\"img-container\">\n      <img src=\"https://tiledesk.com/wp-content/uploads/2020/08/tiledesk-logo_x4_vpadding.png\" width=\"200px\">\n    </div>\n  </body>\n</html>"
}

Notes:

• You can include CSS inside

• Widget recognizes and applies styles for .text-html, .button-html, .image-container; you can override them.

Last updated: 2 years ago

Privacy

• This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the privacy policy: https://tiledesk.com/privacy.html

Was this helpful?