What is an Agent App Widget?

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:

Sample use cases

There are number of ways you can utilize the widgets:

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

Getting started in 5 minutes

  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.

Advanced use

Sample widgets

We’ve prepared two example repositories for your convenience. Both examples show how to receive data from Events and display them within the sidebar.

You can take it from there and use the visitor’s email to query your own service or provide contextual help for the agent based on visitor details.

PHP and Silex

Set up the environment

git clone
cd agent-app-sample-extension
composer install

Configure your local web server to serve content over HTTPS and turn on the extension.

A basic backend application example written with the use of Silex.

GitHub Repository

Webpack (JS)

Set up the environment

git clone
cd agent-app-sample-extension-webpack
npm install

Run the webpack server

npm start

A basic static application example served from Webpack Server.

GitHub Repository

The content of the extension should be available at https://localhost:3333.

You can now turn on the extension.

Hosting the widget

You can host your widget locally or on a dedicated server. The hosted content has to be served over HTTPS Protocol. You can use a self-signed certificate for localhost or upload your widget to an SSL-enabled host. If you go for the Webpack Example, you’ll get the setup out of-the-box.

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 your widget content is loaded, fire the LiveChat.init() method. It will let the Agent App know when to hide the spinning loader.

Fire LiveChat.init()

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


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="//">


If you want to interact with agents data, you have two options.

This way you can leverage safe OAuth2.0 authorization flow. Head to Sign in with LiveChat docs for more information.

Basic authorization flow (deprecated)

1. First, the extension content is requested by the Agent App. A basic HTTPS GET request is sent.

2. Within the body of your extension, you should call the LiveChat.init(); method once the extension is loaded. This will tell the Agent App to start the initialization and hide the spinning loader.

3. In return, the Agent App sends a HTTPS POST request to https://your_ext_url/authorize/. Note that this path is non-configurable. Within the body of the post, you’ll find two keys:

    "login":,    // current LiveChat user email address
    "api_key": <agent_api_key>   // current LiveChat API key

4. You can now create a custom authorization logic (e.g. request external services, define scopes for your user, etc.)

5. In order to complete the flow, you should respond with a JSON response:

    "session_id": 12345          // any string or value

When the basic authorization flow is completed, you can use the LiveChat.on("event", ... ) method to catch the incoming events.

After a successful initialization, the Agent App should remove the spinner, display the content of your extension and push an authorize event via postMessage.

You can listen to authorize and authorize_error to catch the result of the authorization flow and, for instance, to display adequate information.

You should now receive events from the Agent App. Check out the JavaScript API events.

JavaScript API

To use the JavaScript API you have to attach the core functionality script.

Initialize the communication

// Additionaly, you have to authorize using "Sign in with LiveChat":

Let the Agent App know the extension is ready. Once called, the Agent App removes the loader screen from the extension and sends a request to https://your_extension_url/authorize/. This mechanism allows you to introduce an authorization flow for your service.

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 calls of a new one.


Put message

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



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)
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


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.