Skip to main content
Skip table of contents

OCP® Real-Time Metrics API

Real-Time 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. 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 a generic error response for every endpoint in the following format:

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

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.

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

Property

Type

Required

Description

group

string

Yes

The group (organization) the metrics requested belong to. Possible values: ocp

metric-type

string

Yes

The type of metric requested. Possible values: batch, realtime

Query Payload Fields

Property

Type

Required

Description

metrics

array(string)

Yes

List of metrics requested. Available metrics of version 1 can be found in the following section

start

string

Yes

Query start date.

This field value is limited by query-max-age configuration in metrics-api config.

Supported date formats:

  • Relative:

    • <number><units>-ago (units: m = minutes, h = hours, d = days, w = weeks, n = months, y = years)

  • Absolute:

    • yyyy/MM/dd (start of day)

    • yyyy/MM/dd-HH:mm

    • yyyy/MM/dd HH:mm

    • yyyy/MM/dd-HH:mm:ss

    • yyyy/MM/dd HH:mm:ss

Possible values:

  • 1d-ago

  • 2022/01/01 07:00:00

end

string

No

Query end date

Supported date formats:

  • Relative:

    • <number><units>-ago (units: m = minutes, h = hours, d = days, w = weeks n = months, y = years)

    • now (current datetime)

  • Absolute:

    • yyyy/MM/dd (start of day)

    • yyyy/MM/dd-HH:mm

    • yyyy/MM/dd HH:mm

    • yyyy/MM/dd-HH:mm:ss

    • yyyy/MM/dd HH:mm:ss

Possible values:

  • 30m-ago

  • 2022/01/01 07:00:00

  • now (default)

filters.miniappName

array(string)

No

List of miniapp names for the metrics requested. Possible values:

  • appname1 - filters metrics for app1

  • appname1","appname2 - filters metrics for appname1 and appname2

filters.miniappType

array(string)

No

List of miniappTypes for the metrics requested. Possible values:

  • miniapptype1 - filters metrics for miniappType1

  • miniappType1,miniappType2 - filters metrics for miniappType1 and miniappType2

filters.locale

array(string

No

Filter locale for metrics requested. Possible values:

  • en-US - filters metrics for locale en-US

  • en-US,fr-CA - filters metrics for locales en-US and fr-CA

Default value: If absent, will aggregate all locales for metrics requested.

filters.channel

array(string)

No

Filter channel for metrics requested. Possible values:

  • channel1 - filters metrics for channel: channel1

  • channel1 , channel2 - filters metrics for channel1 and channel2

filters.testFlag

boolean

No

Filter test flag for metrics requested. Possible values:

  • false - filters metrics test_flag = false

filters.drilldown

boolean

No

Apply downsampling using interval and algorithm. Possible values:

  • true - for all opentsdb results shows a drilldown (groupBy) using the provided tag value filters

  • false - aggregates opentsdb results in a single time series for the provided filters

timezone

string

No

Possible values:

  • Europe/Athens - use this timezone for start of day to compute daily aggregated counts for metrics requested

Default timezone: UTC

Metrics API Examples

Example 1.

Request Endpoint

POST {iam-url}/metrics-api/{ocp-group}/realtime/miniapp-query

Request payload

JSON
{
    "end": "now",
    "start": "60m-ago",
    "metrics":["error_tasks_batch"],
    "filters": {
      "miniappName":["car_retail_test"],
      "miniappType":["CarRetail"],
      "locale": "en-US"
    },
    "drilldown": "true",
    "timezone": "timezone"
}

Request Example 

POST {iam-url}/metrics-api/{ocp-group}/realtime/miniapp-query

JSON
{
  "end": "now",
  "start": "60m-ago",
  "metrics": [
    "miniapp.invocations",
    "miniapp.invocations_successful",
    "miniapp.system_errors"
    ]
}

Response Example 

JSON
{
  "metric": "miniapp.invocations",     —> The metrics name(s) requested
  "tags": {
    "channel": “omIVR”,                 —> The channel of the metrics 
    "miniapp_name": "Demo_miniApp",     —> The Applications name(s) the metrics refer to
    "miniapp_type": "Banking",          —> The type(s) of the miniApps requested 
    "locale": "en-US",                  —> The language the metrics refer to 
    "group": "Demo_Banking_OCP",      —> The OCP Group (example UAT vs Prod) 
    "test_flag": false           —> Whether the metrics refer to test or prod data
    },
  "aggregateTags": [],
  "dps": {
    "1687333800": 130,   —> 130 invocations per timestamp: 21-June-2023 07:50:00 GMT+00 (5 min interval)
    "1687334700": 70,
    "1687335600": 120,
    "1687336500": 110
    }
}

Curl Request Example

JSON
curl --location --request POST 'https://us1-a.ocp.ai/metrics-api/{ocp-group}/realtime/miniapp-query' \
--header 'Authorization: Bearer ********Authorization Code**********'\
--header 'Content-Type: application/json' \
--data-raw '{
  "end": "now",
  "start": "60m-ago",
  "metrics": [
    "miniapp.invocations",
    "miniapp.invocations_successful",
    "miniapp.system_errors"
    ]
  }'

Example 2.

Request Endpoint for Realtime Sessions

POST {iam-url}/metrics-api/{ocp-group}/realtime/session-query

Request payload

JSON
{
    "end": "now",
    "start": "60m-ago",
    "metrics":["session.initiated"],
    "filters": {
      "channel":["omIVR"]
    },
    "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.

Name

Description

Supported Filters (Query Parameters)

Unsupported Filters

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 they are still active.

Applicable in session query endpoint.

start, end, locale(language), channel, testFlag, drilldown, timezone.

miniappName and miniappType.

Note: miniappName and miniappType are not applicable for Session metrics, as a single session triggers multiple miniApps.

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

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

Note: For Dialog metrics, miniappType = 'Flow' is only supported

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

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

Note: For Dialog metrics, miniappType = 'Flow' is only supported

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

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

Note: For Dialog metrics, miniappType = 'Flow' is only supported

miniapp.invocations

The number of total invocations of each miniApp a flow/application or standalone The miniApp is counted upon completion of this task.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

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

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

miniapp.system_errors

Total number of invocations per miniApp that ended with a system error, critical error or timeout error.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType

miniapp.no_matches

Total NoMatches per miniApp. A single miniApp may have multiple steps with no matches. This is a per-step metric.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

miniapp.no_inputs

Total No inputs per miniApp. A single miniApp may have multiple steps with no inputs. This is a per-step metric.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

miniapp.critical_error

Number of CriticalError events for each application. A Critical Error event may affect one or multiple miniApps within the same call.

start, end, locale(language), channel, testFlag, drilldown, timezone, miniappName and miniappType.

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.