Tuul Web Chat Client

Embed your chatbot on a website with our Web Chat Client.

Overview

The Tuul Web Chat Client is a versatile and easy-to-use web component that enables you to seamlessly integrate an Tuul chatbot into your website or mobile app. It can be displayed as a widget or a full conversation window, adaptable to various surfaces on your site and app. This guide will walk you through the steps to embed the chatbot, ensuring a smooth integration with your web application or mobile app through configurations and advanced features.

Embed Script

Embed our chatbot effortlessly on your website with our simple integration options. Choose from the following supported options:

• Embed Script recommended for most integrations

• WordPress Script for older versions of Wordpress

• NPM Package tailored for React applications

Embed Script

The most straightforward way to add our chatbot to your website is by using our embed script. Simply place the following snippet on any page where you want the chatbot to appear:

<on-chat-bot-client
  client-id="YOUR_UNIQUE_CLIENT_ID"
  display-mode="WIDGET"
></on-chat-bot-client>
<script defer src="https://web-chat.services.onplatform.com/v2/static/bot-client.js"></script>

Remember to replace YOUR_UNIQUE_CLIENT_ID with the ID provided by our Customer Success team.

WordPress Script

If you're using an older version of WordPress that doesn't recognize the on-chat-bot-client tag, use this alternative JavaScript approach:

<script>
  (function() {
    var el = document.createElement('on-chat-bot-client');
    el.setAttribute('client-id', 'YOUR_UNIQUE_CLIENT_ID');
    el.setAttribute('display-mode', 'WIDGET');
    document.body.appendChild(el);
  })();
</script>
<script defer src="https://web-chat.services.onplatform.com/v2/static/bot-client.js"></script>

Remember to replace YOUR_UNIQUE_CLIENT_ID with the ID provided by our Customer Success team.

NPM Package

Should you require more control over the web component distribution, or if your application is in React, we also make available our web component as an NPM package.

To install, simply run:

npm i @gameon/web

Then import our module in your javascript bundle:

import '@gameon/web';

React Support

Our NPM package includes a React component that wraps around our web component, allowing direct usage in your React application.

import { OnChatBotClient } from "@gameon/web/react";

function MyComponent(props) {
  return (
    <OnChatBotClient
      clientId="YOUR_UNIQUE_CLIENT_ID"
      displayMode="WIDGET"
    />
  )
}

Configurations

Our web chat client offers a range of configurable options, allowing you to tailor the client's behavior and appearance to suit your website's needs. You can set these options either as attributes passed to the <on-chat-bot-client> HTML tag (using kebab-case) or as properties in JavaScript (using camelCase).

Client Display

The display-mode attribute controls the client's appearance on your site, with three options:

• FULL_SCREEN (default): Displays the chatbot as a regular HTML box element, suitable for any website surface (e.g., a sidebar).

• WIDGET: Shows a persistent button in the bottom right corner, opening a chat window upon interaction.

• WIDGET_WITHOUT_BUTTON: Similar to WIDGET, but without the persistent button. This mode requires you to programmatically open the widget using a custom button or call to action.

<on-chat-bot-client
  client-id="YOUR_UNIQUE_CLIENT_ID"
  display-mode="FULL_SCREEN"
></on-chat-bot-client>

Auto Open

Use should-auto-open and should-auto-open-mobile to have the chat window open automatically upon loading. This is particularly effective in widget mode.

<on-chat-bot-client
  client-id="YOUR_UNIQUE_CLIENT_ID"
  should-auto-open="true"
  should-auto-open-mobile="true"
></on-chat-bot-client>

Auto-opening on mobile may take over the entire screen, which may not be ideal for all sites.

Initial Message

Set an initial-prompt attribute to send a predefined message to the bot as it initializes, guiding the initial user interaction (e.g., starting with a "new arrivals" message):

<on-chat-bot-client
  client-id="YOUR_UNIQUE_CLIENT_ID"
  initial-prompt="new arrivals"
></on-chat-bot-client>

Style Customizations

Personalize the look of your chat client with CSS custom properties. You can add these to a style tag in your HTML or declare them in your external stylesheets.

Example CSS:

