Teneo Web Chat

Teneo Web Chat is a chat widget that can be embedded in websites. It has built-in support for various message types like buttons, quick replies, images, audio, videos, and cards, and the powerful JavaScript API allows for easy live chat integration and extendability.

Quick Replies

Core features

Supports various message types, like cards, images, buttons, quick replies, etc.
Lightweight
Easy to embed in websites
Extendable through a powerful Javascript API
Works on all major browsers like Chrome, Edge, Firefox, Internet Explorer 11, Opera, and Safari
Works on mobile devices
Accessible (WCAG ready)
Available in multiple languages, easy to localize
Open source, you can find the source code on Github
Rating Message.
Upload files.
TTS Capabilities with WebSpeechAPI

Setting up Teneo Web Chat

Giving Teneo Web Chat a try

Once you've published your bot, you can interact with it using Teneo Web Chat. On your bots page you will find a list of all solutions for your team. Clicking the Teneo Web Chat button of your published bot opens a new tab with an example page containing Teneo Web Chat. Because the example page does not require a login, you can share it with your colleagues.

Adding Teneo Web Chat to your site

To add the web chat UI to your site, proceed as follows:

Download the file teneo-web-chat.js from the latest release on Github and add it to your site.
Add the following code before the closing tag to each page where you want the web chat window to appear.

javascript

1<!-- Teneo Web Chat start -->
2<div id="teneo-web-chat"></div>
3<script src="/path/to/teneo-web-chat.js"></script>
4<script>
5  window.onload = function () {
6    if (
7      window.TeneoWebChat &&
8        typeof window.TeneoWebChat.initialize === 'function'
9    ) {
10      var element = document.getElementById('teneo-web-chat');
11      const teneoProps = {
12        'teneoEngineUrl': 'https://some.teneo/engine-instance/',
13      }
14      window.TeneoWebChat.initialize(element,teneoProps);
15    }
16  }
17</script>
18<!-- Teneo Web Chat end -->
19

When adding the script to your site, note the following:

Make sure /path/to/teneo-web-chat.js is replaced with the correct path.
Make sure https://some.teneo/engine-instance/ is updated to match the URL of your engine.
For better experience on mobile add the meta tag in the <head></head> area as follows:

<meta name="viewport" content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content">

Embedding Teneo Web Chat using an iFrame

An alternative way of adding Teneo Web Chat to your site is by embedding Teneo Web Chat in an iFrame. That will also enable you to support cross-domain browsing for Teneo Web Chat. You can find a repository with more details and example code here: Teneo Web Chat cross-domain example.

Configuration settings

When initializing Teneo Web Chat, an object containing configuration settings needs to be passed on. In the code above, the object is called teneoProps. The following settings are supported:

