OCP® Real-Time Metrics API

Overview

Real-time metrics show the 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. The metrics are separated into two basic types, real-time and batch. These metrics will be publicly available through the Metrics API.

Authentication

Navigate to the API Authentication page to learn more about Token creation and Authentication process.

Errors Codes

Omilia's HTTP response codes can be found on the HTTP Code Responses page.

The API provides an error response for every endpoint containing the error message in the following format:

JSON

{
  "message": "some message pointing to a specific erroneous situation"
}

OCP® Analytics API Reference

Real-Time VS Non-Real-Time Metrics

There are two types of metrics supported:

Real-time metrics are generated in real-time and are broken down into five-minute intervals. They show the current status of the system.
Batch metrics are exported from the OCP Data Warehouse (DWH). They show historical information about the system status. Also available through Conversation Insights.

The metrics are available through five different endpoints, based on the metrics category, and are described below.

The highest granularity of real-time metrics is 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, batch metrics are aggregated on an hourly basis, the same as existing Convo Insights Solutions. For example, the user can view total invocations between 10:00-11:00 and then 11:00-12:00. Both of these metrics can be aggregated on a higher level.

Some discrepancy between real-time and batch metrics is expected. One reason is due to possible data delays, reflecting on the near real-time calculations. 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.

It is advised to make batch metrics requests after the two-hour watermark to ensure late events are updated in the calculations.

Metrics API

This set of near real-time metrics is available in Metrics API v2, both for real-time and batch endpoints.

Metrics API is organized around HTTP REST. For Metrics API v2, both Batch and Real-time endpoints are available for end users. In this version, our Metrics API currently offers five endpoints (two for real-time metrics and three for batch ones) to serve metric requests and uses HTTP response codes to indicate API errors.

Real-time metrics endpoints:

Batch metrics endpoints:

The default granularity of metrics for each type is:

five minutes → for real-time metrics;
one hour → for batch metrics.

However, using the downsampling parameter, users can apply a custom sampling rate. For example, request daily metrics for the last month.

Query Payload Fields

Click to see the details

Property	Type	Required	Default	Description
`metrics`	Array(string)	Yes	-	List of metrics requested. Available metrics can be found in the following section.
`filters`	Object	Yes	-	Object defining the filters of metrics requested. More details on the filters for each endpoint in the following section.
`start`	String	Yes	-	Query start date. This field value is limited: 2 days → for real-time metrics 720 days → for batch metrics Supported date formats: yyyy/MM/dd HH:mm:ss yyyy/MM/dd HH:mm:ss.SSS Example values: 2022/01/01 07:00:00 2022/01/01 07:15:44.542
`end`	String	Yes	-	Query end date. Supported date formats: yyyy/MM/dd HH:mm:ss yyyy/MM/dd HH:mm:ss.SSS Example values: 2022/01/01 07:00:00 2022/01/01 07:15:44.542
`group`	String	Yes	-	The group (organization) the metrics requested belong to. Example values: ocp
`downsampling`	String	Yes	-	Applying downsampilng using an interval. Valid values are: Real-time metrics: five_min hour Batch metrics: hour day week month year
`drilldown`	Boolean	No	false	Whether results should be aggregated together (false) or listed separated for each distinct value combination of filters.

The timestamps in the query payload are in the UTC timezone.

Real-Time Metrics API

Fetch dialogs data

POST	/metrics-api/v2/realtime/metrics/dialogs	Fetches the dialogs data.

Click to see the details

Name	Description
`miniapps_invocations`	The number of total invocations of each miniApp within a flow/application or standalone. The miniApp is counted upon completion of this task.
`miniapps_system_errors`	Total number of invocations per miniApp that ended with a system error, critical error or timeout error.
`miniapps_critical_error`	Number of `CriticalError` events for each application. A `CriticalError` event may affect one or multiple miniApps within the same call.
`miniapps_invocations_successful`	The number of total successful invocations of each miniApp within a flow/application or standalone. The miniApp has Result:success. The miniApp has to be completed in order for us to know if it was successful.
`no_inputs`	Total `NoInputs` per miniApp. A single miniApp may have multiple steps with no inputs. This is a per-step metric.
`no_matches`	Total `NoMatches` per miniApp. A single miniApp may have multiple steps with no matches. This is a per-step metric.
`dialogs_completed`	Total number of dialogs per Orchestrator root application. A dialog is a unique conversation (or call for IVR) within an application. This metric will be counted when Orchestrator root application is completed.
`dialogs_transferred`	Total number of dialogs per Orchestrator application that got transferred. This metric will be counted when Orchestrator root application is completed in order to retrieve the End Type and is applicable to IVR applications only.
`dialogs_terminated`	Total number of dialogs per Orchestrator application that got terminated. This metric will be counted when the Orchestrator root application is completed in order to retrieve the End Type and is applicable to IVR applications only.

List of supported filters

Name	Type
`miniapp_name`	Array(String)
`miniapp_type`	Array(String)
`locale`	Array(String)
`channel`	Array(String)
`test_flag`	Boolean

Fetch sessions data

POST	/metrics-api/v2/realtime/metrics/sessions	Fetches the sessions data.

Click to see the details

Name

Description

session.initiated

Total number of sessions the application received. Sessions refer to either unique IVR Calls or Chat Sessions (depending on the application), no matter how many miniApps or even Orchestrator flows were triggered. A session is counted when the first miniApp is triggered within OCP®. The sessions are recounted for each five-minute interval while the same session is still active. This metric can be treated as a number of active sessions for each five-minute interval.

For real-time session metrics, there’s a roll up aggregation, meaning if instead of five-minute increments, hourly increments are requested, the sessions that were active in both five-minute time frames will be counted twice.

List of supported filters

Name	Type
`channel`	Array(String)
`test_flag`	Boolean

Batch metrics

Fetch batch metrics of dialogs

POST	/metrics-api/v2/batch/metrics/dialogs	Fetches the batch metrics of dialogs.

Click to see the details

Name	Description
`dialogs`	Total number of dialogs (calls or chat sessions) per an OCP application.
`terminated`	Total number of dialogs that were terminated by the user or the system without being transferred to a live agent.
`transferred`	Total number of dialogs that were transferred out of Omilia IVR to an agent.
`error`	Total number of dialogs that had at least one system error.
`other`	Total number of dialogs, which were not classified in the above metrics.

List of supported filters

Name	Type
`miniapp_name`	Array(String)
`miniapp_type`	Array(String)
`language`	Array(String)
`channel`	Array(String)
`miniapp_id`	Array(String)

Fetch batch metrics of sessions

POST	/metrics-api/v2/batch/metrics/sessions	Fetches the batch metrics of sessions.

Click to see the details

Name	Description
`sessions`	Total number of distinct dialog sessions for the selected OCP Group.
`invocations`	Total number of miniApp invocations corresponding to these sessions.
`duration10sec`	Number of 10 seconds increments per distinct OCP session.

List of supported filters

Name	Type
`channel`	Array(String)

Fetch batch metrics of miniApps

POST	/metrics-api/v2/batch/metrics/miniapps	Fetches the batch metrics of miniApps.

Click to see the details

Name	Description
`totalinvocations`	The number of total invocations of each miniApp within a flow/application or standalone. The miniApp is counted upon completion of this task.
`successfultasks`	Total number of successful miniApp invocations.
`failedtasks`	Total number of failed miniApp invocations due to application logic.
`errortasks`	Total number of invocations with at least one system error.
`hangeduptasks`	Total number of user or system terminated invocations prior to the result, success or fail.
`dtmfescapekeytasks`	The total number of invocations within which the user opted out using the DTMF escape key.
`othertasks`	Any expectational case that doesn’t fall on the above categories.

List of supported filters

Name	Type
`miniapp_name`	Array(String)
`miniapp_type`	Array(String)
`language`	Array(String)
`channel`	Array(String)
`miniapp_id`	Array(String)
`miniapp_fail_reason`	Array(String)

List of Supported Filters

There are filters available in Metrics API v2 for each separate endpoint. Most filters are common across different endpoints. To view filters available for a specific endpoint, check its corresponding expandable section “Click to see the details”.

If a supported filter is not selected, the result will aggregate all the values for this filter. For example, if the channel filter is not pre-defined, and there are multiple invocations for the same application in both IVR and Chat channels, then the results will include all supported channels.

Metrics API Examples

Example 1. Fetch real-time metrics for dialogs

POST	{iam-url}/metrics-api/v2/realtime/metrics/dialogs	Fetches the real-time metrics for dialogs.

Click to see the details

Request payload

JSON

{
  "metrics": [
    "miniapps_invocations",
    "dialogs_completed"
  ],
  "filters": {
    "channel": [
      "omIVR",
      "chat"
    ],
    "miniapp_name": [
      "car_retail_test"
    ],
    "locale": [
      "en-US"
    ]
  },
  "start": "2024-03-07 12:00:00",
  "end": "2024-03-07 14:00:00",
  "group": "ocp-qa",
  "downsampling": "hour",
  "drilldown": "true"
}

Response payload

JSON

[
  {
    "metric": "miniapps_invocations",
    "tags": {
      "channel": "chat",
      "miniapp_name": "car_retail_test",
      "locale": "en-US",
      "group": "ocp-qa"
    },
    "dps": {
      "2024-03-27 12:00:00.0": 4606,
      "2024-03-27 13:00:00.0": 4550,
      "2024-03-27 14:00:00.0": 0
    }
  },
  {
    "metric": "dialogs_completed",
    "tags": {
      "channel": "chat",
      "miniapp_name": "car_retail_test",
      "locale": "en-US",
      "group": "ocp-qa"
    },
    "dps": {
      "2024-03-27 12:00:00.0": 55,
      "2024-03-27 13:00:00.0": 23,
      "2024-03-27 14:00:00.0": 0
    }
  },
  {
    "metric": "miniapps_invocations",
    "tags": {
      "channel": "omIVR",
      "miniapp_name": "car_retail_test",
      "locale": "en-US",
      "group": "ocp-qa"
    },
    "dps": {
      "2024-03-27 12:00:00.0": 420,
      "2024-03-27 13:00:00.0": 0,
      "2024-03-27 14:00:00.0": 0
    }
  }
]

Response payload explained

JSON

[
  {
    "metric": "miniapps_invocations",  —> The metrics name(s) requested

    "tags": {
      "channel": "chat",   —> The channel of the metrics
      "miniapp_name": "car_retail_test",  —> The Applications name(s) the metrics refer to
      "locale": "en-US",  —> The language the metrics refer to 
      "group": "ocp-qa"    —> The OCP Group (example UAT vs Prod)
    },
    "dps": {
      "2024-03-27 12:00:00.0": 4606,-> 4606 Invocations in the time interval selected, meaning 
                                    -> between 12:00 and 13:00 for the above group, channel, 
                                    -> language, application name
      "2024-03-27 13:00:00.0": 4550,-> 4550 Invocations in the time interval
      "2024-03-27 14:00:00.0": 0 -> 0 Invocation in the time interval
    }
  },
  {
    "metric": "dialogs_completed",  —> The metrics name(s) requested
    "tags": {
      "channel": "chat",   —> The channel of the metrics
      "miniapp_name": "car_retail_test",  —> The Applications name(s) the metrics refer to
      "locale": "en-US",  —> The language the metrics refer to 
      "group": "ocp-qa"    —> The OCP Group (example UAT vs Prod)
    },
    "dps": {
      "2024-03-27 12:00:00.0": 55, -> 55 Invocations in the time interval
      "2024-03-27 13:00:00.0": 23,-> 23 Invocations in the time interval
      "2024-03-27 14:00:00.0": 0
    }
  },
  {
    "metric": "miniapps_invocations",  —> The metrics name(s) requested
    "tags": {
      "channel": "omIVR",   —> The channel of the metrics
      "miniapp_name": "car_retail_test",  —> The Applications name(s) the metrics refer to
      "locale": "en-US",  —> The language the metrics refer to 
      "group": "ocp-qa"    —> The OCP Group (example UAT vs Prod)
    },
    "dps": {
      "2024-03-27 12:00:00.0": 420, -> 420 Invocations in the time interval
      "2024-03-27 13:00:00.0": 0,
      "2024-03-27 14:00:00.0": 0
    }
  }
]

Curl request example

JSON

curl --location --request POST 'https://us1-a.ocp.ai/metrics-api/v2/realtime/metrics/dialogs' \
--header 'Authorization: Bearer ********Authorization Code**********' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metrics": [
    "miniapps_invocations",
    "dialogs_completed"
  ],
  "filters": {
    "channel": [
      "omIVR",
      "chat"
    ],
    "miniapp_name": [
      "car_retail_test"
    ],
    "locale": [
      "en-US"
    ]
  },
  "start": "2024-03-07 12:00:00",
  "end": "2024-03-07 14:00:00",
  "group": "ocp-qa",
  "downsampling": "hour",
  "drilldown": "true"
}'

Example 2. Fetch batch metrics for miniApps

POST	{iam-url}/metrics-api/v2/batch/metrics/miniapps	Fetches the batch metrics for miniApps.

Click to see the details

Request payload

JSON

{
  "metrics": [
    "totalinvocations"
  ],
  "filters": {
    "channel": [
      "omIVR",
      "web-chat"
    ],
    "miniapp_fail_reason": [
      "CriticalError",
      "MaxContinuousErrors1",
      "MaxContinuousSameStateEvents"
    ]
  },
  "start": "2023-02-01 00:00:00",
  "end": "2024-01-31 11:59:59",
  "group": "ocp-qa",
  "downsampling": "year"
}

Response payload

JSON

[
  {
    "metric": "totalinvocations",
    "tags": {},
    "dps": {
      "2023-01-01 00:00:00.0": 10562,
      "2024-01-01 00:00:00.0": 89
    }
  }
]

Curl request example

JSON

curl --location --request POST 'https://us1-a.ocp.ai/metrics-api/v2/batch/metrics/miniapps' \
--header 'Authorization: Bearer ********Authorization Code**********' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metrics": [
    "totalinvocations"
  ],
  "filters": {
    "channel": [
      "omIVR",
      "web-chat"
    ],
    "miniapp_fail_reason": [
      "CriticalError",
      "MaxContinuousErrors1",
      "MaxContinuousSameStateEvents"
    ]
  },
  "start": "2023-02-01 00:00:00",
  "end": "2024-01-31 11:59:59",
  "group": "ocp-qa",
  "downsampling": "year"
}'

Example 3. Fetch real-time metrics for a call with multiple steps and miniApps

The following Time Series example is aimed to help you understand how a Production Call with multiple steps and miniApps would depicted in real-time metrics.

Click to see the details

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. The time intervals use the start time to be aggregated. 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:00.
B: 10:05-10:10
In the Insights graph, it will be marked as Time Point: 10:05.

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.
The session initiated will also be added at time frame B after 10:06.
The dialogs completed will be added at time frame A after 10:08, because then it will be known that the call was completed within OCP.

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 or Metrics API batch metrics endpoints with a retention period of 720 days.

OCP® Reporting for Real-Time Metrics

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

For more advanced OCP Reporting, visit OCP® Conversational Insights.