OCP® Real-Time Metrics API

Real-Time Metrics

Real-time metrics show necessary information about the current status of an Omilia Application. They are created from a specific selection of Omilia KPIs, targeted to ensure the user is informed about the current state of their system, without being overwhelmed with information. These metrics will be publicly available through the Metrics API.

OCP® Analytics APIs

Metrics API

Metrics API is organized around HTTP REST. Our API currently offers two endpoints to serve parametrized and daily metric requests and uses HTTP response codes to indicate API errors.

• Endpoint 1
  Daily requests fetch the data from midnight of the day the request is made to the moment the request is filled.

• Endpoint 2
  Hourly metrics, for which requests are filled using a call to a non-daily endpoint with a specific start/end time.

The highest granularity of metrics will be five minutes, which is also the default, but with the downsampling parameter, the user can apply a custom sampling rate. For example, request hourly metrics for the last 24 hours.

Authentication

Authenticate by including your secret API key in all requests. Your API keys carry many privileges, so be sure to keep them secret! Do not share this data in publicly accessible areas such as Github, client-side code, and so forth.

There are two types of API keys, depending on the privileges they carry:

• admin API keys - authorized to fully manage and query OCP resources, i.e. create, update, delete and list resources

• application API keys - authorized to only query the OCP resource that they belong to

admin API keys are provided by Omilia and application API keys are generated when creating the respective resource

Include the desired API key in the HTTP Authorization header using the following authorization scheme.

Sample request:

curl -v -X GET {service_url} \
  -H "Authorization: Token {api_key}" \
  -H "Content-Type:application/json"

Errors

The API provides a generic error response for every endpoint in the following format:

{
  "error": <true|false>,
  "code": <error_code>,
  "message": "some message pointing to a specific erroneous situation"
}

Omilia uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (for example, a required parameter was omitted, and so on), and codes in the 5xx range indicate an error with Omilia’s servers.

However, not all errors map cleanly onto HTTP response codes. To understand the source of the error please refer to the list of codes in the documentation.

The Omilia API uses the following error codes:

HTTP Error Codes

Metrics types

There are two types of metrics that will be supported:

• Real-time metrics, are generated in real-time and are broken down into five-minute intervals. Available in Version 1.

• Non-real-time metrics, (or batch metrics), which are exported from DWH. Those metrics are already offered in Convo Insights. Will be available in future versions of Metrics API.

The metrics will be available through two different endpoints. Version 1 will include the endpoint for real-time metrics only.

Real-Time and Non-Real-Time Metrics

The highest granularity of real-time metrics will be in five-minute intervals. For example, the end user will be able to see the number of invocations between 10:00-10:05, 10:05-10:10, and so on. On the other hand, non-real-time metrics (or batch metrics) will be aggregated on an hourly basis, the same as existing Convo Insights Solutions. For example, the user will be able to view total invocations between 10:00-11:00 and then 11:00-12:00. Both of these metrics will be able to be aggregated on a higher level.

Meaning for real-time and non-real-time metrics the end user will be able to fetch total invocations over the last two hours. Some discrepancy between real-time and batch metrics is expected. One reason is due to real-time metrics having a five minutes watermark after the dialog ended. In some cases, that data delay longer than that mark, and those dialogs won’t be taken into account for real-time reporting. On the other hand, batch metrics take longer to produce in order to retrieve data, even if they were sent with some delay, ensuring their accuracy. A simple example of a data sequence will be available.

Path Parameters

Query Payload Fields

Metrics API Example

Request

POST /metrics-api/{group}/{metric-type}/daily-miniapp-query

Response

{
    "metrics":["error_tasks_batch"],
    "filters": {
      "miniappName":["car_retail_test"],
      "miniappType":["CarRetail"],
      "locale": "en-US"
    },
    "drilldown": "true",
    "timezone": "timezone"
}

List of Real-Time Metrics

This set of near real-time metrics will be available in Metrics API v1.0. Apart from the description, there is a list of metrics parameters, also listed above, the user can use to aggregate, drill in, and out of.

Time Series Example

The following example will help the end user understand how a Production Call with multiple steps and miniApps would be depicted in real-time metrics. We have a Banking IVR Application, built using Orchestrator. The main flow consists of a sequence of three miniApps. A call enters our IVR at 10:01 and exits the IVR at 10:08. During this call three miniApps are used:

• miniApp 1 is triggered the moment the call reaches the application,

• miniApp 2 is triggered at 10:02 after miniApp 1 is completed,

• miniApp 3 is triggered from 10:06 until 10:08 when the call is terminated.

Real-Time Metrics Intervals

Real-time metrics are split into five-minute intervals. For this example the call will be active for the following two intervals:

• A: 10:00- 10:05
  In the Insights graph it will be marked as Time Point: 10:05

• B: 10:05-10:10
  In the Insights graph it will be marked as Time Point: 10:10

Metrics Outputs

• miniApp1 Invocation will be added at time frame A after 10:02

• miniApp2 Invocation will be added at time frame A after 10:06

• miniApp3 Invocation will be added at time frame B after 10:08

• This session initiated will be added at time frame A after 10:02

• This Application/Dialog will be added at time frame A after 10:08

• If this call is transferred out from IVR will be added in Dialogs Transferred at time frame A after 10:08

• If miniApp2 has three steps with noMatches, they will be added in time frame A, sequentially, meaning the counter could be increasing as more matches are occurring for the same miniApp.

• If miniApp2 is successful will be added in miniApp successful invocations at time frame A after 10

• If miniAppa2 has a delay in sending the data for more than five minutes (aka the miniApp ends at 10:06 but the JSON file is sent after 10:11) then it won’t be reported in real-time metrics, due to a five-minute watermark, but all data regardless delay will be captured in Convo Insights, in batch (historical) reporting.

• There could be a request for miniApps Invocations for Time Interval A, Time Interval B, and also for Time Interval A+B (10:00-10:10), the last 10 minutes.

• The sessions initiated will be added also at time frame B after 10:08, as the session was still active in that time frame and triggered a new miniApp.

Available Period for Real-Time Metrics

Real-time metrics will have a limited retention period of 48 hours. After this time range the metrics can be monitored, through Conversational Insights. For historical data, the user will be able to monitor their Applications through Convo Insights. In future versions of Metrics API, historical metrics will be also available, but instead of five-minute intervals, they will have one-hour intervals. The historical metrics will be reachable through a different endpoint.

OCP® Reporting for Real-Time Metrics

Metrics available through Metrics API are also available in Reporting UI within OCP® Insights. For more information, refer to the OCP® Reporting User Guide.