Teneo Web Chat JavaScript API

About the API

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.

Getting started

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:

1TeneoWebChat.version()
2

The TeneoWebChat

object comes with the following functions:

• call
  - allows you to invoke methods
• get
  - makes it possible to fetch data
• on
  - registers a callback function for a specific event
• off
  - removes a callback registered by on

The usage of these functions is based on passing the correct arguments in the following pattern:

1TeneoWebChat.function ('method' , 'data' )
2

For example, if you would like to send an input 'Hello world!' to Teneo, this is what it would look like:

Handled state object

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 behavior of the callback.

Object details

• Key - handled
• Type - boolean
• Default value - false
• Description - If set to true, tells Teneo Web Chat that your custom function handles the callback's behavior and Teneo Web Chat should not execute the default behavior after the callback has been executed

For example:

1function askForConfirmationBeforeClose(payload) {
2	// get the handledState object
3	const handledState = payload.handledState
4
5    // prevent chat window from being closed
6    handledState.handled = true
7
8	// functionality to ask for confirmation before we close the window
9    // for example by displaying a modal message
10    TeneoWebChat.call('add_message', myModalMessage)
11}
12
13TeneoWebChat.on('close_button_clicked', askForConfirmationBeforeClose)
14

Methods

To trigger Teneo Web Chat events, you can use the following methods:

• Maximize
• Minimize
• Send input
• End session
• Clear chat history
• Reset
• Add message
• Show typing indicator
• Hide typing indicator
• Set chat window title
• Set chat window icon
• Reset chat window icon
• Set launch icon
• Reset launch icon
• Set send icon
• Reset send icon
• Disable user input
• Enable user input
• Set engine URL
• Set locale
• Show callout
• Hide callout
• Set upload icon
• Reset upload icon
• Show upload button
• Hide upload button
• Disable upload button
• Enable upload button

Maximize

Maximizes the Teneo Web Chat window.

1TeneoWebChat.call('maximize')
2

Minimize

Minimizes the Teneo Web Chat window.

1TeneoWebChat.call('minimize')
2

Send input

Sends a request to Teneo. A new message with the input text will be appended to the message history.

1TeneoWebChat.call('send_input', message)
2

Message payload

Message payload example

1{
2    "text": "Hello!",
3    "parameters": {
4        "countryCode": "NL"
5    },
6    "silent": false
7}
8

End session

Sends an end session request to Teneo.

1TeneoWebChat.call('end_session')
2

Clear chat history

Clears the message history that is shown in the Teneo Web Chat window.

1TeneoWebChat.call('clear_chat_history')
2

Reset

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.

1TeneoWebChat.call('reset')
2

Add message

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.

1TeneoWebChat.call('add_message', message)
2

Message payload

For other message types, see the Message types specifications of Teneo Web Chat.

Message payload example

1{
2    "author": "bot",
3    "type": "text",
4    "data": {
5    	"avatarUrl": "https://url.to/image/bot.png",
6    	"dateline": "Sara - 12:46",
7        "text": "Hello world!"
8    }
9}
10

Show typing indicator

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.

1TeneoWebChat.call('show_typing_indicator', indicator)
2

Indicator payload

Indicator payload example

1{
2    "author": "agent",
3    "data": {
4    	"avatarUrl": "https://url.to/image/agent.png",
5    	"dateline": "Agent",
6    }
7}
8

Hide typing indicator

Hides the typing indicator for a particular author.

1TeneoWebChat.call('hide_typing_indicator', indicator)
2

Indicator payload

Indicator payload example

1{
2    "author": "agent"
3}
4

Set chat window title

Updates the title shown in the header of the Teneo Web Chat window.

1TeneoWebChat.call('set_chat_window_title','New title')
2

Set chat window icon

Updates the icon shown in the header of the Teneo Web Chat window.

1TeneoWebChat.call('set_chat_window_icon','https://url.to//icon.svg')
2

Reset chat window icon

Resets the icon shown in the header of the Teneo Web Chat window to the default icon.

1TeneoWebChat.call('reset_chat_window_icon')
2

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

Set launch icon

Updates the icon shown in the Teneo Web Chat launch button.

1TeneoWebChat.call('set_launch_icon','https://url.to//icon.svg')
2

Reset launch icon

Resets the icon shown in the Teneo Web Chat launch button to the default icon.

1TeneoWebChat.call('reset_launch_icon')
2

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

Set send icon

Updates the send icon shown next to the input field.

1TeneoWebChat.call('set_send_icon','https://url.to//icon.svg')
2

Reset send icon

Resets the send icon shown shown next to the input field.

1TeneoWebChat.call('reset_send_icon')
2

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

Disable user input

Disables the user input field.

1TeneoWebChat.call('disable_user_input')
2

Enable user input

Enables the user input field.

