The Agent Activity API is intended for reporting and information purposes — not for real-time decisions, such as routing. Agent Activity api has sla of 1 hour.
In V1: Each page in the API response is limited to 20 state changes * limit parameter * query days. For example, if the limit is set to 10 (agents), 1-day query then limitation per page = 200 state changes.
In case of excessive state changes, some of the states/agents may be truncated based on the maximum state’s limitation.
In v2 the API response contains all state changes in a flat response (not grouped by agent). This has been done to resolve the limitation in V1.
Introduction
The Agent Activity API provides an historical raw data solution to track agent adherence on both messaging and chat channels.
The API allows its consumer to track the agent login and logout hours, and also the state changes during the login hours, including predefined custom states as defined by the brand.
Note: At this point, away states are not calculated based upon productive and non-productive away status.
The API is based on HTTPS GET functionality, and all data is returned in a JSON format.
Getting started
A few things you'll need to get started with this API:
-
Retrieve your domain. Use the LivePerson Domain API to retrieve this information by providing the following service name:
- agentActivityDomain
-
This API requires authorization using machine-to-machine authorization.
-
For a machine-to-machine authorizion using OAuth 1.0 App Keys OAuth 2.0 Client Credentials flow
- OAuth 1.0 App Keys — follow the instructions, to create and use an App key.
This API requires authorization using an API key methodology.
-
Follow the instructions, to create and use an API key.
-
To access this API, the API key must have the
Data → Workforce Management → Agent Status Changespermission.- OAuth 2.0 Client Credentials flow — follow the instructions, to register an OAuth 2.0 application and generate a JWT access token (Using version 2 of the Authorization API).
When registering an OAuth 2.0 application for using the Agent Activity API, use one of the following scopes based on the endpoint
-
For a machine-to-machine authorizion using OAuth 1.0 App Keys OAuth 2.0 Client Credentials flow
| Endpoint | External Privilege/Scope |
|---|---|
| /api/account/{account}/agent-segments | wfm.agent.activity.read.external, wfm.actual.handle.time.read.external |
| /api/account/{account}/agent-segments/breakdown | wfm.actual.handle.time.export.external |
| /api/account/{account}/agent-segments/files | wfm.actual.handle.time.export.external |
| /api/account/{account}/interval-metrics | wfm.agent.activity.read.external |
| /api/account/{account}/status-changes | wfm.agent.activity.read.external |
| /api/v2/account/{account}/status-changes | wfm.agent.activity.read.external |
-
Note the API terms of use.
-
When using this API, it is recommended that you implement our Retry Policy.
Use cases
-
Evaluate how much time agents spend in each away state.
-
Measures agent schedule adherence by monitoring agent login and logout behavior.
-
Tracking agent behavior by monitoring agent status updates.
-
Tracking and assessing agent and team productivity and correlating against other productivity metrics (e.g. online hours, quantity of closed conversations.