Web widget SDK

One of the most common ways to make your bot available to your clients is through a web widget. You can put the bot wherever you want it to live and talk to your customers. In this technical guide, we will guide you through the process of integrating the bot on your website.

Whitelisting

To make sure your bot only works on your website, Chatlayer will whitelist the bot for your domain. Please send your bot ID and the URL of your domain to be whitelisted to Chatlayer.ai Support.

Embedding the web widget on your website

Include the following <div> on your website:

<div id="frameId"></div>

Include this <script> element in the header:

<script>
(function(d) {
var cm = d.createElement('scr' + 'ipt');
cm.type = 'text/javascript';
cm.async = true;
cm.src = 'https://sdk.staging.chatlayer.ai/chatlayer.js';
//This URL should be changed to 'https://sdk.chatlayer.ai/chatlayer.js' for the production version of the SDK.
cm.id = 'chatjs';
var s = d.getElementsByTagName('scr' + 'ipt')[0];
s.parentNode.insertBefore(cm, s);
cm.addEventListener('load', function() {
// Instantiate your Chatlayer class.
var chat = new Chatlayer({
botId: XYZ, //MANDATORY: fill in your botId here. You can find your botId in the URL where you're configuring your chatbot
autoOpen: true,
styles: {
open:
'position: absolute; height: 800px; width: 375px; bottom:80px; right: 0; transition: 0.5s;',
close:
'position: absolute; height: 0px; width: 375px; bottom:80px; right: 0; transition: 0.5s;',
},
});
chat.initialize(document.getElementById('frameId'));
});
})(document);
</script>

This script contains all the mandatory settings to configure your Chatlayer.ai Webwidget SDK.

Default locale

When there is no locale - which is the language of the user - set, the bot will start speaking in the default bot language. You can override this using the following prop.

Prop

Example

locale

fr-fr / nl-nl / en-us

<script>
(function(d) {
var cm = d.createElement('scr' + 'ipt');
cm.type = 'text/javascript';
cm.async = true;
cm.src = 'https://sdk.staging.chatlayer.ai/chatlayer.js';
//This URL should be changed to 'https://sdk.chatlayer.ai/chatlayer.js' for the production version of the SDK.
cm.id = 'chatjs';
var s = d.getElementsByTagName('scr' + 'ipt')[0];
s.parentNode.insertBefore(cm, s);
cm.addEventListener('load', function() {
// Instantiate your Chatlayer class.
var chat = new Chatlayer({
botId: XYZ, //MANDATORY: fill in your botId here. You can find your botId in the URL where you're configuring your chatbot
locale: 'fr-fr'
styles: {
open:
'position: absolute; height: 800px; width: 375px; bottom:80px; right: 0; transition: 0.5s;',
close:
'position: absolute; height: 0px; width: 375px; bottom:80px; right: 0; transition: 0.5s;',
},
});
chat.initialize(document.getElementById('frameId'));
});
})(document);
</script>

Using CSS classnames instead of styles

If you prefer using css to implement advanced custom styling of the Chatlayer.ai web widget, you can use the following setup:

<script>
(function(d) {
var cm = d.createElement('scr' + 'ipt');
cm.type = 'text/javascript';
cm.async = true;
cm.src = 'https://sdk.staging.chatlayer.ai/chatlayer.js';
//This URL should be changed to 'https://sdk.chatlayer.ai/chatlayer.js' for the production version of the SDK.
cm.id = 'chatjs';
var s = d.getElementsByTagName('scr' + 'ipt')[0];
s.parentNode.insertBefore(cm, s);
cm.addEventListener('load', function() {
// Instantiate your Chatlayer class.
var chat = new Chatlayer({
botId: XYZ, // your botId
//Note: the styles object has been removed
});
chat.initialize(document.getElementById('frameId'));
});
})(document);
</script>

The SDK will initialise the chat frame using these classnames:

Classname

Purpose

chatlayer-chat-open

Loads css when the chat window is open

chatlayer-chat-close

Loads css when the chat window is closed

Example CSS using default classnames

.chatlayer-chat-close {
width: 370px;
height: 0px;
position: absolute;
bottom: 80px;
right: 10px;
}
.chatlayer-chat-open {
width: 370px;
height: 500px;
border: 1px solid black;
position: absolute;
bottom: 80px;
right: 10px;
}

Create your own chat toggle button

A lot of our customers prefer to show the chatbot as a closed button until the user clicks that button to open the full chat window.

Example of a chat toggle button

You can add this button to your Chatlayer.ai SDK by adding the following props to your setup script:

