The API retrieves aggregated metrics

Authorization

Bearer token
OAuth 2.0 token

Request

Method	URL
POST	https://{domain}/ootb_reporting/api/account/{accountId}/agg_metrics?timezone=Europe%2FWarsaw&conversationStartTime=2024-01-01T00%3A00%3A00.000Z~2024-04-31T00%3A00%3A00.000Z&apiSource=test

URL Parameters

Name	Description	Type	Required	Notes
conversationStartTime	Requested time frame	String	Required	Format example : 2024-06-09T00:00:00.000Z~2024-06-15T23:59:59.999Z
timezone	Requested time zone	String	Optional	Format example : Asia%2FKolkata(default is UTC)
apiSource	Source name	String	Required	Default value: 0

Body Parameters :

Name	Description	Type	Required
filters	Contains parameters to filter by (dimensions only).	Container	Optional
dimensions	Array	Object	Required
measures	Array	Object	Required
keyAfter	Reference for next page	Object	Required

Dimension Object:

Name	Description	Type	Required	Notes
name	dimension name	String	Required
interval	time interval for dimension	String	Required only when the dimension is DATE type	allowed values: hour, day, week, month
dimensions	sub dimension	Array	Optional

Measure Object:

Name	Description	Type	Required	Notes
name	measure name	String	Required

Request example: http://ootb_reporting/api/account/ACCOUNT_ID/agg_metrics?timezone=Europe%2FWarsaw&conversationStartTime=2024-01-01T00%3A00%3A00.000Z~2024-04-31T00%3A00%3A00.000Z&apiSource=test

{
  "dimensions": [
    {
      "name": "conversationStartTime",
      "interval": "week",
      "dimensions": [
        {
          "name": "convParticipant_skillName",
          "dimensions": [
            {
              "name": "convParticipants_assignedAgentUserType"
            }
          ]
        }
      ]
    }
  ],
  "measures": [
    {
      "name": "count_agentMessages"
    },
    {
      "name": "avg_lastMcs"
    },
    {
      "name": "avg_calculatedCsat"
    },
    {
      "name": "avg_timeToFirstResponseHuman_minutes"
    },
    {
      "name": "avg_timeToFirstResponseBot_minutes"
    }
  ]
}

Response example :

{
  "totalDocs": 10000,
  "dimensions": [
    {
      "conversationStartTime": "2024-04-29T00:00:00.000+05:30",
      "measures": [
        {
          "count_agentMessages": 29
        },
        {
          "avg_calculatedCsat": 42
        },
        {
          "avg_lastMcs": -11
        },
        {
          "avg_timeToFirstResponseBot_minutes": 0.01
        },
        {
          "avg_timeToFirstResponseHuman_minutes": 0.0
        }
      ],
      "convParticipants_assignedAgentUserType": "Bot",
      "convParticipant_skillName": "Bot Analytics"
    }
  ]
}

Pagination:

The Aggregated Metrics API aims to return all results in a single page. If the number of calculations exceeds the limits, the API will use pagination and provide a key for the next set of results. The API may return empty pages during pagination. If there is a key for the next set of results, keep making requests until you reach the last page, indicated by no "keyAfter". Pagination shows the first 1,000 unique results based on the initial criteria. To avoid pagination, adjust the filters and timeframe in your request.

Request:

{
  "dimensions": [
    {
      "name": "intents",
      "dimensions": [
        {
          "name": "convParticipant_skillName",
          "dimensions":[
            {
              "name": "convParticipants_assignedAgentName"
            }
          ]
        }
      ]
    }
  ],
  "measures": [
    {
      "name": "count_agentMessages"
    },
    {
      "name": "avg_lastMcs"
    },
    {
      "name": "avg_calculatedCsat"
    },
    {
      "name": "avg_timeToFirstResponseHuman_minutes"
    },
    {
      "name": "avg_timeToFirstResponseBot_minutes"
    }
  ],
  "filters": {
    "convParticipants_assignedAgentName": [
      "agent"
    ]
  }
}

Response :

{
  "totalDocs": 0,
  "dimensions": [],
  "currentKey": "OPyOUiWJheFwLO9p+tuD/rGAOihbdxnDdEPQ4UXgsWr5N3z8zKYCHGbtuOpzWfBI9uDuSWYHUm6Qf6nhH1eaXQ=="
}

Next request with the key:

{
  "dimensions": [
    {
      "name": "intents",
      "dimensions": [
        {
          "name": "convParticipant_skillName",
          "dimensions":[
            {
              "name": "convParticipants_assignedAgentName"
            }
          ]
        }
      ]
    }
  ],
  "measures": [
    {
      "name": "count_agentMessages"
    },
    {
      "name": "avg_lastMcs"
    },
    {
      "name": "avg_calculatedCsat"
    },
    {
      "name": "avg_timeToFirstResponseHuman_minutes"
    },
    {
      "name": "avg_timeToFirstResponseBot_minutes"
    }
  ],
  "filters": {
    "convParticipants_assignedAgentName": [
      "agent"
    ]
  },
  "keyAfter":"OPyOUiWJheFwLO9p+tuD/rGAOihbdxnDdEPQ4UXgsWr5N3z8zKYCHGbtuOpzWfBI9uDuSWYHUm6Qf6nhH1eaXQ=="
}

