Agent Activity API — Get Status Changes | LivePerson Developer Center

This method provides raw data about agent states changes.

If you have not done so yet, see the overview of this product.

Request

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.
v2: All states are returned in a flat response (not grouped by agent).

Note that this affects the limit and offset parameters (in v1 they refer to an agent while in v2 to records).

Method	URL
GET	https://{domain}/api/v2/account/{accountID}/status-changes?source={source}

Request Query Parameters

Name	Description	Type	Required?	Default	Notes
v	Version of the API (1 or 2)	String	No	The default is v1	v1: returns the records grouped by an agent with a limitation of the number of records in every page (see the note above). v2: Returns the records in a flat structure and not grouped by an agent. No limitation on the number of records in every page
source	This describes the originator of the call	String	Required
from	This filters the results to status changes occurred within the timeframe between `from` and `to`	RFC 3339 date-time string	Optional	24 hours prior to request time	If provided, `to` must also be provided Minimum value: 6 months prior to request time
to	This filters the results to status changes occurred within the timeframe between `from` and `to`	RFC 3339 date-time string	Optional	request time	If provided, `from` must also be provided Maximum timeframe between `from` and `to`: 1 month
agentId	This filters the results to status changes of the agent with the specified LivePerson ID	number	Optional		If provided, `empId`,`groupId` must not be provided If neither `agentId`,`empId`,`groupId` are provided, all agents will be returned
groupId	This filters the results to status changes of the group with the specified group ID	number	Optional		If provided, `empId`,`agentId` must not be provided If neither `agentId`,`empId`,`groupId` are provided, all agents will be returned
empId	This filters the results to status changes of the employee with the specified employee ID	string	Optional		If provided, `agentId`, `groupId` must not be provided If neither `agentId`,`empId`,`groupId` are provided, all agents will be returned
limit	This limits the number of records in the response to this value	number	Optional	V1: 50 Agents V2: 1000 state changes	Maximum value: V1: 100 Agents V2: 5000 state changes
offset	This allows getting more results in case you have more records than `limit`	number	Optional	0	Example: V1: offset = 20 will skip the first 20 agents V2: offset = 20 will skip the first 20 state changes

Response

V1

Property Name	Description	Type	Notes
timeframe		object
startTime	The start of the requested time frame	RFC 3339 date-time string
startTimeL	Query start date (same as above) in Epoch time format	long — Epoch time in milliseconds
endTime	The end of the requested time frame	RFC 3339 date-time string
endTimeL	Query end date (same as above) in Epoch time format	long — Epoch time in milliseconds
agentsInfo		array
agentId	Agent's LivePerson ID	number
employeeId	Agent's employee ID	string
agentLoginName		string
agentUserName		string
agentGroupId	The ID of the group the agent is assigned to	number
statusChangeHistory		array
time	Time of this status change	RFC 3339 date-time string
sessionId	Agent unique session	number	sessionId is currently missing from the first 2 events. To link these 2 events to a session, you will need to look for the following event, based on its timestamp and where is sequence =2
sequenceNumber	Sequential number of this status change within the session	number	Login event will always have a sequnceNumber = -1. The system default state after login will always have a sequenceNumber = 1.
statusType	Type of status change	number	1 — status changed, see `statusSubType` 3 — login 4 — logout
statusSubType	Subtype of status change with `statusType`=1	number	1 — offline 2 — online 3 — back soon 4 — away
statusReasonId	Identifier of optional custom reason for the status change	number	-1 if no custom reason was provided by the agent
statusReasonText	Optional custom reason for the status change	string	null if no custom reason was provided by the agent
prevStatusChangeTime	Time of this agent’s previous status change	RFC 3339 date-time string	Currently missing from the logout event and from the default status that is set after login
metadata	Response-related metadata	Object
references	An array of links to the pages in the response	Array
rel	Pagination: The name of the link. This is based on the “offset” and “limit” elements	string	Possible values: self — the link to the same page in the query next — link to the next page of results previous — link to the previous page of results first — link to the first page of the query results last — link to the last page of the query results
href	Pagination: The specific link for each one of the above values	string	The values: self and first will always be returned whereas the others will be returned if there is more than 1 page in the response

Response Example (V2)

