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:
--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.
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.
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.
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
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)
Take the basic webview link accessible in the ON Portal.
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
"
Last updated