Introduction

Regardless of the data being targeted, detail queries have a lot in common. They are not meant to summarize overall activity, but rather, to dive into the discrete. Data is sourced from a time interval and presented in a non-lossy manner to show exactly what happened and when. Unlike aggregate queries which tend to focus on summarizing data, detail queries tend to be focused on detailed search-and-retrieval.

{
  "interval": "2015-11-01T00:00:00.000Z\/2015-11-02T00:00:00.000Z",
  "segmentFilters": [
    {
      "type": "or",
      "predicates": [
        {
          "dimension": "purpose",
          "value": "Customer"
        },
        {
          "dimension": "direction",
          "value": "outbound"
        }
      ]
    }
  ],
  "aggregations": [
    {
      "type": "termFrequency",
      "dimension": "wrapUpCode",
      "size": 10
    }
  ],
  "order": "asc",
  "orderBy": "segmentStart",
  "paging": {
    "pageSize": 10,
    "pageNumber": 1
  }

The name of each of the parameters in this query might vary slightly from one API endpoint to the next (as their name and what they target will be contextualized to each individual API endpoint), but the general role, usage, and syntax of them is consistent across the board.

(Required) Specifies a date and time range for the query, such as a week, day, or 30 minute interval. Intervals use ISO-8601 format. In general, if no filter is supplied, you will be limited to an interval no longer than seven days. If you do provide a filter, the limit increases to 31 days.

Important The interval will filter based on the conversation start timestamp. Conversations will only be included in the results if their start occurs on a day that the interval touches. The actual time of the conversation start need not be within the interval as long as it occurs on a day involved in the interval. This is because conversations are stored in daily indexes based on their start timestamp, and we only search the indexes corresponding to days included in the interval for performance reasons. A live conversation that started yesterday will need the start of the interval to include yesterday for said conversation to be included in the results. This only applies to conversations that are still active at the beginning of the query interval. Conversations that end before the query interval are excluded.

For example, say a conversation’s start/end is

start: 2018-02-19T23:55:05.520Z

end: 2018-02-20T07:25:00.692Z

interval: 2018-02-19T23:55:05.519Z/2018-02-20T07:30:00.000Z will include the conversation.

interval: 2018-02-20T07:20:00.000Z/2018-02-20T07:30:00.000Z will NOT include the conversation, even if there was activity at 2018-02-20T07:20:01.000Z. The index for 2018-02-19 was not searched.

interval: 2018-02-19T07:55:05.521Z/2018-02-20T07:30:00.000Z will include the conversation, because the interval touches the day of the conversation start, even though the start is not in the interval.

Consider a different example with a conversation with the following timestamps

start: 2018-02-20T06:55:05.520Z

end: 2018-02-20T07:25:00.692Z

interval: 2018-02-20T07:20:00.000Z/2018-02-20T07:30:00.000Z will include the conversation; this interval overlaps with the conversation timeline.

interval: 2018-02-20T08:00:00.000Z/2018-02-20T08:30:00.000Z will NOT include the conversation since the conversation ended before the interval start.

Tip: While filtering on conversationStart is required you may want to drill down to a more narrow time range of activity within. That can be achived with an additional segmentStart or segmentEnd predicate like so:

{
  "interval": "2018-05-10T19:15:00Z\/2018-05-17T20:00:00Z",
  "segmentFilters": [
    {
      "type": "and",
      "predicates": [
        {
          "dimension": "segmentEnd",
          "value": "2018-05-17T19:16:00Z\/2018-05-17T20:00:00Z"
        }
      ]
    }
  ]
}

In the above scenario, the conversation must have started within 2018-05-10T19:15:00Z\/2018-05-17T20:00:00Z but also had some activity inside of 2018-05-17T19:16:00Z\/2018-05-17T20:00:00Z.

(Optional) You can filter based on dimension. For a full listing of dimensions, see dimensions. You can also use a logical AND or OR statement to combine multiple filters. Filters are about reducing the amount of data returned by a query.

Note: The name of the filter block varies endpoint-to-endpoint and there can be multiple distinctly named filter blocks in a single query. For example, the conversation detail record query has conversationFilters, segmentFilters, and evaluationFilters each of which target specific dimensions and hierarchies of the data being searched. The syntax and intent is the same though: narrow down search results to those that match the filter(s).

Note: Logical NOT statements are not currently supported.

Note: Some dimensions are not available for some queries. For example, you cannot filter chat conversation data based on DNIS (dialed number identification service).

(Optional) While detail record queries are not like aggregate queries, there is still room for aggregate data about the query results. That is, in addition to returning the search results, you can summarize/partition those results. for example, in the above example, the query is asking for the top ten unique values of a dimension named wrapUpCode (if ten or more such values exist in the search results).

(Optional) There are two ordering parameters: "order" to specify if the search results should be returned in ascending or descending order and "orderBy" to specify which field will be used to determine what is ascending/descending. Valid "orderBy" values varies per API endpoint.

(Optional) Depending on your search query, you might retrieve more results than would be feasible to return in a single API call. The paging parameters provide a mechanism to iterate through the result set. If omitted, the default is generally pageNumber 1 and pageSize 25.

Use query predicates to filter out unwanted results. Narrowing down query to particular dimension values like a user ID, direction, queue ID, etc will improve query performance.

Paging deep into a large result set will result in slower query performance the larger the page number. A simple workaround is to time splice your query into smaller chunks.

Instead of querying for an entire week and paging through the results

2017-03-02T20:30:30.000Z/2017-03-09T20:30:30.000Z

Paging through queries in hourly chunks that cover the same overall time window will result in vastly more performant queries.

2017-03-02T20:30:30.000Z/2017-03-02T21:30:30.000Z
2017-03-02T21:30:30.000Z/2017-03-02T22:30:30.000Z
2017-03-02T22:30:30.000Z/2017-03-02T23:30:30.000Z
...
2017-03-09T19:30:30.000Z/2017-03-09T20:30:30.000Z