The Monitoring API is meant to enable 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.
Please view the separate Getting Started document for a step by step example of how to use this API.
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
identitiesarray. 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
loa1only 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 LiveEngage once installing an "Application" on the site. For more info on how applications are installed, please see this document.
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 -
identities, entry points, engagement attributes, client properties, et cetera.
The monitoring system creates a monitor session for the requesting device and replies with an eligible engagement, including the
sessionIdin the response.
The requesting device sends a request to the Report Resource, specifying the
sessionIdcreated in Step 2 in the Report method request, in order to report about the status of the engagement usage - displayed, clicked, et cetera.
The "Monitor API" is a stateful API. This (server-side) state is the monitor session, creating from a combination of a pair of parameters -
sessionId. In order to maintain consistency, maintain a proper funnel and avoid unnecessary load, it is highly advisable to provide the
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
sessionIdthat 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
sessionIdquery parameters, or the values provided are otherwise invalid. Therefore, a new monitor session was created (the new
sessionIdappear in the response body).
- 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
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
visitorIdof 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
visitorIdparameters may lead to an exceptional (abnormal) rate of monitor sessions' creation which will eventually be capped and will result in erroneous 5XX responses.
|Status code||Internal code||Description||Notes|
|400||33||illegal API version requested|
|400||5||request data is missing or invalid||request body is not a valid JSON ; input does not meet validation requirements; input cannot be parsed …|
|500||20||account not loaded or request timed out|
|500||18||internal server error||an unexpected server error occurred|
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.
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 Report 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
- Opening the Business Activity dashboard to additional sources (non-web = Mobile App, Facebook, SMS, etc.)
- Aligning goal tracking from non-web sources to the existing web based attribution model
- Adding source type filtering to the Business Activity, Goal Tracker, and Agent Activity dashboards
- Aligning the terminology of funnel metrics to serve all sources