Agent App Widgets are web applications loaded inside the LiveChat Agent App. All agents can interact with the widget during chats with customers. The widget itself is displayed in the Agent’s App sidebar:


This tool is a simple JavaScript SDK, which allows you to communicate with LiveChat Agent App from within the embedded widget.

Use cases

Widgets are primary elements of Agent App interface. There are number of ways you can use the them:

  • embed and display static content, e.g. knowledge base articles, conversation prompts or context information,
  • embed your SaaS service or web app as a part of agents’ workspace,
  • query external services with visitor email or LiveChat group ID (CRM, marketing automation, etc.),
  • create store with in-app purchases to sell additional services or features of your app,
  • query LiveChat REST API to do basically anything with the visitor, agent or chat.

Important notes

To build Agent App Widgets you need to have basic knowledge about JavaScript and HTML. We’ve got a lot of sample apps ready for you to take further. If you got stuck at any point, feel free to contact us anytime via chat.

Keep in mind the widgets are front-end elements of LiveChat Agent App. If you’d like to build an app that works on the server-side, please see the REST API docs.

Feature requests

If you have any feature requests related to the Agent App Widgets, let us know! We’re open for your insights and suggestions.

Getting started

  1. Go to the LiveChat Developers Console.
  2. Create a new app and follow the app wizard.
  3. Set up app name, descriptions and icon in Display settings.
  4. Configure Agent App Widget in the Features tab. If you don’t have a working app at hand, feel free to start with the sample ones:
  5. Go to Distribution settings and install the app at your license. You’ll see it in the LiveChat Agent App.

Sample Widgets

We’ve prepared a repository of sample apps for your convenience.

  • Tag Master: widget allows user to create, view and delete tags and canned responses in easy and predictable way.
  • Progress: a simple app that creates reports based on data from chats.
  • Supervisor: simple widget for helping you to monitor weekly progress of your agents and also their availability.

See the repo

Advanced use

Developing your own widget

If you want to build your own widget, be sure to include both the LiveChat Boilerplate and JavaScript Widget API:

Our widget SDK package is hosted on NPM. You can get it with following command:

npm install --save @livechat/agent-app-widget-sdk

After the content of your widget is loaded, fire the LiveChat.init() method. It will let the Agent App know when to hide the spinning loader.

Import the SDK and fire LiveChat.init() method

import LiveChat from '@livechat/agent-app-widget-sdk';
// ...

Interacting with Agent App

After a successful initialization, the Agent App should remove the spinner and display the content of your extension. You should now be able to receive events from the Agent App. Check out the JavaScript API events.

Accessing LiveChat data

You can leverage OAuth2.0 authorization flow to access data from the REST API. Head to Sign in with LiveChat docs for more information.

Layout and Styling

We ship a LiveChat Boilerplate – it’s a lightweight CSS stylesheet to help you lift off with creating the widget interface.

Place this tag within the <head></head> section:

<link rel="stylesheet" href="//">

Hosting the widget

You can host your widget locally or on a dedicated server. The hosted content has to be served over HTTPS Protocol.

While development, you can use a self-signed certificate for localhost or upload your widget to an SSL-enabled host. You can also leverage bundlers like Webpack to use https-enabled development server.

JavaScript Widgets API

To use the JavaScript API you should import the Agent App Widgets SDK.

Init and receive customer profile

import LiveChat from '@livechat/agent-app-widget-sdk';

// ...


// Forces Web App to send you information about the current customer

LiveChat.on("customer_profile", function( data ) {
	console.log( data )

Let the Agent App know the widget is ready. Once called, the Agent App removes the loading spinner and shows the content of the widget.


Events allow you react to the actions in the Agent App. Use this method as a listener for certain events.

LiveChat.on("<event_name>", function( data ) {
	// ...
Event name Triggers when
customer_profile the agent opens a customer profile within Chats, Archives or Visitors sections
customer_profile_hidden the opened customer profile belongs to the visitor that left the Visitors list

Events customer_profile and customer_profile_hidden return an object width additional properties.

Customer profile displayed

Sample data object for customer_profile event

  "id": "S126126161.O136OJPO1",
  "name": "Mary Brown",
  "email": "",
  "chat": {
    "id": "NY0U96PIT4",
    "groupID": "42"
  "source": "chats",
  "geolocation": {
    "city": "Wroclaw"
    "country": "Poland"
    "country_code": "PL"
    "latitude": "51.1093"
    "longitude": "17.0248"
    "region": "Dolnoslaskie"
    "timezone": "Europe/Warsaw"
    "zipcode": ""
Property Description
id Unique ID of a visitor
name Visitor name (if provided)
email Visitor email (if provided)
chat Object with two properties: id (unique chat id) and groupID (unique group id); this object may be empty when a visitor is not currently chatting
source String representing the source of an event; possible values: chats, visitors, archives

Customer profile hidden

Sample data object for customer_profile_hidden event

  "id": "S126126161.O136OJPO1"
Property Description
id Unique ID of a visitor

Put message to textarea

It appends given message at the end of current conversation input window or into ticket window. Agent has to confirm sending this message.

LiveChat.putMessage("Hello! This message comes from the App Widget. Press enter to send it!");

Get the ID of the session

Returns the ID of the current extension session.


Refresh the session ID

Deletes the ID of the previous session and requests of a new one.



There are errors in the console

Check out your browser’s console to see if there are any of the errors listed below.

Error Explanation
Mixed Content: The page at '' was loaded over HTTPS, but requested an insecure resource '...'. This request has been blocked; the content must be served over HTTPS. For security reasons the Agent App is served over HTTPS and so must be the extension. Learn more on why we need SSL-enabled address in MDN article about mixed content.
Refused to display '...' in a frame because an ancestor violates the following Content Security Policy directive: "...". The host that serves the plugin has specific Content Security Policy set up.
Refused to display '...' in a frame because it set 'X-Frame-Options' to 'SAMEORIGIN'. The host serving the content of the plugin has specific X-Frame-Options header set up.

The loader never stops spinning

Make sure you followed the initiallization flow mentioned in Developing your own extension. If the LiveChat.init() method is fired correctly, the spinner disappears and the extension becomes visible.