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 API methods on the same page. The widget API information is stored in the local storage of the browser.
Methods
Set custom field
To set a custom field for a visitor, you can use the following:
Set theme options
To change the color of the online status on the Livechat widget, use the following:
The following theme options are exclusively available to workspaces subscribed to any of Rocket.Chat's premium plans:
agentBubbleBackgroundColor
guestBubbleBackgroundColor
background
hideAgentAvatar
hideGuestAvatar
position
Remove theme options
To remove the theme options, set the field value as undefined
. Note that omitting the field itself does not remove the customization value.
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 :
Transfer chat
To transfer an ongoing chat to another department, use the following:
Set visitor token
To set an external token for a visitor, use this:
Set name field
To set the visitor name field, use this:
Set email field
To set the visitor email field, use this:
Register visitor
To register the visitor without using the registration form, use this:
Set guest metadata 
To determine a list of attributes and their corresponding values for a guest:
This method is essential when using an external service to send livechat trigger messages.
Set language for widget
To select a language for the widget, use this:
See supported languages here.
Set a default agent before starting a new conversation
Set a specific agent before the conversation starts. Use this to set up:
Initialize the widget by configuring all available properties in just one call
To configure all the settings in just one method, use this:
It is recommended that you use either the
registerGuest
or thesetToken
property at once. Using both properties at the same time can cause intermittent issues in registering the visitor properly.
Change widget visibility
You can either hide or show widgets in your application. To hide the widget use this:
To show the widget, use this:.
Change the widget window state
You can either open or close the widget on your website. To open the widget by default, use this:
To close the widget, use this:
Set business unit to filter departments on the registration page 
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 Livechat is installed. Therefore, once a BU is set, only departments associated with the current BU set should be available on the Livechat registration form.
To clear any connected business unit on the widget, use this:
Hide system messages 
You can hide specific system messages in the livechat widget conversation. Use the method as follows:
Events
onChatMaximized
Used when the chat widget is maximized.
onChatMinimized
Used when the chat widget is minimized.
onChatStarted
Used when the chat is started (when the first message is sent).
onChatEnded
Used when the chat is ended either by the agent or the visitor.
onPrechatFormSubmit
Used when the pre-chat form is submitted.
onOfflineFormSubmit
Used when the offline form is submitted.
onWidgetHidden
Used when the widget is hidden.
onAssignAgent
Used when an agent is assigned to the chat.
onWidgetShown
Used when the widget is shown.
onAgentStatusChange
Fired when the status of the current agent changes.
onServiceOffline
Fired when a visitor tries to start a new conversation and the Livechat service is offline.
Changelog
Version | Description |
---|---|
6.7.0 | Added |
3.1.0 | Added |
3.0.0 | Added |
2.2.0 | Added |
1.3.0 | Added |
1.1.0 | Added |
1.0.0 | Added |
0.66.0 | Added |
0.53.0 | Added callback events and the ability to pass a flag to |
0.36.0 | Added |
0.26.0 | Added |