Prop

Purpose

button: true

Enable the render of a button

autoOpen: false

Open the web widget automatically when page loads

When the toggle button is enabled you can style the open/close button using the styles object or css classnames indicated below.

Chat toggle button styles

<script>
(function(d) {
var cm = d.createElement('scr' + 'ipt');
cm.type = 'text/javascript';
cm.async = true;
cm.src = 'https://sdk.staging.chatlayer.ai/chatlayer.js';
//This URL should be changed to 'https://sdk.chatlayer.ai/chatlayer.js' for the production version of the SDK.
cm.id = 'chatjs';
var s = d.getElementsByTagName('scr' + 'ipt')[0];
s.parentNode.insertBefore(cm, s);
cm.addEventListener('load', function() {
// Instantiate your Chatlayer class.
var chat = new Chatlayer({
botId: XYZ, // your botId
button: true,
autoOpen: false,
styles: {
button: {
open:
'position: absolute; bottom:0; right: 0; background-color: green; width: 60px; height: 60px; border-radius: 50%;',
close:
'position: absolute; bottom:0; right: 0; background-color: red; width: 60px; height: 60px; border-radius: 50%;',
},
},
});
chat.initialize(document.getElementById('frameId'));
});
})(document);
</script>

Chat toggle button CSS classnames

Classnames

Purpose

chatlayer-button-open

CSS applied when the button is in open state

chatlayer-button-close

CSS applied when button is in closed state

Chat button toggle event

The following event is emitted when the chat toggle button is clicked. You can use this event to trigger when the window is opened yourself.

Opening the chat window:

window.postMessage(
JSON.stringify({
action: 'openChat'
}),
'*'
);

Closing the chat window:

window.postMessage(
JSON.stringify({
action: 'closeChat'
}),
'*'
);

In-page web view rendering

If your bot has a web view, by default, that web view is opened in a new tab. If you would like to open the web view in a container on the page of the bot, use the following prop.

Prop

Purpose

webview: true

Opens the web view in a container on the webpage

Styling the web view window

Default

Default webview styling

Styles

styles: {
webview: {
overlay: 'position: fixed; width: 100%; height: 100%; background-color: #000000BB; z-index: 2147483647; top: 0; left: 0;',
container: 'width: 100%; height: 100%;max-width: 400px;max-height: 600px;margin: 0 auto;position: absolute;top: 50%;right: 50%;display: block;transform: translate(50%,-50%);background-color:white;',
header: 'height: 26px;width: 26px;margin-left: auto;margin-right: 5px;display: block;',
iframe: 'width: 100%; height: 100%;'
}
}

Classnames

Classnames

Purpose

chatlayer-webview-container

The container of the header and iframe

chatlayer-webview-overlay

The black background

chatlayer-webview-header

Header containing the close button

chatlayer-webview-iframe

Iframe

Overwrite default classnames

If you have your own CSS classnames, you can overwrite them using the props below:

<script>
(function(d) {
var cm = d.createElement('scr' + 'ipt');
cm.type = 'text/javascript';
cm.async = true;
cm.src = 'https://sdk.staging.chatlayer.ai/chatlayer.js';
//This URL should be changed to 'https://sdk.staging.chatlayer.ai/chatlayer.js' for the production version of the SDK.
cm.id = 'chatjs';
var s = d.getElementsByTagName('scr' + 'ipt')[0];
s.parentNode.insertBefore(cm, s);
cm.addEventListener('load', function() {
// Instantiate your Chatlayer class.
var chat = new Chatlayer({
botId: XYZ, // your botId
classNames: {
open: 'custom-window-open',
close: 'custom-window-close',
button: {
id: 'chatlayerButton',
open: 'custom-button-open',
close: 'custom-button-close',
},
webview: {
overlay: 'custom-web-overlay',
container: 'custom-web-container',
iframe: 'custom-web-iframe',
header: 'custom-web-header',
},
},
});
chat.initialize(document.getElementById('frameId'));
});
})(document);
</script>

Session Variables

When you want to pass information from your website to the chatbot, you can use session variables. This is often used to send the first name or other data about a logged in user to the bot, at which point it's used to customize the flow.

session: {
namespace: 'example',
data: {
firstname: 'SDK',
lastname: 'DOCS',
amount: '4000',
role: 'EXAMPLE'
},
}

In your bot dialogs you can use these variables as following.

Using session variables

The SDK will pass these variables and the resulting conversation will look like this:

Further questions

If anything is unclear after reading these docs or if you have other questions, feel free to get in touch.