Javascript API

Use Hybrid Chat Javascript API to embed Hybrid Chat web-chat widget in a website or a web application. The API is invoked via Javascript PostMessage. The widget is rendered in an IFrame.

Calling Javascript API

Embed the script into your website or application and launch it using window.PostMessage().

Open config.js file in customer-widget and update the following configuration

JS

const customer_widget_url = "https://[HostName]/customer-gadget";

Where HostName is the IP or FDQN of the server where the solution is hosted.

Embed customer-widget in third-party website

CODE

<script id="EF_init_widget" src="https://[customer-widget-fqdn]/init_widget.js"></script>

Launch

Launch the API from your website or application using Javascript window.postMessag().

API Parameters

Parameter	Type	Description
*action	varchar	Set the value to "`chat"` for a chat request and "`callback"` for a callback request This is a mandatory parameter An error message will be logged in the browser console and a toaster message will be displayed on the UI if, 1. action is not present 2. action is left empty 3. action passed in API is invalid
language	varchar	Language code e.g. `en, fr,` etc. This is an optional parameter If an invalid language code is supplied, the default browser language will be used
is_anonymous_chat `for_future_use`	bool	If set to "`true"`, the system will initialize anonymous chat without requiring the mandatory parameters for customer identification If set to "`false"`, the system will initialize a chat only when the mandatory parameters such as a name and phone number are passed When it is set to "`false"` and the mandatory parameters are also not met, an error message will be logged in the browser console and a toaster message will be displayed on the UI
firstName	varchar	The customer first name This is a mandatory input when the value of `is_anonymous_chat` is set to "`false" and the` action `parameter is set to "chat"` Validation 2 to 50 characters
lastName	varchar	This is an optional field for "`chat`" form Validation 2 to 50 characters
phone	varchar	The phone number of the customer This is a mandatory input when the value of `is_anonymous_chat` is set to "`false"` `and the` action `parameter is set to "chat" or` "`callback`" Validation 1 to 15 digits with an optional leading + character.
email	varchar	The email of the customer This is an optional input when action is set to "`chat"` This is not part of `"callback"` form.
queue	varchar	The name of the queue (max 50 characters) on which this particular chat should be queued This is an optional input in the case of anonymous chat but mandatory when the action parameter is set to `"chat"` If left empty or the queue name supplied is invalid, the chat will be assigned to the default queue
campaignId	int	The ID of the campaign with which the callback request should be linked This is a mandatory input when the action parameter is set to `"callback"` If left empty or the campaign ID passed in the API is invalid, an error message will be logged in the browser console and a toaster message will be displayed on the UI
campaignName	varchar	An Optional parameter for `callback`, this is the name of the campaign or skill group
comment	varchar	This is an optional parameter for both chat and callback. In the case of a chat request, i.e. when the action parameter is set to `"``chat",` it is considered as the first message from the customer and in the case of a callback request, it is used for customer notes that he wants the agent to read before the actual callback is initiated. Validation A comment can be of maximum 2000 characters.
additionalParams	object	This is an optional parameter for chat. In the case of a chat request, i.e. when the action parameter is set to `"``chat",` parameters defined in additionalParams are available for the agent inside customer-data. First five parameters named as channel_data_1 to channel_data_5 are available in reporting database as well. Validation they are key value pairs where the key can be of 15 characters and the value can hold up-to 250 characters.
labels	array	This is an optional parameter for chat. It is used for priority routing. Valid data type is array of strings where each label can be of 20 characters.

Chat Request Example

In this example, a chat request is initiated. The action parameter must be set to "chat". Specify an MRE queue name. See MRE User Guide for how to add a queue in the system. An optional comment field is added in case the customer has some notes they want the agent to read before the actual chat begins.

JS

var initRequest = {
    "action": "chat",
    "language": "en",
    "queue": "support",
    "firstName": "John",
    "lastName":"Doe",
    "phone": "03338283920",
    "email" : "john@domain.com",
    "comment" : "Note before starting chat",
    "labels"  : ["<label_1>", "<label_2>"],
    "additionalParams" : {
							channel_data_1:"<channel_data_1>", 
							channel_data_2:"<channel_data_2>",
							channel_data_3:"<channel_data_3>",
							channel_data_4:"<channel_data_4>",
							channel_data_5:"<channel_data_5>",
							<Key>  : "<VALUE>"
						 }

}
document.getElementById("ef_customer_widget").contentWindow.postMessage(initRequest, "*");

Callback

In order to initiate a callback request, you need to set the action parameter to "callback". Callback does not include the queue parameter. It requires a campaignId parameter which helps add the callback request to a certain campaign. Additionally, a phone number needs to be specified and an additional parameter for comments is provided.

JS

var initRequest = {
    "action": "callback",
    "firstName":"",
    "campaignId": "xxxxxx",
    "campaignName":"",
    "phone" : "923338383922",
    "comment" : "Note before initiating callback request"
    
}
document.getElementById("ef_customer_widget").contentWindow.postMessage(initRequest, "*");

Please refer to the Javascript API reference table for the details of the API parameters.

Anonymous Chat (For Future Use)

In the example below, the parameter action has been set to "chat" as this is a chat request. Additionally, the in_anonymous_chat parameter value is set to "true". You can specify the chat widget language by mentioning one of the predefined language codes enabled via Hybrid Chat's customer widget configurations. Additionally, you can specify the queue parameter to allow these chats to go to a specific agent queue. The code shown below will result in an anonymous chat being initiated with the customer.

JS

var initRequest = {
    "action": "chat",
    "language": "en",
    "queue": "xxxxxx,
    "is_anonymous_chat": true,
}
document.getElementById("ef_customer_widget").contentWindow.postMessage(initRequest, "*");

Events

The customer chat widget triggers the following events via a Javascript call of type .postMessage(). Any third party browser application can listen to the dispatched events to invoke changes in its UI, log chat state events in certain third-party reporting tools such as Google Analytics, etc.

Event Name	Payload	State
loaded	{ type: 'ef_customer_widget', name: 'loaded' }	When the customer widget is completely loaded
initialized	{ type: 'ef_customer_widget, name: 'initialized' }	When a chat has initialized/started.
ended	{ type: 'ef_customer_widget', name: 'ended' }	When a chat has ended
minimized	{ type: 'ef_customer_widget', name: ‘minimized’ }	When the customer widget is minimized
maximized	{ type: 'ef_customer_widget, name: ‘maximized’ }	When the customer widget is maximized

Here is an example of how your client application can listen to events fired by the customer widget. In this particular example, you can listen to the "ended" event and perform actions accordingly, e.g, show a "thank you" message on the screen as soon as the chat ends.

JS

window.addEventListener("message", receiveMessage, false);

function receiveMessage(event) {	
    if (event.data.action === 'ended') {
		//place your code here
	 }
}