WebChat Integration Guide

Last updated: 06 Apr 2022

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). ^[¹^]

<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 ^[²^]
`logoUrl`	string	No	Sets the logo of the widget	Any valid path ^[³^], 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 ^[³^], 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:

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