General

The key messaging metrics API retrieves core messaging metrics at the account, skill or group level, for up to the last 24 hours.

Combining this information with other data sources enables you to create your own customized real-time dashboard. Here are some example use cases of the API, that can assist you in analyzing your contact center performance:

  • Track how many of your agents are currently available (online, away, back soon) at the skill or group level

  • Track how many conversations were resolved and how

  • Track the response times of agents by group or skill

  • Track consumers waiting times by group or skil

  • Retrieve metrics at the group level and automatically include their sub groups

The API is being used today in the LivePerson Conversational Cloud to display the agent manager workspace:

Note: This method is subjected to Rate Limiting. User manager should not send more than X concurrent request (to be defined) and no more than Y request per minute (to be defined). Any additional requests might be rejected with a 429 Status Code.

Request

Method URL
POST https://{domain}/manager_workspace/api/account/{accountId}/metrics?offset=0&limit=50&sort=closedConversations:desc

URL Parameters

Name Description Type/Value Required Notes
sort Sort the results based on a given metric in a predefined order. string Optional
Valid sort values:
agentLoad
humanAgentLoad
closedConversations
avgTimeToResponse
avgTimeToFirstResponseFirstAssignment
avgWaitTime
avgWaitTimeFirstResponse
assignedConversations
activeConversations
onlineAgents
awayAgents
backSoonAgents
Valid order values:
asc/desc
Default sort:
key:asc
offset The offset specifies from which record to retrieve the data. numeric Optional Default is 0
limit Max amount of keys (skillIds/agentGroupIds) to be retrieved in the response. numeric Optional Default is 50. Max value is 50.

BODY Parameters

Name Description Type/Value Required Notes
filters Contains parameters to filter by. Container Required See detailed description below
metricsToRetrieveByTime List of metrics that are calculated for the given time range Array <String> Optional Valid values:
avg_wait_time
avg_wait_time_first_response
avg_time_to_response
avg_time_to_first_response_first_assignment
closed_conversations
closed_by_agent
closed_by_consumer
auto_closed
metricsToRetrieveCurrentValue List of metrics retrieving the current value, not influenced by time Array <String> Optional Valid values:
assigned_conversations
active_conversations
agent_load
human_agent_load
human_online_load
online_agents
back_soon_agents
away_agents
available_slots
responseSections Represents whether we should return the "all" section, "groupBy" section or both. Array <String> Optional Valid values: all, groupBy. Default value — both sections are returned.
groupBy Field according to which all of the metrics should be grouped. String Optional Valid values: skillId, agentGroupId. In case responseSections contains groupBy, a groupBy value must be returned in order to retrieve grouped metrics.

filters

filters info

Name Description Type/Value Required Notes
time {from, to} Represents events time. long — epoch time in milliseconds. Required Including bounds. From/to value is rounded to the last/next 1 minutes, respectively. Time range is limited up to the last 24 hours. Note: This field is required, even if you are not requesting metrics from the metricsToRetrieveByTime section but only asking for the metricsToRetrieveCurrentValue section.
agentIds An array of agent IDs. Array <String> Optional  
agentGroupIds An array of agent group IDs. Array <String> Optional  
skillIds An array of skill IDs. Array <String> Optional  
userTypes Type of the user conducting of the conversation. alphanumeric Optional Valid values: HUMAN, BOT.
includeSubGroups When this is set to true, any metric retrieved for a specific group will include the total value of the metric on the group level, including its sub-groups. Default value is set to false. boolean Optional  

Request body — JSON example:

{
    "filters": {
        "time": {
            "from": 1591951787590,
            "to": 1591955386814
        },
        "userTypes":["HUMAN"]
    },
    "groupBy" : "agentGroupId",
    "responseSections": [
       "groupBy"
    ],
    "metricsToRetrieveCurrentValue": [
        "assigned_conversations",
	"human_agent_load"
    ],
    "metricsToRetrieveByTime": [
        "avg_wait_time",
        "avg_time_to_response",
        "avg_wait_time_first_response",
        "avg_time_to_first_response_first_assignment",
        "closed_conversations"
    ]
}

Response

Name Description Type/Value
metadata All response-related Metadata. container
groupBy Contains grouped by metrics values based on the given groupBy and metrics parameters. container
all Contains metrics values for all relevant agents. container

metadata info

Name Description Type/Value
count Number of groups returned based on the groupBy parameter. In case groupBy section is not passed in the request body, count will be set to zero numeric