{
  "_metadata": {
    "references": [{
      "rel": "self",
      "href": "http://[doamin].agent-activity.liveperson.net/api/v2/account/[account]/status-changes?from=2022-02-24T00:00Z&to=2022-03-16T10:00Z&offset=0&limit=50&source=postman"
    },
      {
        "rel": "first",
        "href": "http://[doamin].agent-activity.liveperson.net/api/v2/account/[account]/status-changes?from=2022-02-24T00:00Z&to=2022-03-16T10:00Z&offset=0&limit=50&source=postman"
      }
    ]
  },
  "timeframe": {
    "startTime": "2022-02-24T00:00:00Z",
    "endTime": "2022-03-16T10:00:00Z",
    "startTimeL": "1645660800000",
    "endTimeL": "1647424800000"
  },
  "stateChanges": [
    {
      "agentId": 3252247132,
      "employeeId": "543acbc",
      "agentLoginName": "test@liveperson.com",
      "agentUserName": "nirle",
      "agentGroupId": 12345,
      "time": "2022-03-13T10:18:51.625Z",
      "sessionId": -1,
      "sequenceNumber": -1,
      "statusType": 3,
      "statusSubType": 0,
      "statusReasonId": 0,
      "statusReasonText": "",
      "prevStatusChangeTime": null
    },
    {
      "agentId": 3252247132,
      "employeeId": "543acbc",
      "agentLoginName": "test@liveperson.com",
      "agentUserName": "nirle",
      "agentGroupId": 12345,
      "time": "2022-03-13T10:18:51.625Z",
      "sessionId": -1,
      "sequenceNumber": 1,
      "statusType": 1,
      "statusSubType": 2,
      "statusReasonId": 0,
      "statusReasonText": "",
      "prevStatusChangeTime": null
    },
    {
      "agentId": 3252247132,
      "employeeId": "543acbc",
      "agentLoginName": "test@liveperson.com",
      "agentUserName": "nirle",
      "agentGroupId": 12345,
      "time": "2022-03-13T10:12:59.118Z",
      "sessionId": 30376039,
      "sequenceNumber": 2,
      "statusType": 1,
      "statusSubType": 1,
      "statusReasonId": 0,
      "statusReasonText": "",
      "prevStatusChangeTime": "2022-03-13T10:10:27.983Z"
    }

  ]
}

V2

Property Name	Description	Type	Notes
timeframe		object
startTime	The start of the requested time frame	RFC 3339 date-time string
endTime	The end of the requested time frame	RFC 3339 date-time string
stateChanges		array
agentId	Agent's LivePerson ID	number
employeeId	Agent's employee ID	string
agentLoginName		string
agentUserName		string
agentGroupId	The ID of the group the agent is assigned to	number
time	Time of this status change	RFC 3339 date-time string
sessionId	Identifier of the session during which this status change took place	number
sequenceNumber	Sequential number of this status change within the session	number
statusType	Type of status change	number	1 - status changed, see `statusSubType` 3 - login 4 - logout
statusSubType	Subtype of status change with `statusType`=1	number	1 - offline 2 - online 3 - occupied 4 - away
statusReasonId	Identifier of optional custom reason for the status change	number	-1 if no custom reason was provided by the agent
statusReasonText	Optional custom reason for the status change	string	null if no custom reason was provided by the agent
prevStatusChangeTime	Time of this agent’s previous status change	RFC 3339 date-time string	null if value is missing

Response Example

{
    "timeframe": {
        "startTime": "2021-08-25T15:00:00Z",
        "endTime": "2021-08-25T23:59:00Z"
    },
    "stateChanges": [
        {
            "agentId": #,
            "employeeId": "1234567",
            "agentLoginName": "testuser",
            "agentUserName": "test user",
            "agentGroupId": 118643451,
            "time": "2021-08-25T00:17:59.747Z",
            "sessionId": 95354544,
            "sequenceNumber": 1,
            "statusType": 1,
            "statusSubType": 4,
            "statusReasonId": 1,
            "statusReasonText": "Training",
            "prevStatusChangeTime": "2021-08-25T00:15:59.747Z",
        },
        ...
    ]
}

Error Codes

See Error Codes

Faster Better answers through AI

Get Status Changes