The Teneo Web Chat JavaScript API allows you to interact with the Teneo Web Chat widget embedded on your site. This lets you change or extend its behavior in ways that are not provided by the standard configuration.
This page focuses on developers and requires a basic knowledge of JavaScript. If you have any questions, don't hesitate to add a new topic on the Teneo Developers Forum.
The API is accessed through the TeneoWebChat
object. It is being initialized as part of the code that is used to install the Teneo Web Chat widget on your site. If you haven't yet added the code to your (development) site, follow the instructions here.
The API is available for Teneo Web Chat v3.0.0 or higher. If you are using an older version of Teneo Web Chat and the API presented here doesn't work, you should update to the latest version. As of version 3.0.0 you can check the current version by calling the version
function:
TeneoWebChat.version()
The TeneoWebChat
object comes with the following functions:
call
- allows you to invoke methodsget
- makes it possible to fetch dataon
- registers a callback function for a specific eventoff
- removes a callback registered by on
The usage of these functions is based on passing the correct arguments in the following pattern:
TeneoWebChat.function('method', 'data')
For example, if you would like to send an input 'Hello world!' to Teneo, this is what it would look like:
TeneoWebChat.call('send_input', {'text':'Hello world!'})
The payload of the on
callbacks may contain an object called handledState
. When this object is available, you can prevent Teneo Web Chat from executing the default behavour of the callback.
Key | Type | Description |
---|---|---|
handled | boolean | Default value: false. If set to true, tells Teneo Web Chat that your custom function handles the callback's behavior and Teneo Web Chat should not exectute the default behaviour after the callback has been executed. |
For example:
function askForConfirmationBeforeClose(payload) {
// get the handledState object
const handledState = payload.handledState
// prevent chat window from being closed
handledState.handled = true
// functionality to ask for confirmation before we close the window
// for example by displaying a modal message
TeneoWebChat.call('add_message', myModalMessage)
}
TeneoWebChat.on('close_button_clicked', askForConfirmationBeforeClose)
To trigger Teneo Web Chat events, you can use the following methods:
Maximizes the Teneo Web Chat window.
TeneoWebChat.call('maximize')
Minimizes the Teneo Web Chat window.
TeneoWebChat.call('minimize')
Sends a request to Teneo. A new message with the input text will be appended to the message history.
TeneoWebChat.call('send_input', message)
Param | Type | Description |
---|---|---|
text | string | Mandatory. The input to send to engine. To send an empty input, use an empty string as value. |
parameters | object | Optional. Additional input parameters to include in the request |
silent | boolean | Optional. If true, the input will be sent without adding a new message bubble to the message history. Defaults to false. |
{
"text": "Hello!",
"parameters": {
"countryCode": "NL"
},
"silent": false
}
Sends an end session request to Teneo.
TeneoWebChat.call('end_session')
Clears the message history that is shown in the Teneo Web Chat window.
TeneoWebChat.call('clear_chat_history')
Resets Teneo Web Chat. This means the chat history will be deleted, an end session request is sent to engine and the chat window is minimized.
TeneoWebChat.call('reset')
Adds a message to the message history shown in the chat window. Note: this only adds a message to the list, it does not send an input to Teneo. To send a request to Teneo, use Send input.
TeneoWebChat.call('add_message', message)
Param | Type | Description |
---|---|---|
type | string | Required. The type of message. Valid values:text audio buttons card clickablelist combo filevideo image quickreply system vimeovideo youtubevideo |
author | text | Optional. Message author type. Only needed for messages of type 'text'. Valid values:agent bot user |
data | object | Required. The message data. For messages of type 'text', the valid keys are:text - The message text.dateline - Optional dateline shown above the text bubble.avatarUrl - Optional URL to an avater image that should be shown next to the text bubble.For other message types, see the Message types specifications of Teneo Web Chat. |
{
"author": "bot",
"type": "text",
"data": {
"avatarUrl": "https://url.to/image/bot.png",
"dateline": "Sara - 12:46",
"text": "Hello world!"
}
}
Shows a typing indicator bubble for a particular author in the message history. If the typing indicator is shown and a new messsage with the same author type is added, the typing indicator will be removed. To explicitly remove the typing indicator, see Hide typing indicator.
TeneoWebChat.call('show_typing_indicator', indicator)
Param | Type | Description |
---|---|---|
author | text | Indicator author type. Required. Valid values:agent bot user |
data | object | Additional information to be shown alongside the typing indicator. Valid keys are:dateline - Optional dateline shown above the typing bubble.avatarUrl - Optional URL to an avater image that should be shown next to the typing indicator. |
{
"author": "agent",
"data": {
"avatarUrl": "https://url.to/image/agent.png",
"dateline": "Agent",
}
}
Hides the typing indicator for a particular author.
TeneoWebChat.call('hide_typing_indicator', indicator)
Param | Type | Description |
---|---|---|
author | text | Indicator author type. Required. Valid values:agent bot user |
{
"author": "agent"
}
Updates the title shown in the header of the Teneo Web Chat window.
TeneoWebChat.call('set_chat_window_title','New title')
Updates the icon shown in the header of the Teneo Web Chat window.
TeneoWebChat.call('set_chat_window_icon','https://url.to//icon.svg')
Resets the icon shown in the header of the Teneo Web Chat window to the default icon.
TeneoWebChat.call('reset_chat_window_icon')
Note: this will reset the icon to the default icon that comes with Teneo Web Chat. If you have specified a custom icon using the 'titleIconUrl' configuration setting, you should instead use the Set chat window icon api and provide the url used for 'titleIconUrl'.
Updates the icon shown in the Teneo Web Chat launch button.
TeneoWebChat.call('set_launch_icon','https://url.to//icon.svg')
Resets the icon shown in the Teneo Web Chat launch button to the default icon.
TeneoWebChat.call('reset_launch_icon')
Note: this will reset the icon to the default icon that comes with Teneo Web Chat. If you have specified a custom icon using the 'launchIconUrl' configuration setting, you should instead use the Set launch icon api and provide the url used for 'launchIconUrl'.
Updates the send icon shown next to the input field.
TeneoWebChat.call('set_send_icon','https://url.to//icon.svg')
Resets the send icon shown shown next to the input field.
TeneoWebChat.call('reset_send_icon')
Note: this will reset the icon to the default icon that comes with Teneo Web Chat. If you have specified a custom icon using the 'sendIconUrl' configuration setting, you should instead use the Set send icon api and provide the url used for 'sendIconUrl'.
Disables the user input field.
TeneoWebChat.call('disable_user_input')
Enables the user input field.
TeneoWebChat.call('enable_user_input')
Allows you to set a new Teneo engine endpoint url.
TeneoWebChat.call('set_engine_url','https://url.to/a/teneo/engine')
Allows you to change the locale used for labels and text, like the placeholder text in the input box. See the locale configuration setting for a list of supported locales.
TeneoWebChat.call('set_locale','zh-TW')
Shows a callout message above the launch button. Clicking the callout message will open the chat window.
TeneoWebChat.call('show_callout','👋 Hi there! I am a callout message. Click me to open the <strong>chat window</strong>!')
Hides the callout message.
TeneoWebChat.call('hide_callout')
Updates the icon for the upload button.
TeneoWebChat.call('set_upload_icon','https://url.to//icon.svg')
Resets the upload icon to either its initialization url or the default icon.
TeneoWebChat.call('reset_upload_icon')
Shows an upload button next to the input box. When clicked, the On upload button clicked callback is called.
TeneoWebChat.call('show_upload_button')
Hides the upload button (when visible).
TeneoWebChat.call('hide_upload_button')
Disables the upload button (when visible and enabled).
TeneoWebChat.call('disable_upload_button')
Enables the upload button (when visible and disabled).
TeneoWebChat.call('enable_upload_button')
You can use getters to fetch data from Teneo Web Chat. These are the getters currently supported:
Returns an object with the Teneo Web Chat window state.
TeneoWebChat.get('state')
Param | Type | Description |
---|---|---|
visibility | string | The Teneo Web Chat window's visibility. Possible values:maximized minimized |
Returns the chat history as a list of message objects. For message object details, see: Add message.
TeneoWebChat.get('chat_history')
Returns an object containing the URL of the Teneo Engine.
TeneoWebChat.get('engine_url')
Param | Type | Description |
---|---|---|
engineUrl | string | The URL of the Teneo Engine. |
Returns an object containing locale used for labels and text in Teneo Web Chat.
TeneoWebChat.get('locale')
Param | Type | Description |
---|---|---|
locale | string | The locale as set in configuration options or using the api. |
Returns the storage object used to store chat history and session id.
TeneoWebChat.get('storage')
Callbacks allow you to react to the events triggered by Teneo Web Chat. You can use them to modify the behavior of Teneo Web Chat when certain events happen. These are the callbacks currently supported:
For example, this is the order of the callbacks when a user sends an input and receives a text answer from the bot:
User action | Callback |
---|---|
Sends input | On input submitted On new message On engine request |
Receives an answer | On engine response On new message |
Teneo Web Chat has finished loading.
function onReady() {
// Teneo Web Chat is ready
console.log("Teneo Web Chat is ready")
}
TeneoWebChat.on('ready', onReady)
Called when the button to open the chat window is clicked, but before the chat window is actually opened. Note: this event is not called when the window is maximized using the api.
Param | Type | Description |
---|---|---|
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the chat window should not be maximized. |
function onOpenButtonClicked(payload) {
// handle open button clicked event
console.log("Open button clicked")
}
TeneoWebChat.on('open_button_clicked', onOpenButtonClicked)
Called when the button to minimize the chat window is clicked, but before the chat window is actually minimized. Note: this event is not called when the window is minimized using the api.
Param | Type | Description |
---|---|---|
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the chat window should not be minimized. |
function onMinimizeButtonClicked(payload) {
// handle minimize button clicked event
console.log("Minimize button clicked")
}
TeneoWebChat.on('minimize_button_clicked', onMinimizeButtonClicked)
Called when the button to close the chat window is clicked but before the chat window is actually reset. Note: this event is not called when the window is minimized or reset using the api.
Param | Type | Description |
---|---|---|
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the chat window should not be reset. |
function onCloseButtonClicked(payload) {
// handle close button clicked event
console.log("Close button clicked")
}
TeneoWebChat.on('close_button_clicked', onCloseButtonClicked)
By default, the close chat button is not visible in the header. To enable it, the property showCloseButton
with value true
should be passed on when initializing Teneo Web Chat.
Called once the visibility of the Teneo Web Chat window has changed. This applies to both user actions like maximizing or minimizing the window as well as maximizing or minimizing the Teneo Web Chat window through the use of this API.
Param | Type | Description |
---|---|---|
visibility | string | The Teneo Web Chat window's visibility. Possible values: maximized, minimized |
function onVisibilityChanged(payload) {
switch (payload.visibility) {
case 'maximized':
break
case 'minimized':
break
}
}
TeneoWebChat.on('visibility_changed', onVisibilityChanged)
Called before the chat window is reset (either using the close button or the reset api).
Param | Type | Description |
---|---|---|
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the chat window should not be reset. |
function onReset(payload) {
// handle close button clicked event
console.log("Chat window was reset")
}
TeneoWebChat.on('reset', onReset)
Called when the user is typing a message in the input box. Called approx once per 250ms.
Param | Type | Description |
---|---|---|
text | string | The text of the message typed so far. |
function onUserTyping(payload) {
// handle user typing event
const text = payload.text
console.log(text)
}
TeneoWebChat.on('user_typing', onUserTyping)
Called when the user submits an input by submitting it from the input box. This is called before the message is added to the message list and before the message is sent to engine.
Param | Type | Description |
---|---|---|
text | string | The text of the message. |
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the input will not be submitted. |
function onInputSubmitted(payload) {
// handle input submitted event
let text = payload.text
console.log(text)
}
TeneoWebChat.on('input_submitted', onInputSubmitted)
Called when the button to send an input is clicked, but before the input is actually sent. Note: this event is not called if the user submits an input using the return/enter key.
Param | Type | Description |
---|---|---|
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the input should not be sent. |
function onSendButtonClicked(payload) {
// handle send button clicked event
console.log("Send button clicked")
}
TeneoWebChat.on('send_button_clicked', onSendButtonClicked)
Called when the user clicks a button, quickreply, clickable list or a link button. This is called before the postback value is (silently) sent to engine or the link button's URL is opened.
Param | Type | Description |
---|---|---|
button | object | Details of the clicked button. See button, quickreply, clickable list or link button for details of the clickable items. |
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the postback value will not be sent to engine or, in case of a link button, the url will not be opened. |
function onMessageButtonClicked(payload) {
// handle message button clicked event
var button = payload.button
console.log("Clicked button details:", button)
}
TeneoWebChat.on('message_button_clicked', onMessageButtonClicked)
Called when the user clicks button in a modal message. This is called before the postback value is (silently) sent to engine.
Param | Type | Description |
---|---|---|
button | object | Details of the clicked button. See Modal message for button details. |
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the postback value of the button will not be sent to engine. |
function onModalButtonClicked(payload) {
// handle modal button clicked event
var button = payload.button
console.log("Clicked modal button details:", button)
}
TeneoWebChat.on('modal_button_clicked', onModalButtonClicked)
Called before a request is sent to engine.
Param | Type | Description |
---|---|---|
requestDetails | object | Object containing the details to be sent to engine. Contains the following keys:channel - Channel parameter. Default value: 'teneo-webchat' text - The user input. [extra parameters] - Additional parameters included in the request. |
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the request will not be sent to engine. |
function onEngineRequest(payload) {
// handle onEngineRequest event
var requestDetails = payload.requestDetails
if (requestDetails.text) {
console.log(requestDetails.text)
}
}
TeneoWebChat.on('engine_request', onEngineRequest)
Called when a response from engine was received, but before the results (messages, components) are added to the message list.
Param | Type | Description |
---|---|---|
responseDetails | object | The response object as returned by Teneo Engine. See Engine Response for details. |
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and the response will not be further processed (and no message will be added to the message list). |
function onEngineResponse(payload) {
// handle engine response event
var response = payload.responseDetails
console.log("Answer text", response.output.text)
}
TeneoWebChat.on('engine_response', onEngineResponse)
Called when both an incoming and outgoing message is added to the message list.
Param | Type | Description |
---|---|---|
message | object | Contains the details of the message that be added to the message list. See Add message for details. |
handledState | object | Contains key 'handled' with boolean value false. If set to true, tells Teneo Web Chat that your callback function overrides the default behaviour and message will not be added to the message list. |
function onNewMessage(payload) {
const message = payload.message
switch (message.type) {
case 'text':
// handle new text message event
console.log(message.data.text)
break
case 'card':
// handle new card message event
console.log(message.data.title)
break
default:
break
}
}
TeneoWebChat.on('new_message', onNewMessage)
Called when the Upload button is clicked.
function onUploadButtonClicked() {
// handle upload button functionality
console.log("Upload button clicked!")
}
TeneoWebChat.on('upload_button_clicked', onUploadButtonClicked)
var chatButtonOpen = document.getElementById('chat-btn-open')
chatButtonOpen.addEventListener('click', function() {
TeneoWebChat.call('maximize')
})
setTimeout(function() {
TeneoWebChat.call('maximize')
}, 30000)
Let's say you want to replace all occurrences of the word 'love' in any text message with the ❤️ emoji.
function handleNewMessage(payload) {
message = payload.message
if (message.type == "text" && message.data.text) {
message.data.text = message.data.text.replace(/love/g,'❤️')
}
}
TeneoWebChat.on('new_message', handleNewMessage)
By default the Teneo Web Chat window is minimized when a page is loaded. Suppose you would like the web chat window to stay open when the user moves from page to page.
function rememberVisibilityState(payload) {
sessionStorage.setItem('twc_last_state', payload.visibility);
}
function restoreWindowState() {
var lastState = sessionStorage.getItem('twc_last_state');
if (lastState === 'maximized') {
TeneoWebChat.call('maximize');
} else {
TeneoWebChat.call('minimized');
}
}
TeneoWebChat.on('visibility_changed', rememberVisibilityState);
TeneoWebChat.on('ready', restoreWindowState);
Sometimes you may wish to add a message to the message history that is not from the bot or the user.
var systemMessage = {
'type': 'system',
'data': {
'text': 'You will be handed over to an agent. You are number <strong>4</strong> in the queue.'
}
}
TeneoWebChat.call('add_message', systemMessage)
You can use the api to delay the bot's response and show a typing indicator during the delay time:
// pick a random number between two values
function randomIntFromInterval(min, max) {
return Math.floor(Math.random() * (max - min + 1) + min);
}
function botTypingIndicator(payload) {
const message = payload.message
// only proceed if the message that is added to the message list is from the bot
if (message.author === "bot") {
// immediately show a typing indicator, but only for text messages
if (message.type === "text") {
// show a typing indicator for author bot
TeneoWebChat.call('show_typing_indicator', {"author":"bot"})
}
// add a delay between 600 and 1000 milliseconds before messages are shown
return new Promise(function(resolve) {
setTimeout(function() {
resolve(payload);
}, randomIntFromInterval(600,1000));
});
}
}
TeneoWebChat.on('new_message', botTypingIndicator);
Was this page helpful?