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

When using this API, it is crucial to iterate through all pages of the response until the "nextPageKey" and “next” fields are no longer present, even if any page contains no data(count=0). This ensures that you retrieve and analyze the complete dataset. If only the first page (or any subset of pages) is processed without fetching subsequent pages, the data may be incomplete, leading to discrepancies when comparing it with data from other sources.

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

IFT starts calculation when the human agent clicks on the conversation and ends when the agent navigates to a location in the conversational cloud outside of the conversation.

  1. 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)

For detailed information on the use cases of IFT and EHT, please refer to the following resource: IFT and EHT Use Cases.

Important Notice: Before enabling the AC features, please ensure that all agents' workstations have their clocks correctly set to the appropriate time and time zone.

⚠️ Failure to do so may result in inaccurate time tracking, leading to potential discrepancies in the calculation of the IFT and other related metrics. This can impact the accuracy of reporting and overall performance evaluation.

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

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

‘from’ must be within the past two weeks.

By default, the data retrieved through this API pertains only to human agents or skills. If you want to include data related to bots, you must explicitly set the "includeBotSkills" field in your request. However, setting this field to true will not include all bot data, but it will ensure that bot-related activities (see below) are reflected in the response.

  • Without the "includeBotSkills" field (or if "includeBotSkills" is set to false): If there is no data in the handleTime or workTime metrics (if these metrics are included in your request), no data will be returned for that interval.
  • With "includeBotSkills" set to true: If there is no data in the handleTime or workTime metrics, bot-related data will be included, but only metrics at the skill level—such as consumerMessages, arrivals, and closedConversations—will be populated. All other metrics will appear as zero.

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,
or fromL & toL.
Minimum value:
request time - 14 days.
Maximum 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,
or fromL & toL.
Minimum value:
request time - 14 days.
Maximum 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,
or fromL & toL.
Minimum value:
request time - 14 days.
Maximum 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,
or fromL & toL.
Minimum value:
request time - 14 days.
Maximum value:
from / fromL value + 1 day.
pageSize Numeric Maximum number of entries to retrieve Optional Default value: 100.
Max 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: 15.
Supported values:
15,
30,
60,
1440.
grouping String Select metrics aggregation level Optional Default value: skill.
Supported 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.
includeBotSkills Boolean Filter intervals without human agent activity Optional Default value: false
false: Don’t include intervals without human agent activity
true: Include intervals without human agent activity

Intervals without human agent activity will have data only for the following metrics: consumerMessages, arrivals, closedConversations.

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 Available only if grouping contains "skill"
intervals[].skillName String Available only if grouping contains "skill"
intervals[].agentGroupId Numeric Available only if grouping contains "agentGroup"
intervals[].agentGroupName String Available only if grouping contains "agentGroup"
intervals[].agentId Numeric Available only if grouping contains "agent"
intervals[].agentName String Available only if grouping contains "agent"
intervals[].agentLogin String Available only if grouping contains "agent"
intervals[].conversationId String Available only if grouping contains "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 This metric provides the number of consumer messages sent within a specified interval.

However, it is important to note that this metric should not be used for grouping by conversation.

Notice: The "Consumer Messages Within the Interval" metric is currently under review and may not provide accurate data.

We recommend avoiding the use of this metric until further notice.
     
intervals[].metrics.agentMessages Numeric This metric provides the number of agent messages sent within a specified interval.

However, it is important to note that this metric should not be used for grouping by conversation.

Notice: The "Agent Messages Within the Interval" metric is currently under review and may not provide accurate data.

We recommend avoiding the use of this metric until further notice.
     
intervals[].metrics.workTime Numeric Work time within the interval
intervals[].metrics.arrivals Numeric Arrivals within the interval.
Available only if grouping has only the value "skill"
intervals[].metrics.closedConversations Numeric Closed Conversations within the interval.
Available only if grouping contains "conversation"

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