Teneo Web Chat

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

Example of the main chat window

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

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 teneo-web-chat.js

Download the file teneo-web-chat.js from the latest release on Github and add it to your site.

Update pages

Add the following code before the closing </body> tag to each page where you want the web chat window to appear.

<!-- Teneo Web Chat start -->
<div id="teneo-web-chat"></div>
<script src="/path/to/teneo-web-chat.js"></script>
<script>
  window.onload = function () {
    if (
      window.TeneoWebChat &&
        typeof window.TeneoWebChat.initialize === 'function'
    ) {
      var element = document.getElementById('teneo-web-chat');
      const teneoProps = {
        'teneoEngineUrl': 'https://some.teneo/engine-instance/',
      }
      window.TeneoWebChat.initialize(element,teneoProps);
    }
  }
</script>
<!-- Teneo Web Chat end -->

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

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

Example of an image in the converstation

Engine JSON

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

{
    "type": "image",
    "image_url": "https://url.to/an/image.png",
    "alt": "This is an image"
}

Videos

Example of a youtube video in the conversation

Teneo Web Chat supports the following video platforms:

  • YouTube
  • Vimeo
  • Mp4 videos
Engine JSON

In general, the JSON to add a video looks like this:

{
    "type": "[videotype]",
    "video_url": "[url]"
}

The type and URL differ depending on the platform that is used to host the video.

YouTube video

{
    "type": "youtubevideo",
    "video_url": "https://www.youtube.com/embed/123456789"
}

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

Vimeo video

{
    "type": "vimeovideo",
    "video_url": "https://player.vimeo.com/video/12345678"
}

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

mp4 video

{
    "type": "filevideo",
    "video_url": "https://url.to/a/video.mp4"
}

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:

{
    "type": "audio",
    "audio_url": "https://url.to/audio.mp3"
}

Buttons

Example of buttons in Teneo Web Chat

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

Engine JSON

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

{
    "type": "buttons",
    "title": "Optional title",
    "button_items": [
        {
            "style": "primary",
            "title": "Primary",
            "postback": "Primary"
        },
        {
            "style": "secondary",
            "title": "Secondary",
            "postback": "Secondary"
        },
        {
            "style": "success",
            "title": "Success",
            "postback": "Success"
        },
        {
            "style": "danger",
            "title": "Danger",
            "postback": "Danger"
        },
        {
            "style": "warning",
            "title": "Warning",
            "postback": "Warning"
        },
        {
            "style": "info",
            "title": "Info",
            "postback": "Info"
        }
    ]
}

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:

...
    {
        "style": "primary",
        "title": "Primary",
        "postback": "Primary",
        "parameters": {
            "button": "primary"
        }
    }
...

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

Example of 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 engine as a user input. Only quick replies in the most recent message can be clicked.

Engine JSON

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

{
    "type": "quickreply",
    "quick_replies": [
        {
            "style": "primary",
            "title": "Primary",
            "postback": "Primary"
        },
        {
            "style": "secondary",
            "title": "Secondary",
            "postback": "Secondary"
        },
        {
            "style": "success",
            "title": "Success",
            "postback": "Success"
        },
        {
            "style": "danger",
            "title": "Danger",
            "postback": "Danger"
        },
        {
            "style": "warning",
            "title": "Warning",
            "postback": "Warning"
        },
        {
            "style": "info",
            "title": "Info",
            "postback": "Info"
        }
    ]
}

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

Clickable list example

The title above the list of clickable items is optional. When clicked, a 'postback' value is sent to 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.

Engine JSON

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

{
    "type": "clickablelist",
    "title": "Optional title",
    "list_items": [
        {
            "title": "One",
            "postback": "One"
        },
        {
            "title": "Two",
            "postback": "Two"
        },
        {
            "title": "Three",
            "postback": "Three"
        },
        {
            "title": "Four",
            "postback": "Four"
        },
        {
            "title": "Five",
            "postback": "Five"
        },
        {
            "title": "Six",
            "postback": "Six"
        }
    ]
}

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

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). Link buttons don't expire, they can be clicked even in older messages. Link buttons don't return a postback value to engine, they do trigger the On message button clicked event however.

Engine JSON

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

{
    "type": "linkbuttons",
    "title": "Optional title",
    "linkbutton_items": [
        {
            "title": "Link 1",
            "url": "https://url.to/a/page",
            "target": "_blank"
        },
        {
            "title": "Link 2",
            "url": "https://url.to/another/page",
            "target": "_blank"
        },
        {
            "title": "Link 3",
            "link": "https://url.to/yet/another/page"
        }
    ]
}

Cards

Card

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

Engine JSON

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

{
    "type": "card",
    "image": {
        "image_url": "https://url.to/an/image.png",
        "alt": "This is an image"
    },
    "title": "This is the title",
    "subtitle": "This is the subtitle",
    "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt."
}

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

Card with buttons:

