WebChat Integration Guide
Last updated:
About this guide
This document explains how to embed Omilia’s WebChat widget in your own website.
Requirements
Basic HTML & JS knowledge
Embed the chat widget on your website
To embed the chat widget to your website, go to the Chat tab of a miniApp, select a Locale and click the Get JS Code button. Copy the Javascript code with the Copy button and paste it to your website’s HTML code. Otherwise copy only the API key and URL Key from the JS code.
Click the Try webchat! button to test the webchat.

Create the JS code manually
Create the required script. Modify the code snippet by altering the values of the parameters in the table Parameters of chat widget integration script.
To embed the WebChat widget in your website paste the code snippet within the body of the HTML code (preferably at the end). [1]
<body>
...
<script>
(function(docElement, tag, rootElementId, bundleSrc, config, data) {
var body = docElement.getElementsByTagName('body')[0];
var div = docElement.createElement('div');
div.id = rootElementId;
body.appendChild(div);
var element = docElement.createElement(tag);
element.src = bundleSrc;
element.type = 'text/javascript';
var callback = function() {
ChatBot.init({ rootElementId, config, data });
};
element.onload = callback;
element.onreadystatechange = function() {
this.readyState == 'complete' && callback();
};
body.appendChild(element);
})
(document, 'script', 'root-chatbot', 'https://assets.miniapps.ocp.ai/ChatWidget/bundle.js', {
apiUrl: 'YOUR_API_URL',
apiKey: 'YOUR_API_KEY'
});
</script>
</body>
Customers during WebChat initialization, can provide a configuration object (see section Configuration) and an initialization data object (see section Initialization Data).
Configuration
During the initialization of the WebChat, customers have the option to pass a set of configuration variables to customize the widget.
Parameter | Type | Required | Description | Value |
---|---|---|---|---|
| string | Yes | Unique API URL of WebChat | Can be extracted from the Javascript with Get JS Code as described in section Embed the chat widget on your website |
| string | Yes | Unique API key of WebChat | Can be extracted from the Javascript with Get JS Code as described in section Embed the chat widget on your website |
| string | No | Sets the title of the widget | Max character length 16 [2] |
| string | No | Sets the logo of the widget | Any valid path [3], or Base64 format |
| string | No | Sets the alt attribute for the logo icon | Any valid |
| boolean | No | To hide or not the logo border. | Boolean value, by default is visible |
| boolean | No | When true the data (either given during | true/false. Default value false |
| string | No | To set the bubble icon of the chat widget. | Any valid path [3], or Base64 format |
| string | No | To set the alt attribute for the bubble icon. | Any valid string |
| boolean | No | When the value is true, the webchat has a button that the user can click to reset the chat. When clicked, it calls the | true/false. Default value false |
| string | No | To set the colour theme of the chat widget. | Any valid HTML colour |
| boolean | No | If it is true after the dialogue ends, the input box remains active (user can type), and inactive if it is false (user cannot type and needs to be restarted by closing and opening or by pressing the reset button). | true/false. Default value true |
Table 1. Parameters of chat widget integration script
config = {
apiUrl: '<YOUR_API_URL>',
apiKey: '<YOUR_API_KEY>',
title:' Omilia Chat',
logoUrl: 'data:image/svg+xml;base64,PD94bWwgdmVyc....',
logoAlt: 'Alt attribute logo icon',
logoBorder: false,
bubbleUrl: './path/to/image.svg',
bubbleAlt: 'Alt attribute bubble icon',
brandColor: '<YOUR_HTML_COLOR>'
}
Example configuration object
Initialization Data
During the initialization of the WebChat, customers have the option to pass their own data (for example, key-value pairs). Initialization data are transmitted when a new dialog starts and used by OCP to improve the conversational experiences of users.
Make sure data contains only whatever is necessary to improve the experience of the users.
data = {
userName: 'bilbo',
firstName: 'Bilbo',
lastName: 'Baggins'
customerNumber: '345453543544'
bearerToken: 'feawfjklej9820jr39802edj032#$23rni32ojrnkd23oj8230'
}
Example initialization object
Data object does not support complex data structures, for example, arrays or nested object.
An alternative way for customers is to use the setData
method on the widget.
ChatBot.setData({
userName: 'bilbo',
firstName: 'Bilbo',
lastName: 'Baggins'
customerNumber: '345453543544'
bearerToken: 'feawfjklej9820jr39802edj032#$23rni32ojrnkd23oj8230'
})
It can be used only when ChatBot is fully initialized. If you want to call setData
right after Chat.init
, it would be safer to move this data directly in the init
method.
Data that have been set during intialization or with setData
method, are sent only when one clicks the WebChat bubble to open or clicks the reset button.
Every time setData
is used, it overwrites previous data.
Event Callback
WebChat can provide chat events by setting up an appropriate callback method.
ChatBot.setEventCallback(event -> () {
})
The Event object has the following structure:
event = {
type: 'route',
meta: {
key1: 'value1',
key2: 'value2'
}
}
Property | Type | Description | Value |
---|---|---|---|
| string | Type of the event | start_dialog, route, end_dialog |
| object | Depending on the event type | (TO BE DETERMINED) |
Table 2. Parameters
At the moment, this method is triggered only when we have key meta
data inside the event. It might not be triggered on the events that do not give or reset meta information.
Restart Chat
State | After method call | Description |
---|---|---|
WebChat windows is open, and a chat is in progress or terminated | Open | The chat closes and reopens in an instant. It disconnects any open connections. Any dialog in progress will be lost. It initializes a new chat, and the dialogs from previous chat are neither visible nor retrievable. |
WebChat is closed and only the chat bubble is visible | Open | The chat opens in an instant. It initializes a new chat, and the dialogs from previous chat sessions are neither visible nor retrievable |
Table 3. UX Restart description
The restart method does NOT clear the data that was set with the setData
method, if the dataPersistent
is true. If you need to change the aforementioned data, you need to call setData
again.
Close Chat
WebChat provides a method to close the current chat. A "close" resets the Chat and closes the connection.
ChatBot.close()
State | After method call | Description |
---|---|---|
WebChat windows is open and a chat is in progress or terminated | Closed | The chat closes and disconnects any open connections. Any dialog in progress will be lost. |
WebChat is closed and only the chat bubble is visible | Closed | The chat remains closed. |
Table 4. UX Close description
The close method does NOT clear the data that was set with the setData
method, if the dataPersistent
is true. If you need to change the aforementioned data, you need to call setData
again.
Integration (Angular)
To embed the WebChat widget in an Angular Universal project, follow the steps below:
Access DOM and add bundle script in head section using the following code:
import {DOCUMENT} from "@angular/common";
import {Renderer2} from '@angular/core';
constructor(@Inject(DOCUMENT) private document: any, private renderer:Renderer2) {
}
constructor() {
const scriptElt = this.renderer.createElement('script');
this.renderer.setAttribute(scriptElt, 'type', 'text/javascript');
this.renderer.setAttribute(scriptElt, 'src','https://assets.miniapps.ocp.ai/ChatWidget/bundle.js');
this.renderer.appendChild(this.document.head, scriptElt);
}
2. Add the rest of the script from the Angular component:
ChatBot.init({
rootElementId: 'your_chat_container,
config: {
apiUrl: 'your_API_URL',
apiKey: 'your_APIkey',
title:' Omilia Chat',
logoUrl: 'data:image/svg+xml;base64,PD94bWwgdmVyc....',
logoAlt: 'Alt attribute logo icon',
logoBorder: false,
bubbleUrl: './path/to/image.svg',
bubbleAlt: 'Alt attribute bubble icon',
brandColor: 'yourHTML_color',
}
});
[1] Code snippet can be minified
[2] Including spaces
[3] To an SVG or png file with 60px X 60px size