groupBy info

Name Description Type/Value
groupByField The name of the field by which the metrics data is grouped (agentId or agentGroupId) String
groups A list of all the groups with the required metrics data Container

groups info

Name Description Type/ Value Notes
key The value the metrics data was grouped by.If groupBy was set to skillId, then the key holds the skill id. If the groupBy was set to agentGroupId, then the key holds the group id. String  
keyDescription The descriptive value the metrics data was grouped by.If groupBy was set to skillId, then the keyDescription holds the skill name. If the groupBy was set to agentGroupId, then the keyDescription holds the group name. Notice: if ID was not successfully associated with any name, return "NA" String  
metrics A list of all the metrics with their value Container  

metrics info

Name Description Type/ Value Notes
assignedConversations The number of open conversations currently assigned to the agent. limited to conversations which started within the past 30 days. Long  
activeConversations The number of open conversations currently handled by the agent. limited to conversations which started within the past 30 days. Long  
agentLoad The total weight of assigned conversations as a percentage of the maximum concurrent conversations of all agents, including bots. Double  
humanAgentLoad The total weight of assigned conversations as a percentage of the maximum concurrent conversations of all human agents. Double  
humanOnlineLoad The total weight of assigned conversations as a percentage of the maximum concurrent conversations of all human online agents. Double  
availableSlots The total number of available conversations slots to take incoming conversations from the queue (the "Supply"). In case the response is grouped by skilldIds, same slots will be counted under all the skills an agent is assigned to. Long  
onlineAgents Agents currently in the ONLINE state. Long  
backSoonAgents Agents currently in the BACK SOON state. Long  
awayAgents Agents currently in the AWAY state. Long  
avgWaitTime The average time in millis consumers wait for a human agent response in a conversation. Attributed to the skill and group at the time of response. Double  
avgWaitTimeFirstResponse The average time in millis consumers wait for the first human response in a conversation. Attributed to the skill and group at the time of response. Double  
avgTimeToResponse The average time in millis it takes a human agent to send a message to the consumer from the time the agent was assigned to the conversation. Attributed to the skill and group at the time of response. Double  
avgTimeToFirstResponseFirstAssignment The average time in millis it takes a human agent to respond to the first message from a consumer, from the time the agent was assigned to the conversation. Measured from the first human agent message sent in a new conversation.Attributed to the skill and group at the time of response. Double  
closedConversations The number of conversations closed within the selected timeframe by the agent, system or consumer. Long  
closedByAgent The number of conversations closed by the agent within the selected timeframe. Long  
closedByConsumer The number of conversations closed by the consumer within the selected timeframe. Long  
autoClosed The number of conversations automatically closed within the selected timeframe. Long  

all info

Contains list of metrics with their values — same as in metrics info.

Response DTO — JSON example:


{
     "metadata": {
        "count": 3,
        "first": {
            "rel": "first",
            "href": "https://localhost:8082/manager_workspace/api/account/le79144597/metrics?offset=0&limit=1&sort=closedConversations:desc"
        },
        "prev": {
            "rel": "prev",
            "href": "https://localhost:8082/manager_workspace/api/account/le79144597/metrics?offset=0&limit=1&sort=closedConversations:desc"
        },
        "self": {
            "rel": "self",
            "href": "https://localhost:8082/manager_workspace/api/account/le79144597/metrics?offset=1&limit=1&sort=closedConversations:desc"
        },
        "next": {
            "rel": "next",
            "href": "https://localhost:8082/manager_workspace/api/account/le79144597/metrics?offset=2&limit=1&sort=closedConversations:desc"
        },
        "last": {
            "rel": "last",
            "href": "https://localhost:8082/manager_workspace/api/account/le79144597/metrics?offset=2&limit=1&sort=closedConversations:desc"
        }
    },
    "groupBy": {
        "groupByField": "agentGroupId",
        "groups": [
            {
                "key": "1641709730",
		"keyDescription": "customerAssistanceSkill",
                "metrics": {
                    "assignedConversations": 6,
                    "humanAgentLoad": 1.18,
                    "avgWaitTime": 228876.654,
                    "avgWaitTimeFirstResponse": 798118.667,
                    "avgTimeToResponse": 58490.731,
                    "avgTimeToFirstResponseFirstAssignment": 59779.667,
                    "closedConversations": 1
                }
            }
        ]
    }
}