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

  1. Create the required script. Modify the code snippet by altering the values of the parameters in the table Parameters of chat widget integration script.

  2. 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>
XML

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

apiUrl

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

apikey

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

title

string

No

Sets the title of the widget

Max character length 16 [2]

logoUrl

string

No

Sets the logo of the widget

Any valid path [3], or Base64 format

logoAlt

string

No

Sets the alt attribute for the logo icon

Any valid

logoBorder

boolean

No

To hide or not the logo border.

Boolean value, by default is visible

dataPersistent

boolean

No

When true the data (either given during init or setData method) is persistent between sessions in an already loaded page. Data do not persist if the webpage is reloaded.

true/false. Default value false

bubbleUrl

string

No

To set the bubble icon of the chat widget.

Any valid path [3], or Base64 format

bubbleAlt

string

No

To set the alt attribute for the bubble icon.

Any valid string

enableResetButton

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 ChatBot.restart() method. When the value is false, the reset button is not visible.

true/false. Default value false

brandColor

string

No

To set the colour theme of the chat widget.

Any valid HTML colour

enableConsecutiveDialogs

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>'
}
CODE

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'
}
CODE

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

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 -> () {


})
CODE

The Event object has the following structure:

event = {
    type: 'route',
    meta: {
      key1: 'value1',
      key2: 'value2'
    }
}
CODE

Property

Type

Description

Value

Type

string

Type of the event

start_dialog, route, end_dialog

meta

object

Depending on the event type meta might contain different key-value pairs.

(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()
CODE

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:

  1. 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);
}
XML

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',
    }
 });
CODE

[1] Code snippet can be minified

[2] Including spaces

[3] To an SVG or png file with 60px X 60px size


Comment about this article and provide feedback