MENU
Developers Consoleopen_in_new

Introduction

What is an Agent App Extension?

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

Sample use cases

There are number of ways you can utilize the extension:

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 Extension 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 extensions

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 & Silex

Set up the environment

git clone https://github.com/livechat/agent-app-sample-extension.git
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 https://github.com/livechat/agent-app-sample-extension-webpack.git
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 extension

You can host your extension 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 extension to an SSL-enabled host. If you go for the Webpack Example, you'll get the setup out of-the-box.

Developing your own extension

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

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

<link rel="stylesheet" href="//cdn.livechatinc.com/boilerplate/1.1.css">
<script src="//cdn.livechatinc.com/boilerplate/1.1.js"></script>

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

Fire LiveChat.init() method after body is loaded (e.g. using jQuery):

// If you authorize using "Basic authorization flow":
$(document).ready(function () {
    LiveChat.init();
});

// If you authorize using "Sign in with LiveChat":
$(document).ready(function () {
    LiveChat.init({
      authorize: false
    });
});

Layout & Styling

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

Authorization

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": agent@email.com,    // 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

// If you authorize using "Basic authorization flow":
LiveChat.init();

// If you authorize using "Sign in with LiveChat":
LiveChat.init({
  authorize: false
});

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.

LiveChat.getSessionId();

Refresh the session ID

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

LiveChat.refreshSessionId();

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 is removed from the Customers list
authorize the extension has been successfully authorized
authorize_error the extension has not been successfully authorized

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

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.