Please note that this API relates to LivePersons legacy chat product which receives limited support and will be deprecated in the future.

It is recommended to build future integrations on top of LivePersons Key Messaging Metrics API instead.

Retrieves Agent State Distribution data, which includes the following states:

  • Logged in (total of all states)
  • Online
  • Away (with breakdown of multiple Away state reasons)
  • Back soon

For each state, the following is indicated:

  • Time spent chatting
  • Time spent not chatting
  • Time spent logged in and chatting concurrently with the maximum allowed chats

If no custom Away state reasons are configured, the 'reasons' field will be returned as an empty array.

Note:

  1. These methods are subject to Rate-Limiting policies. This means that the maximum number of concurrent requests is limited on the server side. As most incoming requests are measured in seconds, the likelihood of your requests actually encountering an issue is rare; however, if you do encounter a limit, you can expect to receive a 429 status code in an error response from the server.

If your request is throttled in this manner, it is recommended that you provide a window of at least 1 second in between subsequent request retries. Clients who submit "bursty" traffic patterns to UMS may face rate-limiting issues, so it is recommended to smoothen traffic to a more distributed pattern whenever possible.

  1. Agent states are calculated by the millisecond but presentation is in seconds. Therefore, there might be a 1 second difference between agent states and agent states total.

Request

Method URL
GET https://{domain}/operations/api/account/{accountID}/agentactivity?timeframe=&agentIds=&interval=&v=
  • Use POST request to pass long list of agentIds
Method URL BODY (Json)
POST https://{domain}/operations/api/account/{accountID}/agentactivity {"timeframe":"<timeframe in minutes>", "agentIds":"<comma separated agent ids list>", "interval":"<interval size in minutes>", "v":"<version>" }
  • Example: {"timeframe":"1440","v":"1","agentIds":"2152260212,2152260212","interval":"1440"}

URL Parameters

Name Description Type / Value Required
timeframe The time range (in minutes) in which the data can be filtered. Where end time = current time, and start time = end time – timeframe. numeric required
agentIds When provided, metrics on the response will be grouped by the requested agents' IDs. If there is no data for the specified agents, an object will be returned with an empty value for key: "metricsPerAgent" with a map including all metrics valued zero. To retrieve all active agents for the time period, use agentIds=all. numeric, comma separated required
v Version of API, for example, v=1. numeric required
interval Interval size in minutes (the minimum value is five minutes). When provided, the returned data will be aggregated by intervals of the requested size. The interval has to be smaller or equal to the time frame, and also a divisor of the time frame.
Example:
timeframe=60&interval=30 (correct)
timeframe=60&interval=61 (bad request)
timeframe=60&interval=31 (bad request)
numeric optional

Response

JSON Example

Request by v=1 and timeframe=120 and agentIds=all (including two agentIds: 2 and 3).

    {
      "agentsMetrics": {
        "metricsPerAgent": {
          "2": [
            {
              "id": 2,
              "name": "Online",
              "value": {
                "total": 4714,
                "chatting": 0,
                "notChatting": 4714,
                "chattingInMaxConcurrency": 0
              }
            },
            {
              "id": 3,
              "name": "Back in 5",
              "value": {
                "total": 2361,
                "chatting": 2361,
                "notChatting": 0,
                "chattingInMaxConcurrency": 0
              }
            },
            {
              "reasons": [
              {
                  "id": "2642559712",
                  "value": {
                      "total": 72,
                      "chatting": 0,
                      "notChatting": 72,
                      "chattingInMaxConcurrency": 0
                  }
              },
              {
                  "id": "2642559112",
                  "value": {
                      "total": 53,
                      "chatting": 0,
                      "notChatting": 53,
                      "chattingInMaxConcurrency": 0
                  }
              }
              ],
              "id": 4,
              "name": "Away",
              "value": {
                "total": 0,
                "chatting": 0,
                "notChatting": 125,
                "chattingInMaxConcurrency": 0
              }
            },
            {
              "id": -1,
              "name": "Logged in",
              "value": {
                "total": 7200,
                "chatting": 2486,
                "notChatting": 4714,
                "chattingInMaxConcurrency": 0
              }
            }
          ],
          "3": [
            {
              "id": 2,
              "name": "Online",
              "value": {
                "total": 2486,
                "chatting": 2486,
                "notChatting": 0,
                "chattingInMaxConcurrency": 0
              }
            },
            {
              "id": 3,
              "name": "Back in 5",
              "value": {
                "total": 4714,
                "chatting": 0,
                "notChatting": 4714,
                "chattingInMaxConcurrency": 0
              }
            },
            {
              "reasons": [],
              "id": 4,
              "name": "Away",
              "value": {
                "total": 0,
                "chatting": 0,
                "notChatting": 0,
                "chattingInMaxConcurrency": 0
              }
            },
            {
              "id": -1,
              "name": "Logged in",
              "value": {
                "total": 7200,
                "chatting": 2486,
                "notChatting": 4714,
                "chattingInMaxConcurrency": 0
              }
            }
          ]
        },
        "metricsTotals": []
      }
    }