on-chat-bot-client {
  --on-chat-widget-right: 100px;
  --on-chat-widget-bottom: 60px;
}

Important CSS custom properties are documented below:

CSS Property	Description
--on-chat-font-family	The font family to use when rendering text within the chat window.
--on-chat-widget-bottom	Sets the space between the widget button and the bottom of the screen, specified as a length.
--on-chat-widget-button-size	Determines the size of the widget button or the maximum height for a custom image button, specified as a length.
--on-chat-widget-right	Sets the space between the widget button and the right side of the screen, specified as a length.
--on-chat-widget-top-offset	Defines the minimum space to be maintained between the top of the screen and the widget, ensuring it doesn't overlap with key elements like a tall navigation bar. Specified as a length.
--on-chat-widget-z-index	The z index of the chat widget and chat window popup. Sets the stacking order, ensuring the chat is always visible above other elements.

Programmatically Open

You can programmatically open the chat window in widget mode using our public methods, accessible via JavaScript.

Programmatically open only has an effect when the client is displayed in widget mode.

Method	Description
close()	Closes the chat window popup.
open()	Opens the chat window popup.
toggle()	Toggles the chat window state; opens it if closed and vice versa.

You will need to query for the Web Chat Client element in javascript, like so:

const client = document.querySelector('on-chat-bot-client');
if (client) {
  client.toggle();
}

Events

The web chat client dispatches several JavaScript events that you can listen for, allowing you to respond to chat interactions.

Event Name	Detail Payload	Description
on-chat-card-link-click	{ cta: string; href: string; label: string; }	Dispatched when a user clicks on one of our link attachment cards. The event payload contains the cta in the card button, the card label and the href URL where the user navigated to.
on-chat-widget-close	null	Dispatched when the chat popup window is closed.
on-chat-widget-open	null	Dispatched when the chat popup window is opened.
on-client-send-message	{ message: string; }	Dispatched when the user sends a message, either by clicking on a quick reply, or by typing on the input box and hitting the send button. The event payload contains the string the user sent to the bot.

Analytics Framework Integration

Use the dispatched events by our Web Chat Client to track user interactions with your preferred analytics tools.

For example, you could integrate with Google Tag Manager using something like the following:

function pushToDataLayer(data) {
  if (window.dataLayer) {
    window.dataLayer.push(data);
  }
}

document.addEventListener('on-chat-widget-open', (e) => {
  pushToDataLayer({
    'event': 'GAevent',
    'eventCategory': 'chat',
    'eventAction': 'popup',
    'eventLabel': 'open_popup'
  });
});

document.addEventListener('on-chat-widget-close', (e) => {
  pushToDataLayer({
    'event': 'GAevent',
    'eventCategory': 'chat',
    'eventAction': 'popup',
    'eventLabel': 'close_popup'
  });
});

document.addEventListener('on-chat-card-link-click', (e) => {
  pushToDataLayer({
    'event': 'GAevent',
    'eventCategory': 'chat',
    'eventAction': 'click_link',
    'eventLabel': e.detail.label
  });
});

document.addEventListener('on-client-send-message', (e) => {
  pushToDataLayer({
    'event': 'GAevent',
    'eventCategory': 'chat',
    'eventAction': 'send_message',
    'eventLabel': e.detail.message
  });
});

Conversational Deep Links

A conversational deep link is a URL or hyperlink that directs users to a specific point within our ON Web Chat UI. These links serve as powerful tools to guide users directly to specific point in the bot.

Website Links

Note: Use the webpage where the bot is embedded as the base URL.

1. Add an ?on_should_auto_open=true URL parameter if you want the chat to open automatically when the page loads.

   • For auto open on mobile, include: ?on_should_auto_open=true&on_should_auto_open_mobile=true

2. Add an &on_initial_prompt=xxx URL parameter with the desired value to feed to the bot, following URL encoding rules.

Standalone Web Chat Links (for mobile apps)

1. Take the basic webview link accessible in the ON Portal.

2. Add an &initial_prompt=xxx URL parameter with the desired text input for the bot. Remember to URL encode the text, replacing special characters with their URL equivalent.

   • For example, if the initial prompt is "Mobile Ticketing Guide," it becomes "mobile%20ticketing%20guide"