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

In the interval metrics API, there are 2 handle models:

  1. In-focus Time (IFT) - Time spent by human agents focused on conversations they are assigned to.

  2. 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

intervalMetrics

Note - for reports that include the Agent system and agent state fields, you must enable the following fields in the API

intervalMetrics

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, closedConversations. 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, available when the grouping is 'skill' only
intervals[].metrics.closedConversations Numeric Closed Conversations within the interval. If grouping is contains 'conversation', 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,
        "closedConversations": 17
      }
    },
    {
      "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,
        "closedConversations": 25
      }
    }
  ]
}

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