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