Agent App SDK


Agent App Widgets are web applications loaded inside the LiveChat Agent App user interface. Read about their possible locations in the Building LiveChat apps guide. The Agent App SDK is currently the primary way to develop your own widgets and can be used in a basic or advanced way.

Use cases

Widgets are primary elements of the Agent App user interface. You can use them to:

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

Before you start

From a technical point of view, widgets are regular web applications. For that reason, you need to have some knowledge of HTML, CSS, and JavaScript to build your own widget.

Bear in mind that widgets are front-end elements of the LiveChat Agent App. If your intention is to build a server-side app, we encourage you to check out the Messaging APIs.

Getting started

Follow the intructions to create a basic LiveChat Widget. Before you start, make sure you have an account.

  1. Go to the Apps section in Developer Console.
  2. Click Create new app + and give your app a name.
  3. Decide which product you want to build your app for.
  4. Go to Building blocks and add a new LiveChat Widgets block.
    • Enter the Widget source URL, which is the address of your application. If it's not ready yet, you can use our sample apps to play around.
    • Choose the widget placement. It allows you to decide where exactly in the LiveChat App you want to display your integration. Currently, the possible locations are: the Details section, message box, Settings, main menu (fullscreen apps). Read more about app locations.
  5. Additionally, you can configure your app's short decription and add an icon for better visibility in the LiveChat App. You can do that in the Display details tab.
  6. Go to the Private installation tab and install the app on your account.

After the successful installation, you'll see the widget in your LiveChat App.

Sample apps

If you'd like to experiment with some of the already existing apps, make sure to check out the repository we've prepared. Once installed, these widgets will be displayed in the right sidebar of the Agent App.

  • Tag Master: allows user to create, view, and delete tags and canned responses in easy and predictable way.
  • Progress: creates reports based on data from chats.
  • Supervisor: helps to monitor the weekly progress of your agents, as well as their availability.

Installing the SDK

You can download the SDK directly from NPM as an ES6 or CommonJS module.

Install the SDK from NPM...

npm install @livechat/agent-app-sdk

...then import the ES6 module...

import * as LiveChat from "@livechat/agent-app-sdk";

...or require the CommonJS.

const LiveChat = require("@livechat/agent-app-sdk");

You can also use the UMD build of the SDK directly in the browser.

You can also use the UMD build:

