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

Embed Customer Gadget in Customer-Widget

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

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

<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 
languagevarchar
  • Language code e.g. en, fretc.
  • 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

firstNamevarchar
  • Name 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"
lastNamevarcharThis is an optional field for "chat" form
phonevarchar
  • The phone number of the customer
  • This is a mandatory input when the value of is_anonymous_chat is set to "falseand the action parameter is set to "chat" or "callback"
emailvarchar
  • 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 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
campaignNamevarchar
  • 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.
additionalParamsobject
  • 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.
labelsarrayThis is an optional parameter for chat. It is used for priority routing.  Valid data type is array of strings.

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.

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.

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.

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.

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

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