Introduction

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:

Overview

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';
// ...
LiveChat.init();

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="//cdn.livechatinc.com/boilerplate/1.1.css">

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';

// ...

LiveChat.init();

// Forces Web App to send you information about the current customer
LiveChat.refreshSessionId();

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

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": "mary.brown@email.com",
  "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!");

Add new content to Customer Details

Introduction

You can use the SDK to add your own content to the Customer Details view. To better understand the following part, lets first define the definitions we will be using:

  • Section - An element of Customer Details that can be collapsed / expanded and includes a completed set of information that is grouped under a single title.
  • Component - A single line in the section that can have one of the pre-defined formats and be filled with the data from AAW.

How to add a section

To extend the Customer Details view, you need to first declare the initial state of the section in the Developer Console:

Example of initial state JSON for “Chat details”:

{
  "customerDetailsSections": [
    { 
      "title": "Example section",
      "components": [
        {
          "type": "button",
          "data": {
            "label": "Example button",
            "id": "example-button"
          }
        }
      ]
    }
  ]
}
  1. Log into the Agent App using your license.
  2. Go to Developer Console Apps and select your app or create a new one with the Agent App Widget template.
  3. Go to the Building blocks section of your app and create a new Agent App widget. You need to provide the Widget source URL, which can be either an URL pointing to the Web or to localhost (for eg. https://localhost:4000), if you want to use the local version of the widget. The URL will be used as an iframe source and should be publily available.
  4. Set the Widget placement to Chat details and provide the initial state JSON.
  5. The sections list can only be initialized once and they can’t be modified afterwarts. This means you can’t add or remove a section using the SDK later on. You can however modify the list of components inside a section later on.
  6. Go to Private installation and click the Install app button.
  7. Your widget should be now visible in the right sidebar of the Agent App chat view. Beware - if you did not set any icon for your widget, it may seem that it’s not there. To make sure, you can hover over the widget icon bar and check if there’s any clickable whitespace. You can set the icon in Developers Console.

How to update a section

Example of using the modifyCustomerDetailsSection method:

LiveChat.modifyCustomerDetailsSection(
  { 
    "title": "Example section",
    "components": [
      {
        "type": "button",
        "data": {
          "label": "Updated button",
          "id": "example-button"
        }
      }
    ]
  } 
);

To update a section you can use the LiveChat.modifyCustomerDetailsSection() method.


IMPORTANT

The title attribute in the root of the JSON acts as an ID to the section and cannot be changed. You need to provide it to identify which section you want to update.


Component types

Components are lego bricks which can be used for building a section.

Section

Section is a container for components.

Example of section component

{
    "title": "card with image",
    "components": [],
    "imgUrl": "https://www.gstatic.com/webp/gallery/4.jpg"
}
Property Required Type
title Yes string
components Yes array of components
imgUrl No string

Title

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

Example of title component

{
    "type": "title",
    "data": {
        "title": "title",
        "value": "value",
        "description": "description",
        "imgUrl": "https://www.gstatic.com/webp/gallery/4.jpg"
    }
}
Property Required Type Note
title Yes string
value No string
description No string
imgUrl No string
imgSize No string, one of: [“small”, “big”]` Default value: “big”
link No string URL added when title is a link.

Button

Simple button from design system.

Example of button component

{
    "type": "button",
    "data": {
          "id": "second-button",
          "label": "second button",
          "openApp": true
    }
}
Property Required Type Description
id Yes string
label Yes string
openApp No boolean Default value: false
Click events
Livechat.on("customer_details_section_button_click", ({ buttonId }) => {
  console.log(buttonId);
});

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",
    "inline": false
  }
}
Property Required Type Description
label No string
value No string
inline No boolean Default value: true

Example of link component

{
  "type": "link",
  "data": {
    "value": "click me",
    "url": "http://google.com",
    "inline": false
  }
}
Property Required Type Description
url Yes string
value No string
inline No boolean default: true

Line

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

Example of line component

{
    "type": "line"
}

Get the ID of the session

Returns the ID of the current extension session.

LiveChat.getSessionId();

Refresh the session ID

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

LiveChat.refreshSessionId();

Troubleshooting

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 'https://my.livechatinc.com/' 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.