IntroductionAbout the APIThe Chat Widget JavaScript API lets you interact with the Chat Widget embedded on your site. It might come in handy whenever you want to gather some additional data using LiveChat, show or hide your Chat Widget on certain occasions, or amend its behavior in a way that is not provided by the standard settings. Show
This document focuses on Developers and requires a basic knowledge of JavaScript. However, if you would have any questions, don't hesitate to start a chat with our Support Team or add a new topic on Developers Community. Getting startedThe API is accessed through the The API requires the newest version of the code snippet (≥2.0). If you had installed the code a while ago and the API presented here doesn't work, you should either update the code or use the old version of JS API. You can check the current version of your snippet by calling the The
The usage of these functions is based on passing the correct arguments in the following pattern: For example, if you would
like to set your customer's name to Asynchronous InitializationAsynchronous initialization is an optional feature available for Chat Widget via JavaScript API. It allows for far more control over the moment when the Chat Widget should be loaded. It can be especially useful if you would like to make widget initialization happen as a consequence of some user interaction, or your own application business logic event. This feature is disabled by default, so the Chat Widget loads automatically just after the snippet code is executed. In order to enable it, you need to explicitly set From now on the snippet code will be executed but the Chat Widget and its resources will not be loaded. It means that although
you will have access to Later in your code you can initialize Chat Widget manually when needed. To do that simply call MethodsTo change the visibility of the Chat Widget, you can use the following methods:
MaximizeIt maximizes the Chat Widget. ExampleMinimizeIt minimizes the Chat Widget. ExampleHideIt hides the Chat Widget on the site. You will need to use either 'maximize', or 'minimize' API calls to show it afterwards. ExampleDestroyIt destroys the Chat Widget. It won't be available for further actions until the window is refreshed. ExampleHide greetingIt hides the currently displayed greeting. In order to hide particular greeting you can listen to ExampleGettersYou can use getters to fetch the data from the Chat Widget. Available getters:
Get stateIt returns the Chat Widget state. This includes Widget visibility and license availability. ExampleResponse
Get customer dataIt returns a filtered list of customer data. ExampleResponse
Get chat dataIt returns chat data which contains current chat and thread ids. ExampleResponse
SettersVarious data can be sent over to the LiveChat integration so that your Agents can use it. For more information, you can read these articles in our Help Center: https://www.livechat.com/help/custom-variables-configuration/. Available setters:
Set session variablesCreates new session variables, or replaces the ones set previously. Update session variablesIt changes the values of your session variables. Please note that the existing variables won't be replaced. The new session variables will be included together with the ones set previously. ExampleSet customer nameIt sets the customer's name. ExampleSet customer emailIt sets the customer's email address. ExampleCallbacksCallbacks allow you to react to the events triggered by the Chat Widget. You can use them to add custom behaviors when certain events happen. This can be accomplished by subscribing a callback with the API. Available callbacks:
On readyThe Chat Widget has finished loading. If the Chat Widget is already loaded the provided handler function will be called immediately. With this callback, you will receive the Chat Widget state and customer data as if requested by their getters. Payload
On availability changedAvailability has changed for the current group. Payload
On visibility changedIt is called once the visibility of the Chat Widget has changed. This applies to both user actions like maximizing or minimizing the window as well as hiding or showing the Chat Widget through the use of this API. Payload
On customer status changedIt is called once the status of your customer has changed. This can be used to track the following info:
Payload
On new eventIt is called for both incoming and outgoing events. Payload
On form submittedIt is called after a form has been submitted in the chat. Payload:
On rating submittedIt is called after the customer has rated the chat, or cancelled the previous rating. Payload
On greeting displayedIt is called after the greeting has been displayed to the customer. Payload
On greeting hiddenIt is called after the greeting has been cancelled by the customer or Payload
On rich message button clickedIt is called after the rich message button has been clicked by the customer. Payload
PlaygroundHere's where you can play with the Chat Widget JavaScript API in an interactive environment. Use the buttons and inputs on the left side of the Widget or try to invoke some functions directly in the console. ExamplesHere you can find some example usage of the Chat Widget JavaScript API. They all require the Widget to be installed on the page and Show the Widget after timeShow the Chat Widget after 30 seconds and keep it open after reloading. Open the Widget using the buttonShow the hidden or minimized Widget after a button has been clicked. You can change the Widget visibility as described in our Help Center Prefill username and emailIt sets the Customers name and email using their login and email. Initialize Widget asynchronusly on button clickInitialize Chat Widget after clicking the button. |