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:

TeneoWebChat.version()

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:

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!'})

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:

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)

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
• Set ASR icon
• Reset ASR icon
• Hide ASR button
• Show ASR button
• Enable ASR button
• Disable ASR button
• ASR active
• ASR inactive
• Set TTS icon
• Reset TTS icon
• Hide TTS button
• Show TTS button
• Enable TTS button
• Disable TTS button
• TTS active
• TTS inactive
• Set MS Voice for TTS

Maximize

Maximizes the Teneo Web Chat window.

TeneoWebChat.call('maximize')

Minimize

Minimizes the Teneo Web Chat window.

TeneoWebChat.call('minimize')

Send input

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

TeneoWebChat.call('send_input', message)

Message payload

Message payload example

{
    "text": "Hello!",
    "parameters": {
        "countryCode": "NL"
    },
    "silent": false
}

End session

Sends an end session request to Teneo.

TeneoWebChat.call('end_session')

Clear chat history

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

TeneoWebChat.call('clear_chat_history')

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.

TeneoWebChat.call('reset')

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.

TeneoWebChat.call('add_message', message)

Message payload

Message payload example

{
    "author": "bot",
    "type": "text",
    "data": {
        "avatarUrl": "https://url.to/image/bot.png",
        "dateline": "Sara - 12:46",
        "text": "Hello world!"
    }
}

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.

TeneoWebChat.call('show_typing_indicator', indicator)

Indicator payload

Indicator payload example

{
    "author": "agent",
    "data": {
        "avatarUrl": "https://url.to/image/agent.png",
        "dateline": "Agent",
    }
}

Hide typing indicator

Hides the typing indicator for a particular author.

TeneoWebChat.call('hide_typing_indicator', indicator)

Indicator payload

Indicator payload example

{
    "author": "agent"
}

Set chat window title

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

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

Set chat window icon

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

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

Reset chat window icon

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

Set launch icon

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

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

Reset launch icon

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

Set send icon

Updates the send icon shown next to the input field.

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

Reset send icon

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

Disable user input

Disables the user input field.

TeneoWebChat.call('disable_user_input')

Enable user input

Enables the user input field.

TeneoWebChat.call('enable_user_input')

Set engine URL

Allows you to set a new Teneo engine endpoint url.

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

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.

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

Show callout

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>!')

Hide callout

Hides the callout message.

TeneoWebChat.call('hide_callout')

Set upload icon

Updates the icon for the upload button.

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

Reset upload icon

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

TeneoWebChat.call('reset_upload_icon')

Show upload button

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

TeneoWebChat.call('show_upload_button')

Hide upload button

Hides the upload button (when visible).

TeneoWebChat.call('hide_upload_button')

Enable upload button

Enables the upload button (when visible and disabled).

TeneoWebChat.call('enable_upload_button')

Disable upload button

Disables the upload button (when visible and enabled).

TeneoWebChat.call('disable_upload_button')

Set ASR icon

Updates the icon for the ASR button.

TeneoWebChat.call('set_asr_icon', 'https://url.to/icon.svg')

Reset ASR icon

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

TeneoWebChat.call('reset_asr_icon')

Show ASR button

Shows an ASR button to the left of the input box. When clicked, the On asr button clicked callback is called.

TeneoWebChat.call('show_asr_button')

Hide ASR button

Hides the ASR button (when visible).

TeneoWebChat.call('hide_asr_button')

Enable ASR button

Enables the ASR button (when visible and disabled).

TeneoWebChat.call('enable_asr_button')

Disable ASR button

Disables the ASR button (when visible and enabled).

TeneoWebChat.call('disable_asr_button')

ASR active

Activates the ASR recording. Once clicked, the speech recognition begins. It will turn inactive when the recording is finished.

TeneoWebChat.call('asr_active')

ASR inactive

Deactivates the ASR recording, stopping whatever recording is in progress and cancelling the speech recogition process.

TeneoWebChat.call('asr_inactive')

Set TTS icon

Updates the icon for the TTS button.

TeneoWebChat.call('set_tts_icon', 'https://url.to/icon.svg')

Reset TTS icon

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

TeneoWebChat.call('reset_tts_icon')

Hide TTS button

Hides the TTS button (when visible).

TeneoWebChat.call('hide_tts_button')

Show TTS button

Shows an TTS button to the left of the input box. When clicked, the On tts button clicked callback is called.

TeneoWebChat.call('show_tts_button')

Enable TTS button

Enables the TTS button (when visible and disabled).

TeneoWebChat.call('enable_tts_button')

Disable TTS button

Disables the TTS button (when visible and enabled).

TeneoWebChat.call('disable_tts_button')

TTS active

Activates TTS reading of incoming messages. Once active, every incoming message will be read out loud until TTS is deactivated.