Property	Type	Description
teneoEngineUrl	string	Mandatory. The URL of the Teneo Engine.
title	string	Optional. Title shown in the header. If empty or not provided, 'Teneo Web Chat' is used.
titleIconUrl	string	Optional. URL to a custom icon (with a size of 24x24 pixels). Both 'plain' URL's and data URL's are supported. If empty or not provided, the default icon is used.
showCloseButton	boolean	Optional. If true, a close button is shown next to the minimize button. When clicked, the chat window is closed, the chat history deleted and the engine session is ended.
closeIconUrl	string	Optional. URL to a custom close icon (with a size of 32x32 pixels). Both 'plain' URL's and data URL's are supported. If empty or not provided, the default icon is used.
minimizeIconUrl	string	Optional. URL to a custom minimize icon (with a size of 32x32 pixels). Both 'plain' URL's and data URL's are supported. If empty or not provided, the default icon is used.
launchIconUrl	string	Optional. URL to a custom launch icon (with a size of 26x26 pixels). Both 'plain' URL's and data URL's are supported. If empty or not provided, the default icon is used.
sendIconUrl	string	Optional. URL to a custom send icon (with a size of 20x20 pixels). Both 'plain' URL's and data URL's are supported. If empty or not provided, the default icon is used.
botAvatarUrl	string	Optional. URL to a custom bot avatar (with a size of 34x34 pixels) shown next to messages with author 'bot'. Both 'plain' URL's and data URL's are supported. If empty or not provided, no avatar will be shown.
userAvatarUrl	string	Optional. URL to a custom user avatar (with a size of 34x34 pixels) shown next to messages with author user. Both 'plain' URL's and data URL's are supported. If empty or not provided, no avatar will be shown.
agentAvatarUrl	string	Optional. URL to a custom agent avatar (with a size of 34x34 pixels) shown next to messages with author agent. Both 'plain' URL's and data URL's are supported. If empty or not provided, no avatar will be shown.
teneoEngineParams	object	Optional. Key-value pairs of input parameters that should be included in requests to the Teneo Engine. Both the keys and the values in the map should be strings.
locale	string	Optional. Locale that should be used for labels and text, like the placeholder text in the input box. If no locale is provided, `en` is used. Teneo Web Chat is available in the following languages: da (Danish)de (German)en (English)en-GB (English UK)es (Spanish)fr (French)id (Indonesian)it (Italian)ja (Japanese)nl (Dutch)pt (Portuguese)sv (Swedish)tr (Turkish)zh-CN (Chinese Simplified)zh-TW (Chinese Traditional)ms (Malaysian)
customLocalizations	object	Optional. Object containing custom localized strings. See Custom localizations for details.
storage	object	Optional. Web storage object that should be used to store chat history and session id. If not provided sessionStorage will be used.
showUploadButton	boolean	Optional. If true, an upload button is shown next to the send button. When clicked, the On upload_button_clicked callback is called.
uploadIconUrl	string	Optional. URL to a custom upload icon (with a size of 20x20 pixels). Both 'plain' URL's and data URL's are supported. If empty or not provided, the default icon is used.
fileUploadSymbolProgressBackgroundColor	string	Optional. color for the background of the spinner for the upload messages, if no color is provided default is used
fileUploadSymbolProgressBarColor	string	Optional. Color for the progress bar of the spinner for the upload messages, if no color is provided default is used
fileUploadSymbolFailed	Unicode symbol	Optional. Icon of symbol in unicode value that indicates that the upload of a file failed for example ❌. If no value is assigned default value will be used. (unicode &#x27f3)
fileUploadSymbolInterrupted	Unicode symbol	Optional. Icon of symbol in unicode value to indicate the interruption of the upload for example !. If no value is assigned default value will be used. (unicode &#9888)
fileUploadSymbolDelete	Unicode symbol	Optional. Icon of symbol in unicode value that indicates deletion of the uploaded file for example ←. If no value is assigned default value will be used. (unicode &#x1F5D1)
fileUploadSymbolStop	Unicode symbol	Optional. Icon of symbol in unicode value to indicate a to stop the upload for example ✋. If no value is assigned default value will be used. (unicode &#x23F3)
fileUploadSymbolRestart	Unicode symbol	Optional. Icon of symbol in unicode value to indicate a restart to upload a file for example 🔃. If no value is assigned default value will be used. (unicode &#x27f3)
fileUploadSymbolRetry	Unicode symbol	Optional. Icon of symbol in unicode value to indicate a retry on the upload for example 🔄. If no value is assigned default value will be used. (unicode &#x27f3)
uploadPanelAddFilesSymbol	Unicode symbol/String	Optional. Value for add files button on the upload panel or unicode symbol for example 'Add file'. If no value is assigned default value will be used. ('+')
showScrollDownButton	boolean	Optional. If true, a scrolldown button is shown on the right side of the chat window. When clicked, it will scroll down to the end of the conversation.

Message types

Teneo Web Chat offers various message types that can be 'attached' to the bot's answer text. This is achieved by adding an output parameter teneowebclient with JSON specific for the message type. For more details on how to populate output parameters, see: Populate output parameters in the 'Build your bot' section.

The following message types are supported:

Image

Teneo Web Chat - Image

To add an image, the JSON that should be included in the teneowebclient output parameter looks as follows:

json

1{
2    "type": "image",
3    "image_url": "https://url.to/an/image.png",
4    "thumbnail_url": "https://url.to/a/thumbnail.png",
5    "alt": "This is an image"
6}
7

Notes:

If only the image_url is present, the image will be shown in the chat history as a thumbnail and the image can be clicked to enlarge it
If only the thumbnail_url is present, the thumbnail image will be shown in the chat history but it cannot be clicked to enlarge it
If both the image-url and the thumbnail_url are present, the thumbnail_url will be used for the thumbnail in the chat history and when clicked the image_url will be used for the enlarged image

Videos

Teneo Web Chat - Youtube Video

Teneo Web Chat supports the following video platforms:

YouTube
Vimeo
Mp4 videos

The general JSON to add a video looks like this:

json

1{
2    "type": "[videotype]",
3    "video_url": "[url]"
4}
5

The type and URL differ depending on the platform that is used to host the video. The following are examples of supported platforms:

Youtube:

json

1{
2    "type": "youtubevideo",
3    "video_url": "https://www.youtube.com/embed/123456789"
4}
5

Note that the URL of a YouTube video should start with https://www.youtube.com/embed/.

Vimeo:

json

1{
2    "type": "vimeovideo",
3    "video_url": "https://player.vimeo.com/video/12345678"
4}
5

Note that the URL of a Vimeo video should start with https://player.vimeo.com/video/.

mp4 video:

json

1{
2    "type": "filevideo",
3    "video_url": "https://url.to/a/video.mp4"
4}
5

Note that the type is filevideo.

Audio

To display an audio player, the JSON that should be included in the teneowebclient output parameter looks as follows:

json

1{
2    "type": "audio",
3    "audio_url": "https://url.to/audio.mp3"
4}
5

Buttons

Teneo Web Chat - Buttons

The title above the buttons is optional. The style attribute in the JSON determines the colors of the buttons. When clicked, a 'postback' value is sent to the engine as a user input. Only buttons in the most recent message can be clicked.

The JSON that should be included in the teneowebclient output parameter should look as follows:

json

1{
2    "type": "buttons",
3    "title": "Optional title",
4    "button_items": [
5        {
6            "style": "primary",
7            "title": "Primary",
8            "postback": "Primary"
9        },
10        {
11            "style": "secondary",
12            "title": "Secondary",
13            "postback": "Secondary"
14        },
15        {
16            "style": "success",
17            "title": "Success",
18            "postback": "Success"
19        },
20        {
21            "style": "danger",
22            "title": "Danger",
23            "postback": "Danger"
24        },
25        {
26            "style": "warning",
27            "title": "Warning",
28            "postback": "Warning"
29        },
30        {
31            "style": "info",
32            "title": "Info",
33            "postback": "Info"
34        }
35    ]
36}
37

If the 'style' of a button is omitted, the primary color is used.

Input parameters

In addition to the above, buttons can contain input parameters that will be included in the request to engine when the user clicks a button. They are defined as follows:

json

1...
2    {
3        "style": "primary",
4        "title": "Primary",
5        "postback": "Primary",
6        "parameters": { "button": "primary" }
7    }
8...
9

In the example above, an input parameter button with value primary will be included in the request to engine when the button is clicked. See How to store input parameters for instructions on how to process input parameters in Studio.

Quick replies

Quick Replies

Quick replies behave the same as buttons but are pill-shaped. Quick replies don't have a title. The style attribute in the JSON determines the colors of the quick replies. When clicked, a 'postback' value is sent to the engine as a user input. Only quick replies in the most recent message can be clicked.

The JSON that should be included in the teneowebclient output parameter should look as follows:

json

1{
2    "type": "quickreply",
3    "quick_replies": [
4        {
5            "style": "primary",
6            "title": "Primary",
7            "postback": "Primary"
8        },
9        {
10            "style": "secondary",
11            "title": "Secondary",
12            "postback": "Secondary"
13        },
14        {
15            "style": "success",
16            "title": "Success",
17            "postback": "Success"
18        },
19        {
20            "style": "danger",
21            "title": "Danger",
22            "postback": "Danger"
23        },
24        {
25            "style": "warning",
26            "title": "Warning",
27            "postback": "Warning"
28        },
29        {
30            "style": "info",
31            "title": "Info",
32            "postback": "Info"
33        }
34    ]
35}
36

Notes:

If the 'style' of a quick reply is omitted, the primary color is used.
Just like buttons, quick replies can contain input parameters.

Clickable list

Teneo Web Chat - Clickable list

The title above the list of clickable items is optional. When clicked, a 'postback' value is sent to the engine as a user input. Clickable lists don't have a style attribute (like buttons and quick replies). Only clickable lists in the most recent message can be clicked.

The JSON that should be included in the teneowebclient output parameter should look as follows:

json

1{
2    "type": "clickablelist",
3    "title": "Optional title",
4    "list_items": [
5        {
6            "title": "One",
7            "postback": "One"
8        },
9        {
10            "title": "Two",
11            "postback": "Two"
12        },
13        {
14            "title": "Three",
15            "postback": "Three"
16        },
17        {
18            "title": "Four",
19            "postback": "Four"
20        },
21        {
22            "title": "Five",
23            "postback": "Five"
24        },
25        {
26            "title": "Six",
27            "postback": "Six"
28        }
29    ]
30}
31

Note: Just like buttons, clickable lists can contain input parameters.

Link buttons

Teneo Web Chat - Link Buttons

The title above the link buttons is optional. When clicked, the URL of the link button is opened in the specified target window. Link buttons don't have a style attribute (like buttons and quick replies). Unlike quick replies, they don't expire, but can be clicked even in older messages. They don't return a postback value to engine, but do trigger the On message button clicked event.

The JSON that should be included in the teneowebclient output parameter looks as follows:

json

1{
2    "type": "linkbuttons",
3    "title": "Optional title",
4    "linkbutton_items": [
5        {
6            "title": "Link 1",
7            "url": "https://url.to/a/page",
8            "target": "_blank"
9        },
10        {
11            "title": "Link 2",
12            "url": "https://url.to/another/page",
13            "target": "_blank"
14        },
15        {
16            "title": "Link 3",
17            "link": "https://url.to/yet/another/page"
18        }
19    ]
20}
21

Tables

Teneo Web Chat - Table

The title above the table, the header row, and the footer row are optional. Accepts only text content in the cells, no HTML or additional message templates can be used. The table will expand the number of cells per row to the number of cells in the longest row.

The JSON that should be included in the teneowebclient output parameter looks as follows:

json

1{
2  "type": "table",
3  "title": "Table Title",
4  "headers": [
5    "Header1",
6    "Header2",
7    "Header3"
8  ],
9  "body": [
10    [
11      "Row1 Cell1",
12      "Row1 Cell2",
13      "Row1 Cell3"
14    ],
15    [
16      "Row2 Cell1",
17      "Row2 Cell2",
18      "Row2 Cell3",
19      "Row2 Cell4"
20    ],
21    [
22      "Row3 Cell1",
23      "Row3 Cell2"
24    ],
25    [
26      "Row4 Cell1",
27      "Row4 Cell2",
28      "Row4 Cell3"
29    ],
30    [
31      "Row5 Cell1",
32      "Row5 Cell2",
33      "Row5 Cell3"
34    ]
35  ],
36  "footers": [
37    "Footer1",
38    "Footer2"
39  ]
40}
41

Forms

Teneo Web Chat - Form

The form message type allows for information to be gathered from the user during a conversation. Almost all elements that are allowed inside an HTML form are permitted here, with the exception of Fieldsets and Optgroups. To build a form, an array is passed in the elements key of the JSON (example below).

The following table contains all the possible elements types that can be added to a form. The control elements (submit and cancel) and at least one other element are required. All types can have an attributes field that is an object that contains the HTML attributes that will be assigned to the field, applicable examples in the table below. While the form is active the user input field is disabled and cannot be typed into. All fields which have the required attribute will have a * added to the end of their labels.

Once submitted or cancelled, the collected data (or none) will be sent to the Teneo Engine as a JSON, with an additional boolean field named success added to it. From the solution side you can parse the message received and use the success field to determine whether the form was sent or closed.

Type	Fields	Comments
title	text (String): The content of the form title.	Optional, only 1 per form.
subtitle	text (String): The content of the form subtitle.	Optional, only 1 per form.
caption	text (String): The content of the form caption.	Optional, only 1 per form.
control	action (String): One of submit or cancel. Determines whether the control button will submit or cancel the sending of the form.	Required. One of each action per form.
	text (String): The text for inside of the button.
label	text (String): The content of the label.	Optional, no limit. These labels can be used to convey information to the user that is not tied to a particular input field, for example, to advise that fields marked with * are required. These labels look the same as the labels defined as companions for other elements (see input entry).
input	label (String): The text for the form label that has the for attribute pointing to the input element. Includes labels that accompany checkboxes and radio buttons.	Optional, no limit. Inputs are the main elements used in a form, together with select and textarea. How these elements are rendered depends on the browser the user is on.
	attributes (Object): These are the attributes that will be added to the HTML tag, type is not required and will default to text if not supplied.
	Common attributes:
	type (String): The type of input, any valid HTML type attribute for input nodes*
	required (Boolean (special)): Whether the element is required to submit the form. Any value, including false, will make the element required, omit completely if not required.
	pattern (Regular Expression): This field can be used to validate the content of a field. Only valid for fields with alphanumeric inputs, ie, types text, email, number, password, search, tel, URL.
	title (String): This field is used together with pattern to give the user an error message when the pattern is not matched.
	value (Alphanumeric): Assigns a value to the field. In radios and checkboxes, it will correspond to the box when ticked. In alphanumeric fields, date pickers, and color pickers it will prepopulate them. In buttons, it will provide the text inside the button.
	name (String): This field will be used to group inputs of types of radio together. Radio buttons with the same name can only have one input selected.
textarea	text (String): The value to prepopulate the field with.	Optional, no limit. The minimal height possible is two line heights.
	label (String): The text for the form label that has the for attribute pointing to the textarea element.
	placeholder (String): is a short, faded text snippet that hints at the expected input.
select	options (Array of Objects): The content of the options in the select. Each object in the array must contain a text field with the words for the dropdown. Additionally, an attributes object can be passed as in the top-level inputs, see example in JSON below.	Optional, no limit. The minimal height possible is two line heights.
	label (String): The text for the form label that has the for attribute pointing to the select element.

*Note: Types file and submit are not supported and will be stripped off, as it could affect the functionality of the form. Instead, use the control elements mentioned above to add the submit and cancel buttons. For uploading files, please refer to the file upload functionality.

The JSON that should be included in the teneowebclient output parameter looks as follows:

json

1{
2  "type": "form",
3  "elements": [
4    {
5      "type": "title",
6      "text": "Form Title"
7    },
8    {
9      "type": "subtitle",
10      "text": "Form Subtitle"
11    },
12    {
13      "type": "label",
14      "text": "This is an additional label to let people know * means required"
15    },
16    {
17      "type": "input",
18      "attributes": {
19        "type": "",
20        "required": true
21      },
22      "label": "Text Input Required Example"
23    },
24    {
25      "type": "input",
26      "attributes": {
27        "type": "text",
28        "pattern": "[A-Za-z]{3}",
29        "required": true,
30        "title": "Three Letters Only"
31      },
32      "label": "Text Input Validation Pattern Example - 3 letters"
33    },
34    {
35      "type": "label",
36      "text": "These inputs are extra buttons that do nothing!"
37    },
38    {
39      "type": "input",
40      "attributes": {
41        "type": "button",
42        "value": "Boink"
43      }
44    },
45    {
46      "type": "input",
47      "attributes": {
48        "type": "button",
49        "value": "Doink"
50      }
51    },
52    {
53      "type": "label",
54      "text": "These inputs are radio buttons"
55    },
56    {
57      "type": "input",
58      "attributes": {
59        "type": "radio",
60        "value": "1",
61        "name": "radios"
62      },
63      "label": "one"
64    },
65    {
66      "type": "input",
67      "attributes": {
68        "type": "radio",
69        "value": "2",
70        "name": "radios"
71      },
72      "label": "two"
73    },
74    {
75      "type": "input",
76      "attributes": {
77        "type": "radio",
78        "value": "3",
79        "name": "radios"
80      },
81      "label": "three"
82    },
83    {
84      "type": "input",
85      "attributes": {
86        "type": "radio",
87        "value": "4",
88        "name": "radios"
89      },
90      "label": "four"
91    },
92    {
93      "type": "input",
94      "attributes": {
95        "type": "radio",
96        "value": "5",
97        "name": "radios"
98      },
99      "label": "five"
100    },
101    {
102      "type": "input",
103      "attributes": {
104        "type": "radio",
105        "value": "6",
106        "name": "radios"
107      },
108      "label": "six"
109    },
110    {
111      "type": "label",
112      "text": "These inputs are checkboxes"
113    },
114    {
115      "type": "input",
116      "attributes": {
117        "type": "checkbox",
118        "value": "dog"
119      },
120      "label": "dog"
121    },
122    {
123      "type": "input",
124      "attributes": {
125        "type": "checkbox",
126        "value": "cat"
127      },
128      "label": "cat"
129    },
130    {
131      "type": "input",
132      "attributes": {
133        "type": "checkbox",
134        "value": "hamster"
135      },
136      "label": "hamster"
137    },
138    {
139      "type": "input",
140      "attributes": {
141        "type": "date"
142      },
143      "label": "This input is a datepicker!"
144    },
145    {
146      "type": "input",
147      "attributes": {
148        "type": "time"
149      },
150      "label": "This input is a timepicker!"
151    },
152    {
153      "type": "input",
154      "attributes": {
155        "type": "datetime-local"
156      },
157      "label": "This input is a datetimepicker!"
158    },
159    {
160      "type": "input",
161      "attributes": {
162        "type": "color"
163      },
164      "label": "This input is a colorpicker!"
165    },
166    {
167      "type": "input",
168      "attributes": {
169        "type": "range"
170      },
171      "label": "This input is a range!"
172    },
173    {
174      "type": "input",
175      "attributes": {
176        "type": "reset",
177        "text": "reset"
178      },
179      "label": "This input is a reset!"
180    },
181    {
182      "type": "textarea",
183      "attributes":{"name":"textarea"},
184      "text": "Prepopulated text in textarea.",
185      "label": "Text Area Example"
186    },
187    {
188      "type": "select",
189      "attributes":{"name":"select"},
190      "label": "Example Select",
191      "options": [
192        {
193          "text": "select one below",
194          "attributes": {
195            "disabled": true
196          }
197        },
198        {
199          "text": "1"
200        },
201        {
202          "text": "2"
203        },
204        {
205          "text": "3"
206        }
207      ]
208    },
209    {
210      "type": "control",
211      "text": "Cancel",
212      "action": "cancel"
213    },
214    {
215      "type": "control",
216      "text": "OK",
217      "action": "submit"
218    },
219    {
220      "type": "caption",
221      "text": "form caption"
222    }
223  ]
224}
225

Cards

Teneo Web Chat - Card

The main elements of a card are the image, title, subtitle, and body. All elements are optional, but you should include at least one of them. Card images have a fixed height of 180px and look best when they have a ratio of 3x2.

The JSON that should be included in the teneowebclient output parameter looks as follows:

json

1{
2    "type": "card",
3    "image": {
4        "image_url": "https://url.to/an/image.png",
5        "alt": "This is an image"
6    },
7    "title": "This is the title",
8    "subtitle": "This is the subtitle",
9    "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt."
10}
11

In addition to the above, cards can contain a section with buttons, link buttons, or a clickable list.

Card with buttons: Teneo Web Chat - Card with buttons

json

1{
2    "type": "card",
3    "image": {
4        "image_url": "https://url.to/an/image.png",
5        "alt": "This is an image"
6    },
7    "title": "This is the title",
8    "subtitle": "This is the subtitle",
9    "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.",
10    "button_items": [
11        {
12            "style": "primary",
13            "title": "Primary",
14            "postback": "Primary"
15        },
16        {
17            "style": "secondary",
18            "title": "Secondary",
19            "postback": "Secondary"
20        },
21        {
22            "style": "success",
23            "title": "Success",
24            "postback": "Success"
25        }
26    ]
27}
28

Card with a clickable list Teneo Web Chat - Clickable List new

json

1{
2    "type": "card",
3    "image": {
4        "image_url": "https://url.to/an/image.png",
5        "alt": "This is an image"
6    },
7    "title": "This is the title",
8    "subtitle": "This is the subtitle",
9    "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.",
10    "list_items": [
11        {
12            "title": "One",
13            "postback": "One"
14        },
15        {
16            "title": "Two",
17            "postback": "Two"
18        },
19        {
20            "title": "Three",
21            "postback": "Three"
22        }
23    ]
24}
25

Card with link buttons: Teneo Web Chat - Link Buttons

json

1{
2    "type": "card",
3    "image": {
4        "image_url": "https://url.to/an/image.png",
5        "alt": "This is an image"
6    },
7    "title": "This is the title",
8    "subtitle": "This is the subtitle",
9    "text": "Lorem ipsum dolor sit amet, consec tetur adipisicing elit.",
10    "linkbutton_items": [
11        {
12            "title": "Card link",
13            "url": "https://url.to/a/page"
14        },
15        {
16            "title": "Another link",
17            "url": "https://url.to/another/page",
18            "target": "_blank"
19        }
20    ]
21}
22

Carousel message

You can group cards into a carousel type message.

Teneo Web Chat - Carousel

The main content elements of a carousel are cards. A carousel can contain up to 10 cards inside of carousel_items.

json

1{
2  "type": "carousel",
3  "carousel_items": [
4    {
5      "type": "card",
6      "image": {
7        "image_url": "https://as-freaky-styley-714c5e.bots.teneo.ai/teneo_web_chat_tes_3gzgctjx5q84x8fztj2bdzxtrh/images/trees.png",
8        "alt": "This is an image"
9      },
10      "title": "Card 1",
11      "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.",
12      "button_items": [
13        {
14          "title": "One",
15          "postback": "One"
16        },
17        {
18          "title": "Two",
19          "postback": "Two"
20        },
21        {
22          "title": "Three",
23          "postback": "Three"
24        }
25      ]
26    },
27    {
28      "type": "card",
29      "image": {
30        "image_url": "https://as-freaky-styley-714c5e.bots.teneo.ai/teneo_web_chat_tes_3gzgctjx5q84x8fztj2bdzxtrh/images/trees.png",
31        "alt": "This is an image"
32      },
33      "title": "Card 2",
34      "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.",
35      "list_items": [
36        {
37          "title": "One",
38          "postback": "One"
39        },
40        {
41          "title": "Two",
42          "postback": "Two"
43        }
44      ]
45    },
46    {
47      "type": "card",
48      "image": {
49        "image_url": "https://as-freaky-styley-714c5e.bots.teneo.ai/teneo_web_chat_tes_3gzgctjx5q84x8fztj2bdzxtrh/images/trees.png",
50        "alt": "Trees in a forrest"
51      },
52      "title": "LinkButton Card",
53      "text": "This is the text of the card.",
54      "linkbutton_items": [
55        {
56          "title": "Studio",
57          "url": "https://developers.artificial-solutions.com/studio",
58          "target": "_blank"
59        },
60        {
61          "title": "Engine",
62          "url": "https://developers.artificial-solutions.com/engine",
63          "target": "_blank"
64        }
65      ]
66    }
67  ]
68}
69

Modal message

Modal messages appear on top of the chat window and block the user from interacting with the chat window until the modal is dismissed.

Teneo Web Chat - Modal Message

The main content elements of a modal are an image, a title, and a body. All elements are optional, but you should include at least one of them. Additionally, a modal can contain buttons. Modal images have a maximum height of 100px.

json

1{ 
2    "type": "modal", 
3    "image": { 
4        "image_url": "https://url.to/an/image.png",
5        "alt": "This is an image"
6    }, 
7    "title": "This is the title", 
8    "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit.", 
9    "button_items": [
10        { 
11            "style": "secondary", 
12            "title": "Secondary", 
13            "postback": "modal-secondary" 
14        }, 
15        { 
16            "style": "danger", 
17            "title": "Danger", 
18            "postback": "modal-danger" 
19        }
20    ] 
21}
22

Link Preview message

Link Previews can be used to display a little bit of information to the user about the page they are about to visit. This includes the page title, description, domain, and an image. Due to space limitations, descriptions are limited to 144 characters, but the full text will be made available as a tooltip.

Teneo Web Chat - Link Preview

Link Preview messages can be either generated manually using the JSON below, or they can be rendered automatically by giving the autoRedirect setting a false value. If you don't override the setting, it will default to true, and all links in the Output Hyperlink field of the Output nodes in Studio will automatically redirect the user to the URL defined there.

Teneo Web Chat - Output Parameter

The data in the Link Preview is gathered from the meta tags of the target page. Due to CORS restrictions, the data from these tags has to be requested from the server side. In order to do so, please include this Groovy script in the Resources -> File area of Studio. Make sure to set the path to /script_lib.

Teneo Web Chat - Preview Properites

Then under Globals -> Scripts -> Post-processing add the following line of code:

groovy

1if( _.outputURL){ _.outputURL= PreviewProperties.get( _.outputURL)}
2

getoutputpreview

In some cases, the target page doesn't have the necessary meta tags, in which case a localized message is displayed in place of the title or the description. You can learn how to modify this message in the Custom localizations page.

json

1{
2  "type": "linkpreview",
3  "title": "Link title",
4  "description": "Short text for the preview",
5  "url": "https://example.com",
6  "image": "https://url.to/an/image.png"
7}
8

Note: If the solution is not ready to handle this type of links, it will display the system message Unable to open hyperlink ,check your configuration for autoRedirect in your client and your solution for the proper configuration.

System message

Teneo Web Chat - System Message

json

1{
2  "type": "system",
3  "text": "This is a system message."
4}
5

Combo message

You can combine multiple message types in a single bot response by using a 'combo' message.

Teneo Web Chat - Combo

The following message types can be included in a combo message:

Buttons
Cards
Clickable lists
Images
Link buttons
Quick replies
Text messages
Videos
Audio players

You can include as many of these messages as you need in the order you like. Obviously one should take into account that the height of the chat window is limited; when too many messages are added, some of them may scroll out of view.

The JSON used to create the combo message in the screenshot looks as follows:

json

1{
2    "type": "combo",
3    "components": [
4        {
5            "type": "card",
6            "image": {
7                "image_url": "https://url.to/an/image.png",
8                "alt": "This is an image"
9            },
10            "title": "This is the title",
11            "subtitle": "This is the subtitle",
12            "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt."
13        },
14        {
15            "type": "text",
16            "text": "This is an additional speech bubble shown below the card."
17        },
18        {
19            "type": "buttons",
20            "title": "Are you sure?",
21            "button_items": [
22                {
23                    "style": "danger",
24                    "title": "Yes",
25                    "postback": "Yes"
26                },
27                {
28                    "style": "success",
29                    "title": "No",
30                    "postback": "No"
31                }
32            ]
33        }
34    ]
35}
36

Rating Message.

Allows users to rate and comment on items or experiences using a personalized scale. This message type simplifies the rating process and stores the chosen value for further use. It offers a customizable rating system and the option to leave comments.

To include a rating message in the bot's answer, use the following JSON in the teneowebclient output parameter:

json

1
2{
3"type": "rating",
4"title": "title text",
5"maxValue": "i",
6"commentsAllowed": true
7}
8
9

where maxValue parameter is required and it represents the upper limit or rating scale for the rating (number of stars). For additional details about the rating message, please refer to the provided link here!

rating message

Splitting answers into 'bubbles'

Sometimes you may wish to provide an answer using multiple text bubbles.

Teneo Web Chat - Bubbles

This can be achieved by including an output parameter called outputTextSegmentIndexes. This output parameter should contain a list of index pairs, to indicate where the output text can be split into separate bubbles. The value of the outputTextSegmentIndexes should be structured like this (linebreaks are added for readability):

json

1[
2	[startIndexOfFirstBubble,endIndexOfFirstBubble],
3    [startIndexOfSecondBubble,endIndexOfSecondBubble],
4    ...
5]
6

For the screenshot above, the following values were used:

Output Text	outputTextSegmentIndexes	Bubbles
This should appear in the first bubble. This appears in the middle. And this in the last bubble.	[[0, 41], [41, 72], [72, 100]]	This should appear in the first bubble.
		This appears in the middle.
		And this in the last bubble.

Upload Message

It simplifies file upload to 3rd party services, resembling popular messaging apps. Note that the actual file upload process is service-specific and not part of TWC's interface. TWC emphasizes smooth integration with 3rd party file upload functionality.

to display an empty upload panel, use the following:

javascript

1
2TeneoWebChat.call('show_upload_panel')
3
4

To display a pre-populated upload panel, pass the desired content as a parameter, like this:

javascript

1
2TeneoWebChat.call('show_upload_panel', content)
3
4

For detailed technical documentation, please consult our GitHub doc section, accessible through this link.

Upload panel

TTS ASR Capabilities.

Text-to-Speech (TTS) and Automatic Speech Recognition (ASR) are incorporated as a visual element into Teneo Web Chat (TWC) enabling users to utilize their microphone for transcribing interactions with our chatbot, leveraging the capabilities of the WebspeechAPI. This functionality includes a designated button that initiates or halts the transcription process. Keep the button pressed, the transcription service is activated , lift to deactivate, converting the user's spoken words into text. ASR-TTS

Post-processing script

There are different ways to generate the value of outputTextSegmentIndexes. The Groovy script below is a global post-processing script that looks for two consecutive pipe symbols || in an output text, uses those to generate the value for outputTextSegmentIndexes, removes the pipe symbols from the answer text, and adds the outputTextSegmentIndexes output parameter.

groovy

1def outputTextSegmentIndexes = []
2def outputTextSegments = _.getOutputText().split(/\|\|/)
3if (outputTextSegments.size() > 1) {
4	def startIndex = 0
5	def cleanedOutputText = ""
6
7	outputTextSegments.each { textSegment ->
8		def endIndex = startIndex + textSegment.size()
9		if (textSegment) {
10    			outputTextSegmentIndexes << [startIndex, endIndex]
11		}
12		startIndex = endIndex
13		cleanedOutputText += textSegment
14	}
15	_.setOutputText(cleanedOutputText)
16}
17
18if (outputTextSegmentIndexes) {
19	_.putOutputParameter("outputTextSegmentIndexes", "${outputTextSegmentIndexes}")
20}
21

To use the script, proceed as follows:

Copy the script above.
In Teneo Studio, open the 'SOLUTION' tab in the solution's window (if you're not there already).
Select 'Globals' in the purple bar on the left-hand side, and then select 'Scripts'.
Select 'Post-processing' and choose 'Edit'.
Paste the script above.
Click 'Save'.

Once added, whenever you add || to an answer text in Teneo Studio, the script will add the output parameter 'outputTextSegmentIndexes' with the proper index values and Teneo Web Chat will divide the text into multiple bubbles.

Note that this script works for both Teneo Web Chat and Microsoft Bot Framework. If this script was already added to post processing, you don't need to add it again.

Javascript API

The functionality provided by Teneo Web Chat can be extended and modified using the Teneo Web Chat JavaScript API. This API allows developers to create extensions that can trigger events in the Teneo Web Chat widget, or subscribe to events that may occur in the chat widget. This lets developers change or extend its behavior in ways that are not provided by the standard configuration.

Extensions can be created using standard JavaScript, without needing to modify the source code of Teneo Web Chat. Full specification of the API can be found here: Teneo Web Chat JavaScript API.

Engine input parameters

Channel

In addition to the input entered by the user, requests to the Teneo Engine also contain an input parameter channel with value teneo-webchat. This allows you to change the behavior of your bot, depending on the channel used. For information on how to retrieve the value of an input parameter in Teneo Studio, see Store input parameters in the 'Build your bot' section.

By default, the Teneo Engine includes CORS headers in the responses to browser requests coming from any domain. This means any site can add the webchat UI and interact with a Teneo Engine. If you want to restrict your solution to only include CORS headers for specific domains, you can add a file called tieapi_cors_origins.txt to the Teneo Resource Manager in the views folder. The file should contain the list of allowed origin domains (one domain per line: domains should include port numbers if applicable).

Teneo Web Chat

Core features

Setting up Teneo Web Chat

Giving Teneo Web Chat a try

Adding Teneo Web Chat to your site

Embedding Teneo Web Chat using an iFrame

Configuration settings

Message types

Image

Videos

Audio

Buttons

Input parameters

Quick replies

Clickable list

Link buttons

Tables

Forms

Cards

Carousel message

Modal message

Link Preview message

System message

Combo message

Rating Message.

Splitting answers into 'bubbles'

Upload Message

TTS ASR Capabilities.

Post-processing script

Javascript API

Engine input parameters

Channel

Cross-Origin Resource Sharing (CORS)