Livechat Widget API
The Livechat Widget API allows developers to integrate Livechat widget functionalities into their apps seamlessly. The code must be after the Livechat Widget installation script and wrapped as a callback of
RocketChat(); function.You can call multiple Livechat Widget APIs on the same page.
To set a custom field for a visitor, you can use the following:
RocketChat(function() {
this.setCustomField('fieldName1', 'Any value you want to store');
this.setCustomField('fieldName2', 'A value set just once', false); // you can pass false as the third parameter to not overwrite an already set value
});
To change the color of the online status on the Livechat widget, use the following:
RocketChat(function() {
this.setTheme({
color: '#04436A', // widget title background color
fontColor: '#FFFFFF', // widget title font color
iconColor: '#1d74f5', // widget icon color
title: "Welcome to Rocket.Chat", // default widget title when the status of service is online
offlineTitle: "Service is offline", // default widget title when the status of service is online
});
});
To automatically assign a Livechat widget to a specific department (for example, to use a unique Livechat widget on more than one website), use the following :
RocketChat(function() {
this.setDepartment('FILL HERE DEPARTMENT NAME - case sensitive');
});
To set an external token for a visitor, use this:
RocketChat(function() {
this.setGuestToken('FHwaLnp8fzjMupSAj');
});
To set the visitor name field, use this:
RocketChat(function() {
this.setGuestName('visitor name');
});
To set the visitor email field, use this:
To register the visitor without using the registration form, use this:
RocketChat(function() t{
this.registerGuest({
token: 'FHwaLnp8fzjMupSAj', // The token field is not required. If it is not passed, a new token will be generated
name: 'visitor Name',
email: '[email protected]',
department: 'my_department', // The department field is not required,
customFields: [ // The customFields field is not required. If it is passed it needs to be an Array, where each item needs to be an object with key and value fields
{key: 'my_custom_field_a', value: 'my_custom_field_a_value', overwrite: true},
{key: 'my_custom_field_b', value: 'my_custom_field_b_value', overwrite: true}
]
});
});
To select a language for the widget, use this:
RocketChat(function() {
this.setLanguage('af');
});
Set a specific agent before the conversation starts. Use this to set up:
RocketChat(function() {
this.setAgent({
_id: 'h24yNtyoCmvp96wgt',
username: 'rocket.chat',
});
});
To configure all the settings in just one method, use this:
RocketChat(function() {
this.initialize({
theme: {
color: '#04436A',
fontColor: '#FFFFFF',
iconColor: '#1d74f5',
title: "Welcome to Rocket.Chat",
offlineTitle: "Service is offline",
},
department: 'sales',
guestToken: 'FHwaLnp8fzjMupSAj',
language: 'en',
});
});
You can either hide or show widget in your application. To hide the widget use this:
RocketChat(function() {
this.hideWidget();
});
To show widget, use this:.
RocketChat(function() {
this.showWidget();
});
You can either open or close the widget on your website. To open the widget by default, use this:
RocketChat(function() {
this.maximizeWidget();
});
To close the widget, use this:
RocketChat(function() {
this.minimizeWidget();
});
Assign a business unit to a widget instance so that the widget will only allow the visitors to select departments connected to that particular business unit on the widget's registration form.
Enterprises need to deal with hundreds of business units in the same workspace, and each Business Unit represents a specific website where Live Chat is installed. Therefore, once a BU is set, only departments associated with the current BU set should be available on the Live Chat Registration Form.
RocketChat(function() {
this.setBusinessUnit('LnM2rzbknjYSkkd5p');
});
To clear any connected business unit on the widget, use this:
RocketChat(function() {
this.clearBusinessUnit();
});
Fired when the chat widget is maximized.
RocketChat(function() {
this.onChatMaximized(function() {
// do whatever you want
console.log('chat widget maximized');
});
});
Fired when the chat widget is minimized.
RocketChat(function() {
this.onChatMinimized(function() {
// do whatever you want
console.log('chat widget minimized');
});
});
Fired when the chat is started (when the first message is sent).
RocketChat(function() {
this.onChatStarted(function() {
// do whatever you want
console.log('chat started');
});
});
Fired when the chat is ended either by the agent or the visitor.
RocketChat(function() {
this.onChatEnded(function() {
// do whatever you want
console.log('chat ended');
});
});
Fired when the pre-chat form is submitted.
RocketChat(function() {
this.onPrechatFormSubmit(function(data) {
// data is an object containing the following fields: name, email and deparment (the department _id)
// do whatever you want
console.log('pre-chat form submitted');
});
});
Fired when the offline form is submitted.
RocketChat(function() {
this.onOfflineFormSubmit(function(data) {
// data is an object containing the following fields: name, email and message
// do whatever you want
console.log('offline form submitted');
});
});
Fired when the widget is hidden.
RocketChat(function() {
this.onWidgetHidden(function(data) {
// do whatever you want
console.log('chat widget hidden');
});
});
Fired when an agent is assigned to the chat.
RocketChat(function() {
this.onAssignAgent(function(data) {
// data is an object containing the following fields: name, username and status
// do whatever you want
console.log('Agent assigned');
});
});
Fired when the widget is shown.
RocketChat(function() {
this.onWidgetShown(function(data) {
// do whatever you want
console.log('chat widget shown');
});
});
Fired when the status of the current agent changes.
RocketChat(function() {
this.onAgentStatusChange(function(data) {
// data is an object containing the following fields: name, username and status
// do whatever you want
console.log('The status of the agent has changed');
});
});
Fired when a visitor tries to start a new conversation and the Livechat service is offline.
RocketChat(function() {
this.onServiceOffline(function(data) {
// do whatever you want
console.log('The Livechat service is offline');
});
});
Version | Description |
|---|---|
3.1.0 | Added setAgent and initialize methods. Also, improved the setTheme method adding more options to customize the widget |
3.0.0 | Added onServiceOffline callback |
2.2.0 | Added maximizeWidget and minimizeWidget methods. |
1.3.0 | Added onAssignAgent and onAgentStatusChange methods. |
1.1.0 | Added showWidget and hideWidget methods along with onWidgetHidden and onWidgetShown events |
1.0.0 | Added setLanguage method |
0.66.0 | Added setGuestToken, setGuestName, setGuestEmail and registerGuest methods. |
0.53.0 | Added callback events and the ability to pass a flag to setCustomField so the value passed does not get wrote if there is already an existing value. |
0.36.0 | Added setTheme method |
0.26.0 | Added setCustomField method |
Last modified 2mo ago