Request by v=1 and timeframe=120 and agentIds=all and interval=60 (including two agentIds: 2 and 3).

    {
      "metricsByIntervals": [
        {
          "timestamp": 1404226200000,
          "metricsData": {
            "agentsMetrics": {
              "metricsPerAgent": {
                "2": [
                  {
                    "id": 2,
                    "name": "Online",
                    "value": {
                      "total": 3268,
                      "chatting": 0,
                      "notChatting": 3268,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": 3,
                    "name": "Back in 5",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                   "reasons": [
                   {
                       "id": "2642559712",
                       "value": {
                           "total": 100,
                           "chatting": 0,
                           "notChatting": 100,
                           "chattingInMaxConcurrency": 0
                       }
                   }
                   ],
                    "id": 4,
                    "name": "Away",
                    "value": {
                      "total": 100,
                      "chatting": 0,
                      "notChatting": 100,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": -1,
                    "name": "Logged in",
                    "value": {
                      "total": 3368,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  }
                ],
                "3": [
                  {
                    "id": 2,
                    "name": "Online",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": 3,
                    "name": "Back in 5",
                    "value": {
                      "total": 3368,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "reasons": [],
                    "id": 4,
                    "name": "Away",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": -1,
                    "name": "Logged in",
                    "value": {
                      "total": 3368,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  }
                ]
              },
              "metricsTotals": []
            }
          }
        },
        {
          "timestamp": 1404222600000,
          "metricsData": {
            "agentsMetrics": {
              "metricsPerAgent": {
                "2": [
                  {
                    "id": 2,
                    "name": "Online",
                    "value": {
                      "total": 1376,
                      "chatting": 0,
                      "notChatting": 1376,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": 3,
                    "name": "Back in 5",
                    "value": {
                      "total": 2224,
                      "chatting": 2224,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "reasons": [],
                    "id": 4,
                    "name": "Away",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": -1,
                    "name": "Logged in",
                    "value": {
                      "total": 3600,
                      "chatting": 2224,
                      "notChatting": 1376,
                      "chattingInMaxConcurrency": 0
                    }
                  }
                ],
                "3": [
                  {
                    "id": 2,
                    "name": "Online",
                    "value": {
                      "total": 2224,
                      "chatting": 2224,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": 3,
                    "name": "Back in 5",
                    "value": {
                      "total": 1376,
                      "chatting": 0,
                      "notChatting": 1376,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "reasons": [],
                    "id": 4,
                    "name": "Away",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": -1,
                    "name": "Logged in",
                    "value": {
                      "total": 3600,
                      "chatting": 2224,
                      "notChatting": 1376,
                      "chattingInMaxConcurrency": 0
                    }
                  }
                ]
              },
              "metricsTotals": []
            }
          }
        },
        {
          "timestamp": 1404219000000,
          "metricsData": {
            "agentsMetrics": {
              "metricsPerAgent": {
                "2": [
                  {
                    "id": 2,
                    "name": "Online",
                    "value": {
                      "total": 232,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": 3,
                    "name": "Back in 5",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "reasons": [],
                    "id": 4,
                    "name": "Away",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": -1,
                    "name": "Logged in",
                    "value": {
                      "total": 232,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  }
                ],
                "3": [
                  {
                    "id": 2,
                    "name": "Online",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": 3,
                    "name": "Back in 5",
                    "value": {
                      "total": 232,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "reasons": [],
                    "id": 4,
                    "name": "Away",
                    "value": {
                      "total": 0,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  },
                  {
                    "id": -1,
                    "name": "Logged in",
                    "value": {
                      "total": 232,
                      "chatting": 0,
                      "notChatting": 0,
                      "chattingInMaxConcurrency": 0
                    }
                  }
                ]
              },
              "metricsTotals": []
            }
          }
        }
      ],
      "agentsMetrics": {
        "metricsPerAgent": {},
        "metricsTotals": []
      }
    }

Elements in the Response

Name Description Type / Value
agentsMetrics An object that represents the agents' data. It includes one member: • metricsPerAgent — A list of agent/s' id/s that were sent in the request with their metrics data. If there is no data for any agent/s, this member will have an empty object as value. If there is no data for a specific agent, it won't be included in this list. When interval size is provided in the request, the response will have the agentsMetrics element in each interval. There will also be an agentsMetrics element at the end of the response, representing the data of the whole requested time frame (totals of all intervals). element
metricsTotals When agentIDs are provided: Total metrics for all requested agents. When agentIDs are not provided: The site metrics. When interval is provided: Total metrics for all requested intervals. If agentIds are requested and there is no data for any of them, this element will still include all of the metrics with value zero. Note: Totals are not currently supported. element
Timestamp When interval size is provided in the request, the response will be aggregated by intervals. The timestamp is the UTC timestamp in milliseconds representing the end time on the interval. Example: Interval size: 30 min. Interval start and end time: 26/03/2014 07:30:00 - 26/03/2014 08:00:00. Timestamp: 1395820800000. Intervals are rounded up to 5 minutes. Consequently: • The latest interval timestamp will be rounded up. Example: Now: 08:07. Last interval end time: 8:10. • The earliest interval will include only the remainder of the requested timeframe — between the start of the timeframe (now – timeframe) and the end of the earliest interval. Example: Now: 8:07. Request parameters: timeframe=20&interval=10 (20 minutes in 10 minutes intervals). Response from and to time: 7:47 – 8:07 → 20 minutes. Response intervals: 8:00 – 8:10 (10 minutes. actual 7 minutes because now is 8:07). 7:50 – 8:00 (10 minutes). 7:47 – 7:50 (only 3 minutes). long
id The ID of the agent state: logged in = -1 online = 2 back in 5 = 3 away = 4 integer
name The name of the agent state: "Logged in", "Online", "Back soon" and "Away" string
value This element contains all the values for a specific distribution agent state. element
total The total time the agent was in this state (seconds). long
chatting The total time the agent was chatting in this state (seconds). long
notChatting The total time the agent was not chatting in this state (seconds). long
chattingInMaxConcurrency The amount of time the agent was chatting concurrently with the maximum allowed chats in this state (seconds). long
reasons An array representing the breakdown of the 'Away' state to multiple away state reasons element
id (reasons) The ID of the away reason string