OCP® Real-Time Metrics API

OCP Metrics

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

For details regarding token creation and authentication, please refer to the API Authentication page.

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 APIs

Metrics types

As mentioned above, 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. 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 will be available through five different endpoints, based on the metrics category, and are described below.

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, 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.

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 as well. 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 the batch metrics requests after the two-hour watermark to ensure late events are updated in the calculations.

Metrics API

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:

/metrics-api/v2/realtime/metrics/dialogs
/metrics-api/v2/realtime/metrics/sessions

Batch metrics endpoints:

/metrics-api/v2/batch/metrics/dialogs
/metrics-api/v2/batch/metrics/sessions
/metrics-api/v2/batch/metrics/miniapps

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

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.

Metrics API Examples

Example 1.

Request Endpoint

POST {iam-url}/metrics-api/v2/realtime/metrics/dialogs

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.

Request Endpoint for Realtime Sessions

POST {iam-url}/metrics-api/v2/batch/metrics/miniapps

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"
}'

List of Supported Metrics

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

Real-Time Metrics

/metrics-api/v2/realtime/metrics/dialogs

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.

/metrics-api/v2/realtime/metrics/sessions

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.

Batch metrics

/metrics-api/v2/batch/metrics/dialogs

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.

/metrics-api/v2/batch/metrics/sessions

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.

/metrics-api/v2/batch/metrics/miniapps

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

This set of filters will be available in Metrics API v2 for each separate endpoint. Most filters are common across different end points.

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.

Real-Time Metrics

/metrics-api/v2/realtime/metrics/dialogs

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

/metrics-api/v2/realtime/metrics/sessions

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

Batch Metrics

/metrics-api/v2/batch/metrics/dialogs

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

/metrics-api/v2/batch/metrics/sessions

Name	Type
`channel`	Array(String)

/metrics-api/v2/batch/metrics/miniapps

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)

Time Series Example

The following example is aimed to help you understand how a Production Call with multiple steps and miniApps would 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. 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 Reporting UI within OCP® Insights. For more information, refer to the OCP® Reporting User Guide.

For more advanced OCP Reporting you may visit OCP® Conversational Insights.

[data-colorid=xs62ia7p2d]{color:#36b37e} html[data-color-mode=dark] [data-colorid=xs62ia7p2d]{color:#4cc994}[data-colorid=rtryysa11j]{color:#36b37e} html[data-color-mode=dark] [data-colorid=rtryysa11j]{color:#4cc994}OCP Metrics

Authentication

Errors Codes

OCP® Analytics APIs

Metrics types

Real-Time and Non-Real-Time Metrics

Metrics API

Query Payload Fields

Metrics API Examples

List of Supported Metrics

Real-Time Metrics

Batch metrics

List of Supported Filters

Real-Time Metrics

Batch Metrics

Time Series Example

Real-Time Metrics Intervals

Metrics Outputs

Available Period for Real-Time Metrics

OCP® Reporting for Real-Time Metrics

OCP Metrics