1TeneoWebChat.call('enable_user_input')
2

Set engine URL

Allows you to set a new Teneo engine endpoint url.

1TeneoWebChat.call('set_engine_url','https://url.to/a/teneo/engine')
2

Set locale

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.

1TeneoWebChat.call('set_locale','zh-TW')
2

Show callout

Shows a callout message above the launch button. Clicking the callout message will open the chat window.

1TeneoWebChat.call('show_callout','👋 Hi there! I am a callout message. Click me to open the <strong>chat window</strong>!')
2

Hide callout

Hides the callout message.

1TeneoWebChat.call('hide_callout')
2

Set upload icon

Updates the icon for the upload button.

1TeneoWebChat.call('set_upload_icon','https://url.to/icon.svg')
2

Reset upload icon

Resets the upload icon to either its initialization url or the default icon.

1TeneoWebChat.call('reset_upload_icon')
2

Show upload button

Shows an upload button next to the input box. When clicked, the On upload button clicked callback is called.

1TeneoWebChat.call('show_upload_button')
2

Hide upload button

Hides the upload button (when visible).

1TeneoWebChat.call('hide_upload_button')
2

Enable upload button

Enables the upload button (when visible and disabled).

1TeneoWebChat.call('enable_upload_button')
2

Disable upload button

Disables the upload button (when visible and enabled).

1TeneoWebChat.call('disable_upload_button')
2

Getters

You can use getters to fetch data from Teneo Web Chat. These are the getters currently supported:

• Get state
• Get message list
• Get engine URL
• Get locale
• Get storage
• Get MS Voice

Get state

Returns an object with the Teneo Web Chat window state.

1TeneoWebChat.get('state')
2

Response object

Get chat history

Returns the chat history as a list of message objects. For message object details, see: Add message.

1TeneoWebChat.get('chat_history')
2

Get engine URL

Returns an object containing the URL of the Teneo Engine.

1TeneoWebChat.get('engine_url')
2

Response object

Get locale

Returns an object containing locale used for labels and text in Teneo Web Chat.

1TeneoWebChat.get('locale')
2

Response object

Get storage

Returns the storage object used to store chat history and session id.

1TeneoWebChat.get('storage')
2

Callbacks

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:

• On ready
• On open button clicked
• On minimize button clicked
• On close button clicked
• On visibility changed
• On reset
• On user typing
• On input submitted
• On send button clicked
• On message button clicked
• On modal button clicked
• On engine request
• On engine response
• On new message
• On upload button clicked

For example, this is the order of the callbacks when a user sends an input and receives a text answer from the bot:

On ready

Teneo Web Chat has finished loading.

Example

1function onReady() {
2  // Teneo Web Chat is ready
3  console.log("Teneo Web Chat is ready")
4}
5
6TeneoWebChat.on('ready', onReady)
7

On open button clicked

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.

Payload

1function onOpenButtonClicked(payload) {
2	// handle open button clicked event
3    console.log("Open button clicked")
4}
5
6TeneoWebChat.on('open_button_clicked', onOpenButtonClicked)
7

On minimize button clicked

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.

Payload

1function onMinimizeButtonClicked(payload) {
2	// handle minimize button clicked event
3    console.log("Minimize button clicked")
4}
5
6TeneoWebChat.on('minimize_button_clicked', onMinimizeButtonClicked)
7

On close button clicked

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.

Payload

1function onCloseButtonClicked(payload) {
2	// handle close button clicked event
3    console.log("Close button clicked")
4}
5
6TeneoWebChat.on('close_button_clicked', onCloseButtonClicked)
7

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.

On visibility changed

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.

Payload

Example

1function onVisibilityChanged(payload) {
2  switch (payload.visibility) {
3    case 'maximized':
4      break
5    case 'minimized':
6      break
7  }
8}
9
10TeneoWebChat.on('visibility_changed', onVisibilityChanged)
11

On reset

Called before the chat window is reset (either using the close button or the reset API).

Payload

1function onReset(payload) {
2	// handle close button clicked event
3    console.log("Chat window was reset")
4}
5
6TeneoWebChat.on('reset', onReset)
7

On user typing

Called when the user is typing a message in the input box. Called approximately once per 250ms.

Payload

Example

1function onUserTyping(payload) {
2    // handle user typing event
3    const text = payload.text
4  	console.log(text)
5}
6
7TeneoWebChat.on('user_typing', onUserTyping)
8

On input submitted

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

Payload

Example

1function onInputSubmitted(payload) {
2    // handle input submitted event
3	let text = payload.text
4  	console.log(text)
5}
6
7TeneoWebChat.on('input_submitted', onInputSubmitted)
8

On send button clicked

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.

Payload

1function onSendButtonClicked(payload) {
2	// handle send button clicked event
3    console.log("Send button clicked")
4}
5
6TeneoWebChat.on('send_button_clicked', onSendButtonClicked)
7

