Visual IVR API

Overview

The AGI Connector supports the Visual IVR feature through a POST API endpoint. When a POST request is made to this endpoint, the Visual IVR process is triggered.

Authentication

Navigate to the API Authentication to learn more about Authorization Token Endpoint and Authentication process.

Flow of Visual IVR in AGI Connector

API endpoint is called.
There is a validation of form params.
_ocp_session_id
_ocp_gen_ts
_ocp_resp_ts
_ocp_form_hash

If the validation is successful, AGI Connector retrieves the form data parameters from the request and saves them locally. Also success response will be received. In case of failure an error response will be received.
An abort recognition is then triggered to deepASR through the corresponding API endpoint.
All form data params are then sent to DMT through the AGI Connector.

Endpoint

POST

<https://server/agi/visualivr>

Triggers the Visual IVR process

Request

cURL

BASH

curl --location --request POST server/agi/visualivr' \
--header 'Content-Type: application/json' \
--data-raw '{
    "_ocp_session_id": "<session_id>",
    "_ocp_gen_ts":"<Unix timestamp in seconds at the time the form was created>",
    "_ocp_resp_ts":"<Unix timestamp in seconds at the time the form was submitted>",
    "_ocp_form_hash":"<base64_encoded_hash_value>" \
    "other_form_param_1":"String",
    "other_form_param_2" : "String"
}'

cURL Example:

BASH

curl --location --request POST 'https://aws-staging-m-pub.ocp.ai/agi/visualivr' \
--header 'Content-Type: application/json' \
--data-raw '{
    "_ocp_session_id": "1697104818766:e49ff5313335656eadd415c7d7bd77fb",
    "_ocp_gen_ts":"1698667075",
    "_ocp_resp_ts":"1698667195",
    "_ocp_form_hash":"58a44a154902fc0db9515dc9a5b586e3381666f9515480c87d221fce2d91c2d8",
    "other_form_param_1":"aaaaaa",
    "other_form_param_2" : "bbbbb"
}'

This example of the curl command makes a POST request to the Visual IVR endpoint by providing the required data strictly formatted as JSON, including session id, unix timestamps, hashed values and other form parameters.

Make sure to replace placeholder values with your actual data before sending the request.

Headers:

Parameter	Type	Description
`Content-Type`	String	Set it to `application/json`.

Body/Form-data:

All form-data fields are required.

Parameter	Type	Description
`_ocp_session_id`	String	DiaManT's session ID.
`_ocp_gen_ts`	Long	Unix timestamp (in seconds) at the time when the form was created.
`_ocp_resp_ts`	Long	Unix timestamp (in seconds) at the time when the form was submitted.
`_ocp_form_hash`	String	The Base64 encoded SHA-256 hash of: `(salt + _ocp_session_id value + _ocp_gen_ts value + <the names of input fields concatenated>`) `salt` is a 32 character string containing random characters from the A-Z,a-z,0-9 subset and should be provided by miniApps.
`other_form_param_1`	String	Miscellaneous form data.
`other_form_param_2`	String	Miscellaneous form data.

Response

Success:

NONE

HTTP 200 OK success status response code

JSON

{
    "success": true
}

Fail:

JSON

{
    "success": false,
    "error": Error,
    "message": <Error message>
}

Error Codes

Omilia's HTTP response codes can be found on the HTTP Error Codes page.

Specifically, the Visual IVR API may receive an error response with code 400 due to issues with the following parameters:

400 Error Code messages	Error reason
`ocp_gen_ts identifier is required`	Parameter `ocp_gen_ts` is missing
`ocp_gen_ts identifier has invalid format must be numeric`	Invalid `ocp_gen_ts` parameter Format. Parameter is not numeric.
`ocp_resp_ts identifier is required`	Parameter `ocp_resp_ts` is missing
`ocp_resp_ts identifier has invalid format must be numeric`	Invalid `ocp_resp_ts` paramenter Format. Parameter is not numeric.
`ocp_form_hash identifier is required`	Parameter `ocp_form_hash` is missing
`Session id must be provided in the form.` `Provided session id not valid`	The `ocp_session_id` is missing or does not exist