TeneoWebChat.call('tts_active')

TTS inactive

Deactivates the TTS reading of incoming messages.

TeneoWebChat.call('tts_inactive')

Set MS Voice for TTS

Allows you to set the voice you want to use for the TTS functionality. Only applicable if using Microsoft Cognitive Services for TTS. List of voices can be found here.

TeneoWebChat.call('set_ms_voice', 'en-US-AriaNeural' )

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.

TeneoWebChat.get('state')

Response object

Get chat history

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

TeneoWebChat.get('chat_history')

Get engine URL

Returns an object containing the URL of the Teneo Engine.

TeneoWebChat.get('engine_url')

Response object

Get locale

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

TeneoWebChat.get('locale')

Response object

Get storage

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

TeneoWebChat.get('storage')

Get MS Voice

Returns the name of the voice used for TTS from the Microsoft Cognitive Services.

TeneoWebChat.get('storage')

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
• On ASR 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

function onReady() {
  // Teneo Web Chat is ready
  console.log("Teneo Web Chat is ready")
}

TeneoWebChat.on('ready', onReady)

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

function onOpenButtonClicked(payload) {
    // handle open button clicked event
    console.log("Open button clicked")
}

TeneoWebChat.on('open_button_clicked', onOpenButtonClicked)

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

function onMinimizeButtonClicked(payload) {
    // handle minimize button clicked event
    console.log("Minimize button clicked")
}

TeneoWebChat.on('minimize_button_clicked', onMinimizeButtonClicked)

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

function onCloseButtonClicked(payload) {
    // handle close button clicked event
    console.log("Close button clicked")
}

TeneoWebChat.on('close_button_clicked', onCloseButtonClicked)

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

function onVisibilityChanged(payload) {
  switch (payload.visibility) {
    case 'maximized':
      break
    case 'minimized':
      break
  }
}

TeneoWebChat.on('visibility_changed', onVisibilityChanged)

On reset

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

Payload

function onReset(payload) {
    // handle close button clicked event
    console.log("Chat window was reset")
}

TeneoWebChat.on('reset', onReset)

On user typing

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

Payload

Example

function onUserTyping(payload) {
    // handle user typing event
    const text = payload.text
    console.log(text)
}

TeneoWebChat.on('user_typing', onUserTyping)

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

function onInputSubmitted(payload) {
    // handle input submitted event
    let text = payload.text
    console.log(text)
}

TeneoWebChat.on('input_submitted', onInputSubmitted)

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

function onSendButtonClicked(payload) {
    // handle send button clicked event
    console.log("Send button clicked")
}

TeneoWebChat.on('send_button_clicked', onSendButtonClicked)

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

function onMessageButtonClicked(payload) {
    // handle message button clicked event
    var button = payload.button
    console.log("Clicked button details:", button)
}

TeneoWebChat.on('message_button_clicked', onMessageButtonClicked)

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

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)

On engine request

Called before a request is sent to the engine.

Payload

Example

function onEngineRequest(payload) {
    // handle onEngineRequest event
    var requestDetails = payload.requestDetails
    if (requestDetails.text) {
        console.log(requestDetails.text)
    }
}

TeneoWebChat.on('engine_request', onEngineRequest)

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

function onEngineResponse(payload) {
    // handle engine response event
    var response = payload.responseDetails
    console.log("Answer text", response.output.text)
}

TeneoWebChat.on('engine_response', onEngineResponse)

On new message

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

Payload

Example

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)

On upload button clicked

Called when the Upload button is clicked.

function onUploadButtonClicked() {
    // handle upload button functionality
    console.log("Upload button clicked!")
}

TeneoWebChat.on('upload_button_clicked', onUploadButtonClicked)

On ASR button clicked

Called when the ASR button is clicked. Bear in mind that if a function is registered to handle the click, the native functionality using Microsoft´s Cognitive services will not be called. Active status and styling must also be applied by the handling extension.

function onASRButtonClicked() {
    // handle ASR button functionality
    console.log("ASR button clicked!")
}

TeneoWebChat.on('asr_button_clicked', onASRButtonClicked)

On TTS button clicked

Called when the TTS button is clicked. Bear in mind that if a function is registered to handle the click, the native functionality using Microsoft´s Cognitive services will not be called. Active status and styling must also be applied by the handling extension.

function onTTSButtonClicked() {
    // handle TTS button functionality
    console.log("TTS button clicked!")
}

TeneoWebChat.on('tts_button_clicked', onTTSButtonClicked)

Examples

Open the chat window using a button

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

Open the chat window after 30 seconds

setTimeout(function() {
    TeneoWebChat.call('maximize')
}, 30000)

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.

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)

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.

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);

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.

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)

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:

// 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);