{
    "type": "card",
    "image": {
        "image_url": "https://url.to/an/image.png",
        "alt": "This is an image"
    },
    "title": "This is the title",
    "subtitle": "This is the subtitle",
    "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.",
    "button_items": [
        {
            "style": "primary",
            "title": "Primary",
            "postback": "Primary"
        },
        {
            "style": "secondary",
            "title": "Secondary",
            "postback": "Secondary"
        },
        {
            "style": "success",
            "title": "Success",
            "postback": "Success"
        }
    ]
}

Card with a clickable list

Card with a clickable list

{
    "type": "card",
    "image": {
        "image_url": "https://url.to/an/image.png",
        "alt": "This is an image"
    },
    "title": "This is the title",
    "subtitle": "This is the subtitle",
    "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt.",
    "list_items": [
        {
            "title": "One",
            "postback": "One"
        },
        {
            "title": "Two",
            "postback": "Two"
        },
        {
            "title": "Three",
            "postback": "Three"
        }
    ]
}

Card with link buttons:

Car with link buttons

{
    "type": "card",
    "image": {
        "image_url": "https://url.to/an/image.png",
        "alt": "This is an image"
    },
    "title": "This is the title",
    "subtitle": "This is the subtitle",
    "text": "Lorem ipsum dolor sit amet, consec tetur adipisicing elit.",
    "linkbutton_items": [
        {
            "title": "Card link",
            "url": "https://url.to/a/page"
        },
        {
            "title": "Another link",
            "url": "https://url.to/another/page",
            "target": "_blank"
        }
    ]
}

Previous versions of Teneo Web Chat supported cards with links by providing a list of link_items. These types of links have been deprecated as of version 3.1.0 and will be removed in the next major release of Teneo Web Chat. If your solution uses cards with link_items, please update them to use linkbutton_items instead.

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

Modal message

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

Engine JSON
{ 
    "type": "modal", 
    "image": { 
        "image_url": "https://url.to/an/image.png",
        "alt": "This is an image"
    }, 
    "title": "This is the title", 
    "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit.", 
    "button_items": [
        { 
            "style": "secondary", 
            "title": "Secondary", 
            "postback": "modal-secondary" 
        }, 
        { 
            "style": "danger", 
            "title": "Danger", 
            "postback": "modal-danger" 
        }
    ] 
}

System message

System message

Engine JSON
{
    "type": "system",
    "text": "This is a system message."
}

Combo message

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

Combo message showing a card, a text message and buttons

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.

Engine JSON

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

{
    "type": "combo",
    "components": [
        {
            "type": "card",
            "image": {
                "image_url": "https://url.to/an/image.png",
                "alt": "This is an image"
            },
            "title": "This is the title",
            "subtitle": "This is the subtitle",
            "text": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt."
        },
        {
            "type": "text",
            "text": "This is an additional speech bubble shown below the card."
        },
        {
            "type": "buttons",
            "title": "Are you sure?",
            "button_items": [
                {
                    "style": "danger",
                    "title": "Yes",
                    "postback": "Yes"
                },
                {
                    "style": "success",
                    "title": "No",
                    "postback": "No"
                }
            ]
        }
    ]
}

Splitting answers into 'bubbles'

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

Example of multiple answer text 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):

[
    [startIndexOfFirstBubble,endIndexOfFirstBubble],
    [startIndexOfSecondBubble,endIndexOfSecondBubble],
    ...
]

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.

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.

def outputTextSegmentIndexes = []
def outputTextSegments = _.getOutputText().split(/\|\|/)
if (outputTextSegments.size() > 1) {
    def startIndex = 0
    def cleanedOutputText = ""

    outputTextSegments.each { textSegment ->
        def endIndex = startIndex + textSegment.size()
        if (textSegment) {
                outputTextSegmentIndexes << [startIndex, endIndex]
        }
        startIndex = endIndex
        cleanedOutputText += textSegment
    }
    _.setOutputText(cleanedOutputText)
}

if (outputTextSegmentIndexes) {
    _.putOutputParameter("outputTextSegmentIndexes", "${outputTextSegmentIndexes}")
}

To use the script, proceed as follows:

  1. Copy the script above.
  2. In Teneo Studio, open the 'SOLUTION' tab in the solution's window (if you're not there already).
  3. Select 'Globals' in the purple bar on the left hand side, and then select 'Scripts'.
  4. Select 'Post-processing' and choose 'Edit'.
  5. Paste the script above.
  6. 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 foud 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.

Extra parameters

An optional map of parameters can be included when Teneo Web Chat is initialized. The keys in this map (and their values) will be included as individual input parameters in all requests to the Teneo Engine.

Cross-Origin Resource Sharing (CORS)

In many cases, the website that is hosting the web chat UI uses a different domain than the domain used by the Teneo Engine. Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to tell a browser to let a web application running at one origin (domain) have permission to access selected resources from a server at a different origin.

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 web chat 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).

Was this page helpful?