Sandbox Configuration

Note: This option was introduced in ver 7.1 of the platform. It is not available for on-prem installation.

Kore.ai XO Platform offers an IVR Sandbox environment to instantly launch your VA for interactions over voice calls. This is useful when a working IVR system is not available for testing your VA over a voice channel. IVR Sandbox is an optional integration and it can coexist with your custom IVR integration.

Enabling this option generates a Phone Number, Pin, and Secret. To develop and test it with your teams, you can call your VA by using the phone number and PIN allocated for your VA. On receiving the valid Pin and Secret you will be connected with the VA for interactions. See the following steps to understand the Sandbox configuration.

1. Select Enable for Kore.ai IVR Sandbox under the Configurations tab, to enable the Sandbox.
   
   
2. In the Select App drop-down, select an existing app or create a new app by clicking the Add button or choosing the Create App option.

The details are populated for an existing app, as shown in the following screenshot.



3. Click Save.

The following pop-up is displayed for the new app creation. Enter the details and click Create to create the app.


4. Upon saving the details, the following pop-up is displayed with Phone Number, PIN and Secret values. Click OK.
   
5. Once enabled, you can access the IVR Sandbox interaction details by clicking the Test button, which becomes visible upon hovering over the IVR icon under the Configured Channels.
   
6. On clicking Test, the following pop-up is displayed.
   
   

The Phone Number, PIN, and Secret are populated in the IVR Configurations panel as shown in the following screenshot.

IVR Sandbox Limitations:

• The platform supports only a limited number of concurrent lines, hence calls to your VAs through IVR Sandbox may not be answered at times.
• We strongly recommend you use IVR Sandbox only for internal testing purposes and not for the end-users of your Virtual Assistants, as there might be some functional limitations.

Configure Dialog Node IVR Properties

You can configure IVR properties for a node in a dialog task. Click the IVR Properties icon and  enter initial prompts, define Grammar, enter timeout, number of retries and other available fields. To know more about dialog definition, see the Voice Call Properties: Dialog Node Settings section.

IVR Channel Setup

This section explains the IVR channel setup for your virtual assistant. After configuring IVR Settings at both the VA and the Dialog levels, you must configure IVR Channel for the VA. IVR channel provides a generic integration to connect VAs with IVR systems. Kore.ai XO platform generates required VXML files to be exchanged as part of the VA interaction with the end user through the IVR systems.

Enable IVR Channel and Associate with an APP

Kore.ai Virtual Assistants require a JWT token to authenticate the incoming requests from IVR. For generating a JWT token, you should associate an app with the VA. You can select any existing Apps available in your Kore.ai account or create a new app.

1. Go to Deploy —> Channels in the left navigation panel of the virtual assistant.
2. On the Channels page, click IVR. The IVR Channel Instructions panel is displayed.
   

   Note: The Webhook Payload is used to test the IVR channel configuration for your VA. It can be tested using Postman.

   The IVR Voice Sample CURL request is as follows: 

   curl --location --request POST
'{{host}}/ivr/hooks/{{streamId}}?token={{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"callId":"98ab212987ce868ad546",
"message":"check balance",
"from":"14022334455",
"app_root":"app.vxml"
}'

   The following table provides the descriptions of all the mandatory and optional request parameters:

   Parameter	Required	Description
   callId	Y	Unique Id to identify or create a new user
   message	Y	Message from User. If the value is empty, then the Welcome message will be triggered.
   from	N	Created as a secondary user identity
   app_root	N	Select any document to be the application root document Note: The application root contains the file path, which is an entry point for the application.
   token	N	The JWT token can be passed in the body if it is not provided as a query parameter.

3. Click the Configurations tab.
   
4. From the Select App drop-down list, select an existing App or create a new app. See Configure IVR Settings to know more.
5. Copy the following values:
     a. WebHook URL: For calling the VA from IVR.
     b. Client Secret: To generate a JWT token that must be appended to the WebHook URL.
   
   
6. Select Yes for Enable Channel.

Generating JWT Token

1. To generate the JWT Token, click here.
   

   Note: For a quick overview of the JWT token, refer to Introduction to JWT tokens

2. JWT has to be passed in the IVR hook URL as a value for the query parameter “token”:
   https://{{host}}/ivr/hooks/{{botId}}?token={{JWT}}
   The token can also be passed as the body parameter.

Note: The host name, {{host}} refers to an environment URL, for example, https://bots.kore.ai. It changes based on the domain name.

Call The Virtual Assistant From IVR Call flow

You can pass data to the VA from the IVR call flow using VXML <subdialog> as shown in the following screenshot. The subdialog src should be Webhook URL with JWT Token, which receives the following parameters as Input.

• message: Message from User. If the value is empty, then Welcome message would be triggered.

• callId: A unique Call ID, based on which the VA identifies the IVR sessions

• from: Unique User’s Identity, e.g., Phone Number

• to: Bot Stream Id

The endOfConversation variable should be processed through the data returned from the sub-dialog. If the value is true, it indicates that the dialog execution (conversation) is complete. It can be a trigger point to end the call with the user.

ASR Metadata Extraction

The Automatic Speech Recognition (ASR) engine configured by bot engineers compares the speech input with many pre-specified possibilities and converts the speech to text. In addition to the ‘text,’ the bot designers need additional information from the ASR engine that helps them customize the conversation flow and the user experience. The two major additional details extracted from the ASR Metadata are:

•  Input Mode (Speech or DTMF) – The mode used by the user to provide the input. The two modes available include Speech and DTMF.

•  ASR Confidence – The confidence with which the ASR engine identifies the user input.

To extract the metadata from the ASR transcription, follow these steps: 

1. In IVR Channel settings under Voice Call Properties various details like Input Mode, ASR Confidence Threshold etc. are configured.


See Voice Call Properties: Channel Settings for more information.

2. The additional information provided by the ASR engines can be extracted using the context object. This is configured at  Bot User Session → lastMessage →  asrMetaData.
   

3. Go to the Settings panel of the last message node for your dialog task and configure the JavaScript Message under Bot Responses, as shown below:
   
   


The ASR metadata is extracted in the response using the following syntax:
print(JSON.stringify(context.session.BotUserSession.lastMessage.asrMetaData))

In this example, based on the ASR Confidence value extracted from the user input, we define the connection rules for the dialog as shown below:


4.  Go to Analyze → NLP Insights of your Virtual Assistant on the Kore.ai XO Platform.



5. Click on the relevant utterance to see the Chat History details.

6. Click the ellipsis icon on top of the Javascript Message to view the details of the ASR metadata extracted from the response.
   
   

In this example, the parameters like ASR Confidence score, input mode, utterance, etc. are extracted in the syntax shown below:

“data”: {

“text”:
“{“confidence”:”0.810000″,
“Inputmode”:”voice”,
“interpretation”:”Login.”,
“utterance”:”Login.”}”

Note: The information is available for the existing and new virtual assistants whose IVR channel is enabled.