On the last page, the response object will return with empty dimensions, no totalDocs, and no reference to the next page:

{
  "dimensions": []
}

Time dimension: To make the most of Aggregated Metrics API, users need to set up aggregation dimensions carefully, keeping time in mind. When using a DATE-type dimension in your request, you must specify an interval. You can have a maximum of 48 intervals.

For example:

If the timeframe is 3 days, an interval by hour would result in 72 intervals, which is not allowed. To achieve hourly buckets, the user can change the timeframe to 1 day and send 3 separate requests, each with an hourly interval.
For a 3-month timeframe, selecting a day interval is not allowed since it exceeds 48 intervals. The available options for intervals within this timeframe will be weeks or months.

Request:

{
  "dimensions": [
    {
      "name": "conversationStartTime",
      "interval": "week",
      "dimensions": [
        {
          "name": "convParticipant_skillName"
        }
      ]
    }
  ],
  "measures": [
    {
      "name": "count_agentMessages"
    },
    {
      "name": "avg_lastMcs"
    },
    {
      "name": "avg_calculatedCsat"
    },
    {
      "name": "avg_timeToFirstResponseHuman_minutes"
    },
    {
      "name": "avg_timeToFirstResponseBot_minutes"
    }
  ],
  "filters": {
    "convParticipants_assignedAgentName": [
      "agent"
    ]
  }
}

Response :

{
  "totalDocs": 7,
  "dimensions": [
    {
      "conversationStartTime": "2024-04-08T00:00:00.000Z",
      "measures": [
        {
          "count_agentMessages": 29
        },
        {
          "avg_calculatedCsat": 42
        },
        {
          "avg_lastMcs": -11
        },
        {
          "avg_timeToFirstResponseBot_minutes": 0.01
        },
        {
          "avg_timeToFirstResponseHuman_minutes": 0.0
        }
      ],
      "convParticipant_skillName": "new_skill_security"
    },
    {
      "conversationStartTime": "2024-04-29T00:00:00.000Z",
      "measures": [
        {
          "count_agentMessages": 9
        },
        {
          "avg_calculatedCsat": 26
        },
        {
          "avg_lastMcs": 0
        },
        {
          "avg_timeToFirstResponseBot_minutes": 0.01
        },
        {
          "avg_timeToFirstResponseHuman_minutes": 0.0
        }
      ],
      "convParticipant_skillName": "Bot Analytics"
    },
    ....
  ]
}

Sibling Aggregations: (not for this release) Currently supports only on the first level of the aggregation request

Request:

{
  "dimensions": [
    {
      "name": "conversationStartTime",
      "interval": "week",
      "dimensions": [
        {
          "name": "convParticipant_skillName"
        }
      ]
    },
    {
      "name": "convParticipants_assignedAgentName"
    }
  ],
  "measures": [
    {
      "name": "count_agentMessages"
    },
    {
      "name": "avg_lastMcs"
    },
    {
      "name": "avg_calculatedCsat"
    },
    {
      "name": "avg_timeToFirstResponseHuman_minutes"
    },
    {
      "name": "avg_timeToFirstResponseBot_minutes"
    }
  ],
  "filters": {
    "convCsat": [
      "btw_lte_50_gte_0"
    ]
  }
}

Response :

{
  "totalDocs": 7,
  "dimensions": [
    {
      "conversationStartTime": "2024-04-08T00:00:00.000Z",
      "measures": [
        {
          "count_agentMessages": 1
        },
        {
          "avg_calculatedCsat": 26
        },
        {
          "avg_lastMcs": 0.0
        },
        {
          "avg_timeToFirstResponseBot_minutes": 0.01
        },
        {
          "avg_timeToFirstResponseHuman_minutes": 0.0
        }
      ],
      "convParticipant_skillName": "new_skill_security"
    },
    ......
    {
      "convParticipants_assignedAgentName": "Agent1",
      "measures": [
        {
          "count_agentMessages": 1
        },
        {
          "avg_calculatedCsat": 26
        },
        {
          "avg_lastMcs": 0.0
        },
        {
          "avg_timeToFirstResponseBot_minutes": 0.0
        },
        {
          "avg_timeToFirstResponseHuman_minutes": 0.0
        }
      ]
    }
  ]
}

Limitations

The APIs support only metrics and dimensions that are associated with the conversation model
Dimensions:
- Limited to a maximum of three dimensions
- The API response data is aggregated by the available dimensions and grouped by the dimension order selection.
- When selecting the dimension order, consideration must be given to the dimension levels: Conversation and Segment. Users have the flexibility to initiate their selection with either Conversations or Segment levels. However, once they start with the Segment level, they cannot revert to the Conversation level. The Dimension level is displayed here under the ‘Level’ column.
Filters:
- Users can filter data based on all dimensions (except time dimensions)
- Up to 1000 values for all types. For instance, if the user chooses to filter by Skills, the user can choose up to 1,000 skills.
Paging - In case the number of inner aggregation calculations reaches a max limit in request, the API will enforce pagination and provide the key for the next iteration.
Measures:
- Calculate on the last dimension only.

Faster Better answers through AI

Aggregated Metrics API

Authorization

Request

URL Parameters

Body Parameters :

Dimension Object:

Measure Object:

Limitations