Introduction

The Monitoring API enables consumer monitoring and engagement flows. By combining monitoring capabilities with our Campaigns feature, you can display tailored engagements to the right consumer at the right time. For example, in order to present a "Click to Message" button (an engagement) with an updated state of availability (a certain number of agents online, a skill being available and so on), you can access the specific engagement using this API and display it to the consumer only if it is available, for a certain type of consumer, at a certain time of day and so on. Thus, the Monitoring API allows you to report data about the consumer and get information back about engagements and campaigns relevant to specific consumers.

Getting Started

Please view the separate Getting Started document for a step by step example of how to use this API.

Terminology

• Consumer device: The device the consumer is messaging from, for example: Mobile, desktop.

• Monitor session: The server-side state of the current consumer device session.

• consumerId (deprecated — use identities instead): The brand's identifier for the consumer (e.g, email, phone number or a generated unique id).

• identities: In order to target a specific consumer and their engagement, the identity of the consumer must be passed to the API using the identities array. The information in this array should match the values assigned to the user when they authenticate on your site. That, upon authentication on your site (and according with the OpenID RFC), each visitor should be assigned values to the following keys, values which are later passed to the API. Each array consists of 3 keys:

  • iss: Issuer, who identified the consumer — usually the brand.

  • acr: Authentication Context Class Reference, the level of the authentication. Currently, we support the level loa1 only and thus only it should be used here, based on NIST-2 (2013).

  • sub: Unique and non-guessable identifier of the consumer (email and phone number are not good candidates since they can be guessed by an attacker, and might be recycled and move between consumers).

When the API receives the identities array, it matches the keys to the consumer's information on your account. If the values match (mainly the sub field, which identifies the consumer), the API will return the existing engagement. If there is no match, a new engagement will be presented.

• visitorId: The LivePerson identifier to the current consumer device.

• sessionId: The LivePerson identifier to the current monitor session of this consumer device.

• appInstallationId: The app key generated by Conversational Cloud once installing an "Application" on the site. For more info on how applications are installed, please see this document.

Sample Flow

1. Your environment (app/connector) sends a request to the Engagement Resource. To the request you can add the following information regarding the consumer's activity within your brand's environment — consumerId or identities, entry points, engagement attributes, client properties, et cetera.

2. The monitoring system creates a monitor session for the requesting device and replies with an eligible engagement, including the visitorId and a sessionId in the response.

3. The requesting device sends a request to the Report Resource, specifying the visitorId and the sessionId created in Step 2 in the Report method request, in order to report about the status of the engagement usage — displayed, clicked, et cetera.

Notes

The "Monitor API" is a stateful API. This (server-side) state is the monitor session, creating from a combination of a pair of parameters - visitorId and sessionId. In order to maintain consistency, maintain a proper funnel and avoid unnecessary load, it is highly advisable to provide the sessionId and visitorId that are created in the first request for a specific device session in all subsequent requests to all resources of the "Monitor API".

• A response code of 200 (OK) means that the values of the visitorId and a sessionId that were provided are valid — the pair represents a valid monitor session.

• A response code of 201 (CREATED) means that no values were provided for the visitorId and/or sessionId query parameters, or the values provided are otherwise invalid. Therefore, a new monitor session was created (the new visitorId and sessionId appear in the response body).

Protocols

• HTTP based: All information (both client to server and server to client) will be passed using an HTTP request-response model.
• HTTPS only: Only secured (SSL) requests will be handled.
• JSON based: All data (both directions) will be passed using a valid JSON. Note: Clients should not rely on a closed set of attributes since the format is JSON ("Forward Compatibility").

Authentication and Authorization

This API is public. When specifying appInstallationId and accountId, the API does not require any further authentication or authorization beyond the basic ID validation.

Usage, Capping and Error handling

• In order to avoid unnecessary load, it is highly advisable to provide the sessionId and visitorId of the consumer device in all subsequent requests (e.g. the 2nd request onwards) spanning the current monitor session.

• Not complying to the above usage of the sessionId and visitorId parameters may lead to an exceptional (abnormal) rate of monitor sessions' creation which will eventually be capped and will result in erroneous 5XX responses.

Response Errors

Use Cases

• Customized Mobile Experience - If you're looking to build your own customized mobile experience in conjunction with our other APIs, you can enrich those APIs with monitoring. This API would enable you to do so independently by reporting on engagements.

• Report SDEs via the API - if you're already using other LivePerson APIs to build custom solutions, you'd need to work with this API directly to enable communication with those custom solutions.

Reporting funnel

Note: The reporting funnel relies on terms and definitions explained as part of the Report method of this API. Please visit this link for more information on these terms.

Today, the Analytics Builder offers a set of operational and funnel reports which instill visibility into campaign performance and agent performance against campaign goals. These reports currently cover both Chat and Messaging conversation types from Web sources.

Now a selection of dashboards has been released to reflect on the performance of campaigns which include a mix of engagements from web and non-web source.

This expansion includes

1. Opening the Business Activity dashboard to additional sources (non-web = Mobile App, Facebook, SMS, etc.)
2. Aligning goal tracking from non-web sources to the existing web based attribution model
3. Adding source type filtering to the Business Activity, Goal Tracker, and Agent Activity dashboards
4. Aligning the terminology of funnel metrics to serve all sources