Livechat Widget API

Usage
Livechat Widget API code must be inserted 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.
Methods
Set custom field
To set a custom field for a visitor, you can use the following code:
1
RocketChat(function() {
2
    this.setCustomField('fieldName1', 'Any value you want to store');
3
    this.setCustomField('fieldName2', 'A value set just once', false); // you can pass false as the third parameter to not overwrite an already set value
4
});
Copied!
Set theme options
To change the online color of the Livechat widget, use the following code:
1
RocketChat(function() {
2
    this.setTheme({
3
        color: '#04436A', // widget title background color
4
        fontColor: '#FFFFFF', // widget title font color
5
        iconColor: '#1d74f5', // widget icon color
6
        title: "Welcome to Rocket.Chat", // default widget title when the status of service is online
7
        offlineTitle: "Service is offline", // default widget title when the status of service is online
8
    });
9
});
Copied!
Assign chats to a specific department
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 code:
1
RocketChat(function() {
2
    this.setDepartment('FILL HERE DEPARTMENT NAME - case sensitive');
3
});
Copied!
Set visitor token
To set an external token for a visitor, you can use the following code:
1
RocketChat(function() {
2
    this.setGuestToken('FHwaLnp8fzjMupSAj');
3
});
Copied!
Set name field
To set the visitor name field, you can use the following code:
1
RocketChat(function() {
2
    this.setGuestName('visitor name');
3
});
Copied!
Set email field
To set the visitor email field, you can use the following code:
1
RocketChat(function() {
2
    this.setGuestEmail('[email protected]');
3
});
Copied!
Register visitor
To register the visitor without using the registration form, you can use the following code:
1
RocketChat(function() {
2
    this.registerGuest({
3
        token: 'FHwaLnp8fzjMupSAj', // The token field is not required. If it is not passed, a new token will be generated
4
        name: 'visitor Name',
5
        email: '[email protected]',
6
        department: 'my_department', // The department field is not required,
7
        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
8
            {key:  'my_custom_field_a', value: 'my_custom_field_a_value'},
9
            {key:  'my_custom_field_b', value: 'my_custom_field_b_value'}
10
        ]
11
    });
12
});
Copied!
Set Language for Widget
There are number of language options, which you can choose from to set language for your widget. To check supported languages refer here. To set language of widget use the following code.
1
RocketChat(function() {
2
    this.setLanguage('af');
3
});
Copied!
Set a default Agent before starting a new conversation
The widget allows setting a specific agent before the conversation starts, to do this follow these steps:
1
RocketChat(function() {
2
    this.setAgent({
3
        _id: 'h24yNtyoCmvp96wgt',
4
        username: 'rocket.chat',
5
  });
6
});
Copied!
Initialize the widget by configuring all available properties in just one call
The widget allows configuring all the settings in just one method, the following properties are acceptable:
1
RocketChat(function() {
2
    this.initialize({
3
        theme: {
4
            color: '#04436A',
5
            fontColor: '#FFFFFF',
6
            iconColor: '#1d74f5',
7
            title: "Welcome to Rocket.Chat",
8
           offlineTitle: "Service is offline",
9
        },
10
        department: 'sales',
11
        guestToken: 'FHwaLnp8fzjMupSAj',
12
        language: 'en',
13
  });
14
});
Copied!
Change widget visibility
You can either hide or show widget in your website. To hide widget use the following code:
1
RocketChat(function() {
2
    this.hideWidget();
3
});
Copied!
To show widget use the following code.
1
RocketChat(function() {
2
    this.showWidget();
3
});
Copied!
Change widget window state
You can either open or close then widget in your website. To open widget(default state) use the following code:
1
RocketChat(function() {
2
    this.maximizeWidget();
3
});
Copied!
To close the widget use the following code.
1
RocketChat(function() {
2
    this.minimizeWidget();
3
});
Copied!
Set Business Unit to filter departments on Registration page
Only available on Enterprise license
With this method, you can 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.
To set the business Unit on the widget use the following code: (Note, Business Unit ID is required)
1
RocketChat(function() {
2
    this.setBusinessUnit('LnM2rzbknjYSkkd5p');
3
});
Copied!
To clear any connected business Unit on the widget the following code.
1
RocketChat(function() {
2
    this.clearBusinessUnit();
3
});
Copied!
Events
onChatMaximized
Fired when the chat widget is maximized.
1
RocketChat(function() {
2
    this.onChatMaximized(function() {
3
        // do whatever you want
4
        console.log('chat widget maximized');
5
    });
6
});
Copied!
onChatMinimized
Fired when the chat widget is minimized.
1
RocketChat(function() {
2
    this.onChatMinimized(function() {
3
        // do whatever you want
4
        console.log('chat widget minimized');
5
    });
6
});
Copied!
onChatStarted
Fired when the chat is started (the first message was sent).
1
RocketChat(function() {
2
    this.onChatStarted(function() {
3
        // do whatever you want
4
        console.log('chat started');
5
    });
6
});
Copied!
onChatEnded
Fired when the chat is ended either by the agent or the visitor.
1
RocketChat(function() {
2
    this.onChatEnded(function() {
3
        // do whatever you want
4
        console.log('chat ended');
5
    });
6
});
Copied!
onPrechatFormSubmit
Fired when the pre-chat form is submitted.
1
RocketChat(function() {
2
    this.onPrechatFormSubmit(function(data) {
3
        // data is an object containing the following fields: name, email and deparment (the department _id)
4
​
5
        // do whatever you want
6
        console.log('pre-chat form submitted');
7
    });
8
});
Copied!
onOfflineFormSubmit
Fired when the offline form is submitted.
1
RocketChat(function() {
2
    this.onOfflineFormSubmit(function(data) {
3
        // data is an object containing the following fields: name, email and message
4
​
5
        // do whatever you want
6
        console.log('offline form submitted');
7
    });
8
});
Copied!
onWidgetHidden
Fired when widget is hidden.
1
RocketChat(function() {
2
    this.onWidgetHidden(function(data) {
3
        // do whatever you want
4
        console.log('chat widget hidden');
5
    });
6
});
Copied!
onAssignAgent
Fired when an agent is assigned to the chat.
1
RocketChat(function() {
2
    this.onAssignAgent(function(data) {
3
        // data is an object containing the following fields: name, username and status
4
​
5
        // do whatever you want
6
        console.log('Agent assigned');
7
    });
8
});
Copied!
onWidgetShown
Fired when widget is shown.
1
RocketChat(function() {
2
    this.onWidgetShown(function(data) {
3
        // do whatever you want
4
        console.log('chat widget shown');
5
    });
6
});
Copied!
onAgentStatusChange
Fired when the status of the current agent changes.
1
RocketChat(function() {
2
    this.onAgentStatusChange(function(data) {
3
        // data is an object containing the following fields: name, username and status
4
​
5
        // do whatever you want
6
        console.log('The status of the agent has changed');
7
    });
8
});
Copied!
onServiceOffline
Fired when a visitor tries to start a new conversation and the Livechat service is offline.
1
RocketChat(function() {
2
    this.onServiceOffline(function(data) {
3
        // do whatever you want
4
        console.log('The Livechat service is offline');
5
    });
6
});
Copied!
Change Log
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

Avatars

Next - Fuselage

Contributing

Last modified 5mo ago

Export as PDF

Copy link

Edit on GitHub

Contents