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.
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 in Metrics API v2 (six endpoints in Metrics API v3), 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 V3
This set of near real-time metrics is available in Metrics API v3, both for real-time and batch endpoints.
Please be aware that Metrics API v2 is going to be deprecated. Metrics API v2 will be supported until end of Q4 2024.
Please migrate to Metrics API v3 if you used Metrics API v2 or refer to the Metrics API v3 from the beginning if you’re just starting your integration.
Metrics API is organized around HTTP REST. For Metrics API v3, both Batch and Real-time endpoints are available for end users.
Metrics APIv3 currently offers six endpoints (three for real-time metrics and three for batch ones) to serve metric requests and uses HTTP response codes to indicate API errors.
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.
timezone
String
No
UTC
The timezone of the dates returned in the metric results.
Start and end fields are also expressed in this timezone.
Real-Time Metrics API
Fetch dialogs data
POST
/metrics-api/v3/realtime/metrics/dialogs
Fetches the dialogs data.
Click to see the details
Name
Description
root_agent_requests
The number of agent requests within each dialog (conversation from an orchestrator root flow application). Multiple agent requests can be within the same call.
root_system_errors
Total number of dialogs (conversation from an Orchestrator root flow application) that ended with a system error, critical error, or timeout error.
root_critical_error
Number of CriticalError events for each dialog (conversation from an Orchestrator root flow application). Multiple CriticalError events can be within the same call.
root_no_inputs
Total NoInputs per root flow. Multiple NoInputs can be within the same call.
root_no_matches
Total NoMatches per root flow. Multiple NoMatches can be within the same call.
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 is counted when Orchestrator root application is completed.
dialogs_transferred
Total number of Transfers. Meaning unique dialogs (system bot conversations) that transferred out of Omilia Application. This metric is applicable for OCP Root Orchestrator Applications.
dialogs_terminated
Total number of Terminations. Meaning unique dialogs (system bot conversations) that were terminated by either the system or the user and never reached a live agent. This metric is applicable for OCP Root Orchestrator Applications.
List of supported filters
Name
Type
flow_name
Array(String)
locale
Array(String)
channel
Array(String)
test_flag
Boolean
region
Array(String)
Fetch sessions data
POST
/metrics-api/v3/realtime/metrics/sessions
Fetches the sessions data.
Click to see the details
Name
Description
sessions_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
region
Array(String)
Fetch miniApps data
POST
/metrics-api/v3/realtime/metrics/miniapps
Fetches the miniApps data.
Click to see the details
Name
Description
miniapps_agent_requests
The number of agent requests of each miniApp within a flow/application or standalone. There can be multiple agent requests even within the same miniApp.
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.
miniapps_no_inputs
Total NoInputs per miniApp. A single miniApp may have multiple steps with no inputs. This is a per-step metric.
miniapps_no_matches
Total NoMatches per miniApp. A single miniApp may have multiple steps with no matches. This is a per-step metric.
List of supported filters
Name
Type
miniapp_name
Array(String)
miniapp_type
Array(String)
locale
Array(String)
channel
Array(String)
test_flag
Boolean
region
Array(String)
Batch metrics
Fetch batch metrics of dialogs
POST
/metrics-api/v3/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)
region
Array(String)
Fetch batch metrics of sessions
POST
/metrics-api/v3/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)
region
Array(String)
Fetch batch metrics of miniApps
POST
/metrics-api/v3/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)
region
Array(String)
List of Supported Filters
There are filters available in Metrics API v3 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.
[
{
"metric": "root_agent_requests", —> The metrics name(s) requested
"tags": {
"channel": "chat", —> The channel of the metrics
"flow_name": "car_retail_flow_test", —> The application 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 agent requests in the time interval selected, meaning
-> between 12:00 and 13:00 for the above group, channel,
-> language, root application name
"2024-03-27 13:00:00.0": 4550, -> 4550 agent requests in the time interval selected
"2024-03-27 14:00:00.0": 0 -> 0 agent requests in the time interval selected
}
},
{
"metric": "dialogs_completed", —> The metrics name(s) requested
"tags": {
"channel": "chat", —> The channel of the metrics
"flow_name": "car_retail_flow_test", —> The application 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 dialogs completed in the time interval selected
"2024-03-27 13:00:00.0": 23, -> 23 dialogs completed in the time interval selected
"2024-03-27 14:00:00.0": 0 -> 0 dialogs completed in the time interval selected
}
},
{
"metric": "root_agent_requests", —> The metrics name(s) requested
"tags": {
"channel": "omIVR", —> The channel of the metrics
"flow_name": "car_retail_flow_test", —> The application 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 agent requests in the time interval selected, meaning
-> between 12:00 and 13:00 for the above group, channel,
-> language, root application name
"2024-03-27 13:00:00.0": 0, -> 0 agent requests in the time interval selected
"2024-03-27 14:00:00.0": 0 -> 0 agent requests in the time interval selected
}
}
]
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.
Metrics API V2
Please be aware that this set of Metrics API v2 described below is going to be deprecated. The Metrics API v2 will be supported until end of Q4 2024.
Please migrate to Metrics API v3 if you used Metrics API v2 or refer to the Metrics API v3 from the beginning if you’re just starting your integration.
Metrics API is organized around HTTP REST. For Metrics API v2, both Batch and Real-time endpoints are available for end users.
Metrics APIv2 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.
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.
timezone
String
No
UTC
The timezone of the dates returned in the metric results.
Start and end fields are also expressed in this 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
region
Array(String)
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
region
Array(String)
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)
region
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)
region
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)
region
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.
[
{
"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
}
}
]
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.
.svg)