<script src=""></script>
  LiveChat.createDetailsWidget().then(function(widget) {
    // do something with widget

Basic use

The specific usage of the Agent App SDK depends on the type of widget you want to create. The currently available widget types are the following:

All widgets created with the Agent App SDK share a common interface, which lets you listen for the events happening in the Agent App.

Supposing that widget is a widget instance:

function handleEvent(event) {
  // perform logic when event happens,
  // you can also use the data attached to the event

// Subscribe to event
widget.on("event", handleEvent);

// Unsubscribe from event"event", handleEvent);

Each widget type offers a different set of events that you can listen for.

Details widgets

If you want to use your app in the Details section, you should use the createDetailsWidget function. It returns a promise resolving to a details widget instance.

import { createDetailsWidget } from "@livechat/agent-app-sdk";

createDetailsWidget().then(widget => {
  // build your logic around the widget



Emitted when an agent opens a conversation within Chats or Archives, or when an agents selects the customer profile in the Customers sections. The handler will get the customer profile object as an argument.

Listen for the customer profile changes:

widget.on("customer_profile", profile => {
  // read the new profile

The customer profile object will have the following shape:

idUnique ID of a visitor
nameVisitor name (if provided)
emailVisitor email (if provided)
chatObject with three properties: chat_id (unique chat id), groupID (unique group id), and id (unique thread id); this object may be empty when a visitor is not currently chatting
sourceString representing the source of an event; possible values: chats, customers, archives
geolocationObject containing detailed information about customer's geolocation
customVariablesObject containing custom variables for given customer/chat (if provided)

Emitted when you click a button located in a section in Customer Details. The handler gets the following payload:

buttonIdThe id of the button taken from the section definition

React to button clicks within Customer Details widgets

widget.on("customer_details_section_button_click", ({ buttonId }) => {
  // perform an action when the button is clicked


Get the customer profile

If you want to access the current customer profile, you should use the getCustomerProfile method.

Get the current customer profile

const profile = widget.getCustomerProfile();

The returned profile will be an object identical to the one emitted by the customer_profile event. It can also be null if no profile was recorded.

Append text to the message box

You can add any text to the current chat message box by using the putMessage method. The method returns a promise.

Append text to the message box

widget.putMessage("this text will be appended").then(() => {
  // the text should be appended now
Modify Customer Details widget's state

If you configured a Customer Details widget, you can modify its section state using the modifySection method. The method accepts the section state definition as its only parameter, and returns a promise.

You can look up the component types to see how to create the state definition.

The title of a given section has to match the one specified in the initial state. Otherwise, the section won't change. Also, the Agent App ignores the commands without valid section definitions. Make sure that the definition you're sending is correct.

Modify the Customer Details widget's state

    title: "My widget",
    components: [
        type: "title",
        data: {
          value: "The title will be modified"
  .then(() => {
    // the widget should be modified now


The createMessageBoxWidget function creates a widget instance to be used in MessageBox.

import { createMessageBoxWidget } from ‘@livechat/agent-app-sdk’;

createMessageBoxWidget().then(widget => {
  // do something with the widget


Set a message to be stored by MessageBox
putMessage(msg: IRichMessage ): Promise<void>

Calling this method does not automatically send the message right away. The message is sent once an agent clicks the Send button. The message accepts the rich message type, which must implement the IRichMessage interface.

Set a message to be stored by MessageBox

const richMessage = {
  template_id: "cards",
  elements: [
      title: "My cat photo",
      image: {
          url: ""

Rich Message object format
  • custom_id, properties and elements are optional
  • elements may contain 1-10 element objects
  • all elements properties are optional: title, subtitle, image, and buttons
  • property url on image is required
  • optional image properties: name, content_type, size, width, and height
  • buttons may contain 1-11 button objects (1-13 if using API version 3.2 and above)
  • template_id describes how the event should be presented in an app
  • elements.buttons.postback_id describes the action sent via the send_rich_message_postback method
  • multiple buttons (even from different elements) can contain the same postback_id; calling send_rich_message_postback with this id will add a user to all these buttons at once.
  • elements.buttons.user_ids describes users who sent the postback with "toggled": true
Read more about Rich Messages

Fullscreen widgets

If you want to connect a Fullscreen widget to the LiveChat Agent App, you should use the createFullscreenWidget function. It returns a promise resolving to a Fullscreen widget instance.

import { createFullscreenWidget } from "@livechat/agent-app-sdk";

createFullscreenWidget().then(widget => {
  // build your logic around the widget


This widget currently does not support any events.


Set notification badge

If you want to notify Agents there’s something important inside the widget, use the setNotificationBadge method.


It displays a notification badge on top of your app’s icon:

Fullscreen widget badge

If you want to remove the badge, invoke the method with the null parameter.


Make sure Agents can dismiss the notification to avoid cluttered UI.

Advanced use

Developing your own widget

If you're building your own widget and you need to interact with the Agent App, be sure to use the Agent App SDK.

Accessing LiveChat data

You can leverage the OAuth 2.1 authorization flow to use all of LiveChat APIs. Head to Sign in with LiveChat docs for more information.

Layout and Styling

If you're using React, you can use the LiveChat Design System, which is a component library used directly in the LiveChat user interface.

Hosting the widget

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

During 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 an https-enabled development server.

If you need a quick way to deploy your widget, you can use Netlify Drop.

Creating a Customer Details widget

When developing an app in the Details section, you can add some content to the Customer Details view and display it as a widget. This way you turn it into a Customer Details widget.

Let's define the terms we use in this document:

  • Section - an element of Customer Details. It contains a complete set of information grouped under a single widget.
  • Component - a single line in a section. It can have one of the pre-defined formats and be filled with data from the app.

How to add a widget

To display a widget, first, you need to declare the initial state of a section. Go to Apps in Developer Console and create a new Details widget or update an exisiting one. The initial state of a section can be added using the Initial state input.

Example of the initial state JSON:

  "customerDetailsSections": [
      "title": "Example section",
      "components": [
          "type": "button",
          "data": {
            "label": "Example button",
            "id": "example-button"

You can define as many sections as you want. Once your widget is running within the Agent App, you can't add nor remove any sections. However, you can still modify the components within any section.

Also, the title attribute in the section initial state acts as a section ID. You should not modify it.

How to update a section

You can control your widget and change its components using the Agent App SDK. Please refer to the Modify the Customer Details widget.

Component types

Here's the list of all the components you can use to build the Customer Details app.


Section is a container for components.

Example of a section component

  "title": "card with image",
  "components": [],
  "imgUrl": "",
  "openApp": true
componentsYesarray of components

Title could be used in several cases. Component look depends on the given data.

Example of a title component

  "type": "title",
  "data": {
    "title": "title",
    "value": "value",
    "description": "description",
    "imgUrl": ""
imgSizeNoValue: "small" or "big" (default)
linkNostringURL added when the title is a link
idNostringID passed to the widget on click
clickableNobooleanAdds a border and makes it clickable
openAppNobooleanOpens widget on click

Simple button component

Example of a button component

  "type": "button",
  "data": {
    "id": "second-button",
    "label": "second button",
    "openApp": true,
    "primary": true
openAppNobooleanDefault value: false
primaryNobooleanDefault value: false
secondaryNobooleanDefault value: false
Click events

You can listen for button clicks using the SDK. Note that buttonId will be the same as the id from the schema. If you want to capture a specific click, you need to make sure that the id is unique across all definitions.

Label with value

Example of label with value component

  "type": "label_value",
  "data": {
    "label": "Name",
    "value": "Stefan",
    "iconUrl": ""

Example of a link component

  "type": "link",
  "data": {
    "value": "click me",
    "url": "",
    "inline": false
inlineNobooleandefault: true

Line could be used to separate section content. It has no components inside.

Example of a line component

  "type": "line"

Renders a line with a customer's avatar, name, and email.

  "type": "customer"

Renders a list of tags with an optional label.

  "type": "tags",
  "data": {
    "tags": ["new", "important", "private"],
    "label": "Tags:"
tagsYesarray of strings


There are errors in the console

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

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.

Contact us

If you have any feature requests related to the App Widgets, let us know! We're open to your insights and suggestions. Feel free to drop us an email at or join our community on Discord and ask us your questions there.


Join the community
Get in direct contact with us through Discord.
Follow us
Follow our insightful tweets and interact with our content.
See something that's wrong or unclear? Submit a pull request.
Contact us
Want to share feedback? Reach us at: