Teneo Web Chat is a chat interface that can be embedded in websites. It is built using the Vue.js javascript framework and based on Vue Beautiful Chat by Matteo Merola.
Support for various components like buttons, quick replies, images, videos and cards is built-in and additonal components can easily be added. For more details, see the Teneo Web Chat page on teneo.ai.
Teneo Web Chat works on modern browsers, like Chrome, Edge, Firefox, Opera and Safari.
- Your bot needs to be published and you need to know the engine URL.
- When extending the UI, a basic understanding of Vue.js is required.
To add Teneo Web Chat to your site, proceed as follows:
Download the file main.js from the latest release of teneo-web-chat and add it to your site.
Make the following changes to each page where you want the web chat window to appear. Add the following code before the closing </body> tag to each page where you want the web chat window to appear.
<script type="text/javascript" src="/path/to/webchat/main.js"></script>
<div id="teneo-web-chat"></div>
<script>
window.onload = function () {
if (
window.TeneoWebChat &&
typeof window.TeneoWebChat.initialize === 'function'
) {
var element = document.getElementById('teneo-web-chat')
var teneoEngineUrl = 'https://some.teneo/engine-instance/'
var closeEngineSessionOnExit = 'no'
var headerTitle = ''
var headerIconUrl = ''
var extraEngineInputParams = {}
window.TeneoWebChat.initialize(
element,
headerTitle,
teneoEngineUrl,
closeEngineSessionOnExit,
headerIconUrl,
extraEngineInputParams
);
}
}
</script>
When adding the script to your site, note the following:
- Make sure
/path/to/webchat/main.js
in the first line is replaced with the correct path. - The value of 'teneoEngineUrl' should be updated to match the url of your Teneo Engine.
- The variable 'closeEngineSessionOnExit' specifies if the Teneo Engine session should be ended when the chat UI is closed. It is advised to keep this value as is, to prevent your bot from losing the conversation history when the user closes the chat UI.
- The value of 'headerTitle' specifies the title shown in the header of the chat window. If empty, 'Teneo Web Chat' is used.
- The variable 'headerIconUrl' can be used to specify a custom icon () in the header. It's an image with a size of 24x24 px.
- The variable 'extraEngineInputParams' can be populated with additional input parameters that need to be included in each Teneo Engine request. Note that both the keys and the values in the map should be strings.
If you are looking for a quick way to interact with your bot using Teneo Web Chat but you don't have a website to host it yet, you can deploy it to Heroku. Click the button below to create a new Heroku app that hosts the web chat:
- Give the app a name (lowercase, no spaces)
- In the 'Config Vars' section, add the following:
- TENEO_ENGINE_URL: The engine url.
- CLOSE_TIE_SESSION_ON_EXIT: Optional. If set to true, the Teneo engine session will be killed when the chat UI is closed.
- HEADER_TITLE: Optional. Title shown in the header of the chat window. Defaults to 'Teneo Web Chat' if empty.
- HEADER_ICON_URL: Optional. Can be used to specify a custom icon (with a size of 24x24 pixels) shown in the header.
- Click 'Deploy app'.
When Heroku has finished deploying, click 'View app'. You should now be able to use the web chat ui to talk to your bot.
If you want to run the code locally, for example to extend or update it, proceed as follows:
- Clone the project:
git clone https://github.com/artificialsolutions/teneo-web-chat && cd teneo-web-chat
- Install dependencies:
Note: if you're using Windows and get an error "'NODE_ENV' is not recognized as an internal or external command, operable program or batch file.", you may want to install a module called win-node-env and run npm install again.
npm install
- Create a
.env
file in theteneo-web-chat
folder with following (replace the dummy url with Teneo Engine url of your bot):TENEO_ENGINE_URL="https://some.engine/instance/"
- Start the application:
npm run start:dev
The page should be loaded on http://localhost:9000 now.
To build the bundle, run:
npm run-script build
This will add a file main.js
in the /dist
folder of the project. You can use this main.js
to add to your site.
The following input parameters are included in requests to Engine.
In addition to the input entered by the user, requests to the Teneo Engine also contain an input paramter '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 on the Teneo Developers website.
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.
The following ouput parameters can be included in responses from Engine.
The output parameter teneowebclient
can contain JSON that is used to display attachments, like images, videos, buttons, cards etc. For more details on the compontent that are supported, please see: teneo.ai.
The web chat UI can be extended by adding additional .vue
files in the /src/components/messages/ folder. This file should parse the JSON that is included in an output parameter called teneowebclient
in the engine response. The .vue file should display the data accordingly.
The ImageMessasge.vue extension displays an image below the bot's answer text.
The JSON that should be included in the teneowebclient
output parameter should look as follows:
{
"type": "image",
"url": "https://url.to/an/image.png"
}
Allowed characters for the type name are a-z
and -
where -
cannot be the first character. Based on the type
, the Teneo Web Chat code will look for a matching Vue component in the /src/components/messages/ folder. The assumed file name is derived by taking the type
field, turn it into upper CamelCase
and append Message
to the resulting string. E.g image
becomes ImageMessage
and image-list
would become ImageListMessage
.
Because the type is image
, the web chat code looks for a component in a file called ImageMessage.vue and renders it. This is what the ImageMessage.vue file looks like:
<template>
<div class="image-message">
<img :src="imageUrl" :alt="altText"/>
</div>
</template>
<script>
export default {
name: 'ImageMessage',
props: {
message: {
type: Object,
required: true,
validator: (message) => {
return (
message &&
message.type === 'image' &&
message.data &&
message.data.image_url
);
},
},
},
computed: {
imageUrl() {
return this.message.data.image_url;
},
altText() {
return this.message.data.alt;
},
},
};
</script>
<style>
.image-message {
width: 100%;
margin-right: 40px;
}
.image-message img {
max-width: 100%;
max-height: 200px;
}
</style>
As you can see the file contains three sections:
- template: contains the html used to display the image
- script: contains the javascript to parse the engine json and return the image url
- style: contains the css styles to format the image
A second example extension shows how buttons can be displayed below the bot answer. When clicked a new input with the clicked postback value is sent to the bot.
To display three buttons (Small, Medium and Large), the JSON that needs to be included in the teneowebclient
output parameter can look as follows:
{
"type": "quickreply",
"quick_replies": [
{
"title": "Small",
"postback": "small"
},
{
"title": "Medium",
"postback": "medium"
},
{
"title": "Large",
"postback": "large"
}
]
}
For each button, the title is displayed in the button and the postback value is sent back to engine when the button is clicked.
Because the type is quickreply
, the web chat code looks for a component defined in a file called QuickreplyMessage.vue and renders it.
Again, everything needed to handle this type of extension is contained in the single .vue file. It contains a template section to specify the html, a script section to parse the json but to also handle what happens when a user clicks one of the buttons. It also contains the styles needed to style the buttons.
The Teneo API is available as this.$teneoApi
if you need to send messages back to the bot. Look at the QuickreplyMessage.vue for an example of how to use it.
To add custom extensions, these are the steps to take:
- Define the JSON that specifies the message type and any additional data.
- Create an example flow in Teneo Studio that includes the JSON in the output parameter
teneowebclient
and publish your solution. - Create a .vue file for the message type
- In the view file create the template, scripts and applicable styles
- Test the result by connecting your web chat UI to the the engine with the example flow.
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).