MENU

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:

Use cases

There are number of ways you can utilise the extension:

Before you start

This guide describes the flow of development. Once your extension is ready to deploy let us know and we'll guide you to the production.

Layout & Styling

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

Example 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 extension should be available at https://localhost:3333.

You can now turn on the extension.

Core functionality

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

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

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

Extension hosting

You can either 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.

Turn on the extension

Paste following snippet inside the developers console:

App.collections.Integrations.add({
  id: 'sandbox',
  url: 'https://localhost:3333'
})

A green Sandbox App button should appear:

To activate the extension, login to the Agent App and simply paste this snippet within developers console in your browser of choice. The id has to be sandbox, but you can go with url of your own environment.

Your extension should be ready to use. In the upper right corner of Agent App appear a button labelled "Sandbox App".

Authorization

If you need to somehow authorize the user of your extension, you can utilize the following flow.

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

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

3. In return, Agent App sends a HTTPS POST request at https://your_ext_url/authorize/. Note 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 ordred to complete the flow, you should respond with 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 incoming events.

After the 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 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

LiveChat.init();

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 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 object width additional properties.

Customer profile displayed

Example data object for customer_profile event

{
  "id": "S126126161.O136OJPO1",
  "name": "Mary Brown",
  "email": "mary.brown@email.com",
  "chat": {
    "id": "NY0U96PIT4",
    "groupID": "42"
  }
}
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)

Customer profile hidden

Example data object for customer_profile_hidden event

{
  "id": "S126126161.O136OJPO1"
}
Property Description
id Unique ID of a visitor