Introduction

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.

Use cases

Widgets are primary elements of 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 a part of 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 REST API to do basically anything with the visitor, agent, or chat.

Important notes

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 REST API documentation.

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

To add a widget, follow the steps below. If you don’t have your own widget, you can use one of our Sample Apps.

  1. Go to LiveChat Developers Console.
  2. Click New app + and follow the app wizard.
  3. In the Display details tab, enter your application name, description, and icon.
  4. Go to Agent App Widgets -> New Widget +.
    • Enter the Widget source URL.
    • Select the desired location as the Widget placement.
  5. Go to the Private installation tab and install the app on your account.

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

Sample Widgets

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.

See the repo

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.

If you’ve already developed a widget, you’re probably using the Widget SDK. Keep in mind that it is no longer actively maintained. However, we provide backward compatibility for this SDK, so your existing widgets should still be working properly. When building new widgets, we encourage you to use the Agent App SDK instead.

Accessing LiveChat data

You can leverage the OAuth2.0 authorization flow to access data from the REST API. 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

Section is a container for components.

Example of a 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 the given data.

Example of a 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 component

Example of a 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

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 a 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 a line component

{
    "type": "line"
}

Agent App SDK

The Agent App SDK is currently the primary way to develop your own widgets.

Installation

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="https://unpkg.com/@livechat/agent-app-sdk@latest/dist/agentapp.umd.min.js"></script>
<script>
  LiveChat.createDetailsWidget().then(function(widget) {
    // do something with widget
  });
</script>

Usage

The usage of the SDK depends on the type of widget you want to use. Refer to the specific instructions for available widget types.

Neverthless, all widgets created with the SDK share a common interface, which lets you listen to 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
widget.off("event", handleEvent);

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

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

Events

customer_profile

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 to the customer profile changes:

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

The customer profile object will have the following shape:

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, customers, archives
geolocation Object containing detailed information about customer’s geolocation

customer_details_section_button_click

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

Property Description
buttonId The 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
});

Actions

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

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

MessageBox

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

Actions

Set a message to be stored by MessageBox

putMessage(msg: IRichMessage | string): 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 regular message type as string or rich messages. The latter must implement the IRichMessage interface.

Set a message to be stored by MessageBox

  const richMessage = {
    template_id: "cards",
    elements: [
      {
        title: "My cat photo",
        image: "imgs/john-the-cat.jpg"
      }
    ]
  };

  widget.putMessage(richMessage);

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

Widget SDK

Please remember that the Widget SDK is considered deprecated and you should use the Agent App SDK instead.

To use the JavaScript API you should import the Agent App Widget SDK. Note that this document describes the API for 1.3.x version of the package. If you’re using version 2.x or higher, please refer to the README file located in the Github repository.

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

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

Import the SDK and fire the LiveChat.init() method

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

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

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.

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 with 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 a given message at the end of the current conversation input window or into the ticket window. Agent has to confirm sending the 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.

LiveChat.getSessionId();

Refresh the session ID

Deletes the ID of the previous session and requests 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.