On message button clicked

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.

Payload

Example

1function onMessageButtonClicked(payload) {
2    // handle message button clicked event
3    var button = payload.button
4  	console.log("Clicked button details:", button)
5}
6
7TeneoWebChat.on('message_button_clicked', onMessageButtonClicked)
8

On modal button clicked

Called when the user clicks button in a modal message. This is called before the postback value is (silently) sent to engine.

Payload

Example

1function onModalButtonClicked(payload) {
2    // handle modal button clicked event
3    var button = payload.button
4  	console.log("Clicked modal button details:", button)
5}
6
7TeneoWebChat.on('modal_button_clicked', onModalButtonClicked)
8

On engine request

Called before a request is sent to the engine.

Payload

Example

1function onEngineRequest(payload) {
2    // handle onEngineRequest event
3    var requestDetails = payload.requestDetails
4    if (requestDetails.text) {
5    	console.log(requestDetails.text)
6    }
7}
8
9TeneoWebChat.on('engine_request', onEngineRequest)
10

On engine response

Called when a response from engine was received, but before the results (messages, components) are added to the message list.

Payload

Example

1function onEngineResponse(payload) {
2	// handle engine response event
3    var response = payload.responseDetails
4	console.log("Answer text", response.output.text)
5}
6
7TeneoWebChat.on('engine_response', onEngineResponse)
8

On new message

Called when both an incoming and outgoing message is added to the message list.

Payload

Example

1function onNewMessage(payload) {
2  const message = payload.message
3  switch (message.type) {
4    case 'text':
5      // handle new text message event
6      console.log(message.data.text)
7      break
8
9    case 'card':
10      // handle new card message event
11      console.log(message.data.title)
12      break
13
14	default:
15      break
16  }
17}
18
19TeneoWebChat.on('new_message', onNewMessage)
20

On upload button clicked

Called when the Upload button is clicked.

1function onUploadButtonClicked() {
2	// handle upload button functionality
3	console.log("Upload button clicked!")
4}
5
6TeneoWebChat.on('upload_button_clicked', onUploadButtonClicked)
7

Examples

Open the chat window using a button

1var chatButtonOpen = document.getElementById('chat-btn-open')
2chatButtonOpen.addEventListener('click', function() {
3  TeneoWebChat.call('maximize')
4})
5

Open the chat window after 30 seconds

1setTimeout(function() {
2    TeneoWebChat.call('maximize')
3}, 30000)
4

Modify a message before it is added to the message list

Let's say you want to replace all occurrences of the word 'love' in any text message with the ❤️ emoji.

1function handleNewMessage(payload) {
2  message = payload.message
3  if (message.type == "text" && message.data.text) {
4    message.data.text = message.data.text.replace(/love/g,'❤️')
5  }
6}
7TeneoWebChat.on('new_message', handleNewMessage)
8

Manage window state between pages

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.

1function rememberVisibilityState(payload) {
2  sessionStorage.setItem('twc_last_state', payload.visibility);
3}
4
5function restoreWindowState() {
6  var lastState = sessionStorage.getItem('twc_last_state');
7  if (lastState === 'maximized') {
8    TeneoWebChat.call('maximize');
9  } else {
10    TeneoWebChat.call('minimized');
11  }    
12}
13
14TeneoWebChat.on('visibility_changed', rememberVisibilityState);
15TeneoWebChat.on('ready', restoreWindowState);
16

Add a system message

Sometimes you may wish to add a message to the message history that is not from the bot or the user.

1var systemMessage = {
2    'type': 'system',
3    'data': {
4        'text': 'You will be handed over to an agent. You are number <strong>4</strong> in the queue.'
5    }
6}
7
8TeneoWebChat.call('add_message', systemMessage)
9

Delay bot response and show typing indicator

You can use the API to delay the bot's response and show a typing indicator during the delay time:

1// pick a random number between two values
2function randomIntFromInterval(min, max) {
3    return Math.floor(Math.random() * (max - min + 1) + min);
4}
5
6function botTypingIndicator(payload) {
7    const message = payload.message
8
9    // only proceed if the message that is added to the message list is from the bot
10    if (message.author === "bot") {
11
12    	// immediately show a typing indicator, but only for text messages
13        if (message.type === "text") {
14        	// show a typing indicator for author bot
15            TeneoWebChat.call('show_typing_indicator', {"author":"bot"}) 
16        }
17
18        // add a delay between 600 and 1000 milliseconds before messages are shown
19        return new Promise(function(resolve) {
20            setTimeout(function() {
21                resolve(payload);
22            }, randomIntFromInterval(600,1000));
23        });
24    }
25}
26
27TeneoWebChat.on('new_message', botTypingIndicator);
28