If you have not done so yet, see the overview of this product.
In the interval metrics API, there are 2 handle models:
- In-focus Time (IFT) - Time spent by human agents focused on conversations they are assigned to.
-
Engaged Handle Time(EHT) - Time spent by human agents focused on conversations they are assigned to, while either:
a. The conversation is pending an agent response.
b. The agent is sending messages (calculated until the last agent message)
These metrics are available by an API as well as the out-of-the-box WFM adapters for NICE, Verint, and Calabrio. To enable the API you must contact your account team/manager, there is a need to turn on these features in Houston:
- LEUI.BAM_Enabled
- Common.WorkforceManagement_AHT
- lp-agentactivity-app.wfm-nrt-interval-metrics
You must enable the following permissions in Data Sources
Note - for reports that include the Agent system and agent state fields, you must enable the following fields in the API
Request
GET | https://{domain}/api/account/{account}/interval-metrics |
Example | https://{domain}/api/account/17434331/interval-metrics?v=1&source=Postman&metrics=handleTime,handledConversations,repliedConversations,consumerMessages,agentMessages&handleTimeModel=IFT&from=2023-05-01T00:00:00Z&to=2023-05-02T00:00:00Z&grouping=skill,agent |
Note - ‘from’ must be within the past week
Request Query Parameters
Parameter | Type | Description | Required | Notes |
---|---|---|---|---|
v | Numeric | API version | Required | Default value: latest available API version, New API versions will be added in case of backward-compatibility breaking changes. Supported values: Current version, Historical version - up to 1 month after a newer version is announced.Note - there might be a delay in the depreciation of the former version |
source | String | Describes the originator of the request | Required | Source must not exceed 20 characters |
from | String | Retrieve intervals which started within this timeframe | Required | Only one pair must be included. Either: from & to, fromL & toL, Minimum from / fromL value: request time - 7 days. Maximum to / toL value: from / fromL value + 1 day. |
to | RFC 3339 date-time | Retrieve intervals which started within this timeframe | Required | Only one pair must be included. Either: from & to, fromL & toL, Minimum from / fromL value: request time - 7 days. Maximum to / toL value: from / fromL value + 1 day. |
fromL | Numeric Milliseconds from Epoch | Retrieve intervals which started within this timeframe | Required | Only one pair must be included. Either: from & to, fromL & toL, Minimum from / fromL value: request time - 7 days. Maximum to / toL value: from / fromL value + 1 day. |
toL | Numeric Milliseconds from Epoch | Retrieve intervals which started within this timeframe | Required | Only one pair must be included. Either: from & to, fromL & toL, Minimum from / fromL value: request time - 7 days. Maximum to / toL value: from / fromL value + 1 day. |
pageSize | Numeric | Maximum number of entries to retrieve | Optional | Default value: 100Max value: 500 |
pageKey | String | Key for page of data to retrieve | Optional | The value for this parameter should be taken from the response’s metadata.paging.nextPageKey |
intervalDuration | Numeric Minutes | Select interval length | Optional | Default value: 15Supported values: 15, 30, 60, 1440 |
grouping | String | Select metrics aggregation level | Optional | Default value: skillSupported values: skill, agentGroup, agent, conversation |
agentId | Numeric | Filter intervals data for a specific agent | Optional | |
skillId | Numeric | Filter intervals data for a specific skill | Optional | |
agentGroupId | Numeric | Filter intervals data for a specific agent group | Optional | |
conversationId | String | Filter intervals data for a specific conversation | Optional | |
handleTimeModel | String | Handle time calculation model | Required | Supported values: IFT, EHT |
metrics | String Comma- separated list | Select which interval metrics to retrieve | Required | Supported values: handleTime, handledConversations, repliedConversations, consumerMessages, agentMessages, workTime If skillId grouping is provided, additional supported values:,arrivals. See the Metrics section for more info |
Response
Field | Type | Description |
---|---|---|
metadata | Object | |
metadata.v | Numeric | Reflects the requested API version |
metadata.timeframe | Object | Reflects the requested timeframe |
metadata.timeframe.from | String RFC 3339 date-time in UTC timezone | Reflects the requested timeframe |
metadata.timeframe.to | String RFC 3339 date-time in UTC timezone | Reflects the requested timeframe |
metadata.timeframe.fromL | Numeric Milliseconds from Epoch | Reflects the requested timeframe |
metadata.timeframe.toL | Numeric Milliseconds from Epoch | Reflects the requested timeframe |
metadata.paging | Object | Reflects the requested paging |
metadata.paging.pageSize | Numeric | Reflects the requested paging |
metadata.paging.pageKey | String | Reflects the requested paging Available only if the pageKey request parameter was provided |
metadata.paging.nextPageKey | String | Key for the next page. To be provided in the pageKey request parameter |
metadata.paging.refs | Object | Irrelevant references will not appear in the response |
metadata.paging.refs.first | String URL | Link to the first page of entries |
metadata.paging.refs.current | String URL | Link to the current page of entries |
metadata.paging.refs.next | String URL | Link to the next page of entries |
metadata.query.intervalDuration | Numeric | Reflects the requested intervalDuration |
metadata.query.grouping | String | Reflects the requested intervalGrouping |
metadata.query.handleTimeModel | String | Reflects the selected handleTimeModel |
metadata.filters | Object | Reflects the filters set by the request. Filters which were not requested will not appear in the response |
metadata.filters.agentId | Numeric | Reflects the filters set by the request. Filters which were not requested will not appear in the response |
metadata.filters.skillId | Numeric | Reflects the filters set by the request. Filters which were not requested will not appear in the response |
metadata.filters.agentGroupId | Numeric | Reflects the filters set by the request. Filters which were not requested will not appear in the response |
metadata.filters.conversationId | String | Reflects the filters set by the request. Filters which were not requested will not appear in the response |
metadata.count | Numeric | Numbers of retrieved entries |
intervals | Array of objects | |
intervals[].timeframe | Object | |
intervals[].timeframe.from | String RFC 3339 date-time in UTC timezone | |
intervals[].timeframe.to | String RFC 3339 date-time in UTC timezone | |
intervals[].timeframe.fromL | Numeric Milliseconds from Epoch | |
intervals[].timeframe.toL | Numeric Milliseconds from Epoch | |
intervals[].skillId | Numeric | |
intervals[].skillName | String | |
intervals[].agentGroupId | Numeric | Available only for grouping levels: agentGroup, agent, conversation |
intervals[].agentGroupName | String | Available only for grouping levels: agentGroup, agent, conversation |
intervals[].agentId | Numeric | Available only for grouping levels: agent, conversation |
intervals[].agentName | String | Available only for grouping levels: agent, conversation |
intervals[].agentLogin | String | |
intervals[].conversationId | String | Available only for grouping levels: conversation |
intervals[].metrics | String Array | Reflects the requested metrics |
intervals[].metrics.handleTime | Numeric Seconds | Handle time within the interval, as calculated by the selected handleTimeModel |
intervals[].metrics.handledConversations | Numeric | Handle conversations within the interval |
intervals[].metrics.repliedConversations | Numeric | Replied conversations within the interval |
intervals[].metrics.consumerMessages | Numeric | Consumer messages within the interval |
intervals[].metrics.agentMessages | Numeric | Agent messages within the interval |
intervals[].metrics.workTime | Numeric | Work time within the interval |
intervals[].metrics.arrivals | Numeric | Arrivals within the interval If grouping is other than skill, this field will not appear in the response |
Examples
Default Request - Intervals grouped by skill
GET | /api/account/123456/interval-metrics?v=1&source=postmanTest&handleTimeModel=IFT&from=2023-02-07T13:22:00Z&to=2023-02-07T13:52:00Z&grouping=skill |
{
"metadata": {
"timeframe": {
"from": "2023-02-07T13:22:00Z",
"fromL": 1675776120000,
"to": "2023-02-07T13:52:00Z",
"toL": 1675777920000
},
"paging": {
"limit": 100,
"offset": 0,
"refs": {
"current": "/api/account/123456/interval-metrics?v=1&source=postmanTest&limit=100&offset=0&handleTimeModel=IFT&fromL=1675776120000&toL=1675777920000",
"next": "/api/account/123456/interval-metrics?v=1&source=postmanTest&limit=100&offset=100&handleTimeModel=IFT&fromL=1675776120000&toL=1675777920000"
}
},
"query": {
"intervalDuration": 15,
"grouping": "skill",
"handleTimeModel": "IFT"
},
"filters": { },
"count": 100
},
"intervals": [
{
"timeframe": {
"from": "2023-02-07T13:15:00Z",
"fromL": 1675768500000,
"to": "2023-02-07T13:30:00Z",
"toL": 1675769400000
},
"skillId": 123,
"skillName": "Tech Support",
"metrics": {
"handleTime": 240,
"handledConversations": 20,
"repliedConversations": 15,
"consumerMessages": 40,
"agentMessages": 60,
"arrivals": 120
}
},
{
"timeframe": {
"from": "2023-02-07T13:15:00Z",
"fromL": 1675768500000,
"to": "2023-02-07T13:30:00Z",
"toL": 1675769400000
}
"skillId": "456",
"skillName": "Sales",
"metrics": {
"handleTime": 360,
"handledConversations": 30,
"repliedConversations": 25,
"consumerMessages": 90,
"agentMessages": 120,
"arrivals": 360
}
}
]
}
Intervals grouped by agent
GET | /api/account/123456/interval-metrics?v=1&source=postmanTest&handleTimeModel=IFT&from=2023-02-07T13:22:00Z&to=2023-02-07T13:52:00Z&grouping=agent |
{
"metadata": {
"timeframe": {
"from": "2023-02-07T13:22:00Z",
"fromL": 1675776120000,
"to": "2023-02-07T13:52:00Z",
"toL": 1675777920000
},
"paging": {
"limit": 100,
"offset": 0,
"refs": {
"current": "/api/account/123456/interval-metrics?v=1&source=postmanTest&limit=100&offset=0&handleTimeModel=IFT&fromL=1675776120000&toL=1675777920000",
"next": "/api/account/123456/interval-metrics?v=1&source=postmanTest&limit=100&offset=100&handleTimeModel=IFT&fromL=1675776120000&toL=1675777920000"
}
},
"query": {
"intervalDuration": 15,
"grouping": "agent",
"handleTimeModel": "IFT"
},
"filters": { },
"count": 100
},
"intervals": [
{
"timeframe": {
"from": "2023-02-07T13:15:00Z",
"fromL": 1675768500000,
"to": "2023-02-07T13:30:00Z",
"toL": 1675769400000
},
"skillId": 123,
"skillName": "Tech Support",
"agentId": 123,
"agentName": "John Doe",
"agentLogin": "john.doe@brand.com",
"metrics": {
"handleTime": 240,
"handledConversations": 20,
"repliedConversations": 15,
"consumerMessages": 40,
"agentMessages": 60
}
},
{
"timeframe": {
"from": "2023-02-07T13:15:00Z",
"fromL": 1675768500000,
"to": "2023-02-07T13:30:00Z",
"toL": 1675769400000
},
"skillId": "456",
"skillName": "Sales",
"agentId": "456",
"agentName": "Jane Doe",
"agentLogin": "jane.doe@brand.com",
"metrics": {
"handleTime": 360,
"handledConversations": 30,
"repliedConversations": 25,
"consumerMessages": 90,
"agentMessages": 120
}
}
]
}
Response Codes
- 200 - Success. Response contains data for all requested intervals
- 202 - Accepted. Some interval processing has not been completed yet. Retry later, or change the requested time frame to include only intervals with status “Done”
{
"intervals": [
{
"from": "2023-02-07T13:15:00Z",
"fromL": 1675768500000,
"to": "2023-02-07T13:30:00Z",
"toL": 1675769400000,
"status": "Done"
},
{
"from": "2023-02-07T13:30:00Z",
"fromL": 1675768500000,
"to": "2023-02-07T13:45:00Z",
"toL": 1675769400000,
"status": "In Progress"
}
]
}
- 400 - Invalid request. Do not retry. Fix the request according to the provided causes
- 401 - Unauthorized. Do not retry. Verify your API key is valid and has the correct permissions
- 429 - Too many requests. Retry later after at least 1 second
- 500 - Server Error. Retry 3 times with increasing pause between retries of at least 5, 10, and 15 seconds
- 503 - Service unavailable. Retry 3 times with increasing pause between retries of at least 5, 10, and 15 seconds
See Error Codes