IVR Integration

When it comes to automating customer interactions, IVR systems have proven to be among the top choices for organizations. But if you are using an Interactive Voice Response (IVR) system for your customer service, odds are you might have encountered these two issues quite often:

Non-Intuitive Interface: IVR systems do not simply let the customers state their need. They make the users go through a plethora of menu options from which to select before finding their intent. Even if they allow users to express their intent at first go, the backend programs can only understand a limited number of phrases.
Static Flows: IVR systems use static call flows that do not align with the nonlinear and contextual nature of human interactions. Take the following example of a customer trying to Book Flight tickets:
```
User: Book me a ticket to NYC
IVR: Sure, for which date?
User: Wait, will it rain there this Sunday?
IVR: Sorry, I don’t understand the input.
```
Conventional IVR system leaves limited room for the users to articulate their requests beyond the rigid program flows.

Kore.ai IVR Support

Kore.ai allows you to give a conversational makeover to your IVR system. It lets you build chatbots with human-like conversation capabilities and integrate them with your existing IVR system, thus taking your organization’s customer service experience to a whole new level.

The following features enable the seamless integration of your Kore.ai Bots with your existing IVR:

Native VXML Support: Built-in support to parse and generate W3C compliant VXML files.
Hybrid integration: Flexibility to build use cases or dialogs on the Bots Platform, which can work in-sync with the IVR dialogs.
Discourse Analyzer: Kore.ai’s discourse analyzer helps enterprises generate conversation flows using historical chat or call transcripts. Chat and call transcripts are analyzed using neural network-based machine learning models to identify intents and discourse patterns to fulfill a specific intent. This is an out-of-the-box feature which is in Beta state. Contact our support team if you want to try this feature.
Granular Call Flow Support: Ability to define all the call flow elements such as grammar, prompts, retry and time-out periods. Kore.ai supports call termination handlers, allowing you to end calls or invoke dialogs in case of exceptions.

Setting Up

Setting up IVR integration involves the following three steps:

Configure Bot Settings: Define IVR settings such as transcription options, welcome messages, standard responses and VXML properties
Dialog Definition: Define Dialog by configuring node-specific grammar, prompts, and call flow behavior like time-out, retries.
Channel Setup: Set up authentication, configure WebHook in your IVR system and enable channel.

Bot Settings

Step 1: IVR Settings for a Bot

As the first step of the integration, you first need to enable the IVR settings for the bot and define the Transcription options and VXML properties. These settings act as the default for the bot. You may override VXML properties defined at the bot level by defining custom values at the node level of the Dialog tasks.

To configure IVR settings for the bot

Open the Bot for which you want to integrate the IVR.
Hover over the Left navigation panel and select Channels
Locate and click IVR Settings. The IVR Panel with Instructions opens.
From the Configuration tab,
1. You can use Kore.ai IVR Sandbox for testing your Bot, see below for details.
  IMP: If you save the configuration after associating an app without Enabling IVR Settings, the platform will pre-populate the required settings for Sandbox.
2. Associate an App with the IVR channel – either by creating a new one or selecting an existing one.
3. Use the WebHook URL provided in your external application.
From the Settings tab set the configurations.
Note: The IVR Settings options on Dialog task nodes, Standard Responses, and Welcome Message become visible only when you enable IVR Settings for the bot from here.

If you have enabled IVR Sandbox, the following settings are required by the platform. These will be pre-populated if you do not enable the IVR settings. In case you have enabled the settings, ensure the values are the same as given below, sandbox may not respond as expected if you use different values:
– Enable Transcription set to Yes,
– transcription engine source set to builtin:speech/transcribe,
– IVR Data Extraction Key set to userinput,
– ASR Confidence Threshold Key set to userinput.confidence,
– ASR Threshold Confidence set to 50
(Optional) To enable an external transcription engine, under Enable Transcription, select Yes.
- On enabling the transcription engine, a text box appears for entering the source of the transcription engine.
  Note: Bots Platform supports all UniMRCP-encoded voice-to-text services. Only if you select the Enable Transcription option for the bot, the platform allows you to do away with defining grammar during configuring IVR settings for any node (described in Step 2).
  
  See below for detailed configuration for Grammar syntax.

Enter the following details to complete the setup:

Field	Description
IVR Data Extraction Key	Specify the syntax to extract the filled data
End of Conversation Behavior (post ver7.1)	This property can be used to define the bot behavior at the end of conversation. The options are: Trigger End of Conversation Behavior and configure the Task, Script or Message to be initiated. See here for details. Terminate the call.
Call Termination Handler	Select the name of the Dialog task that you want to use as the call termination handler when the call ends in error.
VXML Properties	Click Add Property. Enter property names and values to use in defining the VXML definition. Note: You should these properties and values in the VXML files for all call flows in the IVR system.
ASR Confidence Threshold
Threshold Key	This is the variable where the ASR confidence levels are stored. This field is pre-populated, do not change it unless you are aware of the internal working of VXML.
Define ASR threshold confidence	In the range between 0 to 1.0 which defines when the IVR system hands over the control to the Bot.
Timeout Prompt	Enter the default prompt text to play when the user doesn’t provide the input within the timeout period. If you do not specify a Timeout Prompt for any node, this prompt take its place.
Grammar	Define the grammar that should be used to detect user’s utterance The input type can be Speech or DTMF Source of grammar can be Custom or Link For Custom, write VXML grammar in the textbox. For Link, enter the URL of the grammar. Ideally, the URL should be accessible to the IVR system so that the resource can be accessed while executing the calls at runtime See below for detailed configuration for Grammar syntax. Note: If the Enable Transcription option is enabled for the bot along with specifying the source of the transcription engine, defining grammar isn’t mandatory.
No Match Prompt	Enter the default prompt text to play when user input is not present in the defined grammar. If you do not specify a No Match Prompt for any node, this prompt take its place.
Barge-In	Select whether you want to allow a user input while a prompt is in progress. If you select no, the user cannot provide input until IVR completes the prompt.
Timeout	Select the maximum wait time to receive user input from the drop-down list, from 1 second up to 60 seconds.
No. of Retries	Select the maximum number of retries to allow. You can select from just 1 retry up to 10 retries.
Log	Select Yes if you want to send the chat log to the IVR system.

Once you have enabled the IVR channel, we recommend configuring the Welcome Event for IVR Settings. This would play a welcome message for users when they connect to the Bot via the IVR channel.
For this:
1. From Natural Language -> Event Handlers configure Welcome Event
2. Select Show Message under Event Configuration
3. Click the Add IVR Settings button to open the IVR settings window
4. Under the Initial Prompts text box, enter the message that needs to be played when user connects to the Bot.
5. For details regarding other configuration fields, refer to the Configuring IVR Settings for a Node section below.

Sandbox Configuration

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

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

Enabling this option will give you a Phone Number, Pin, and Secret. You can call your bot by using the phone number and PIN allocated for your bot to develop and test the bot with your teams. On receiving the valid Pin and Secret you will be connected to the Bot for interactions.

Once enabled you can access the IVR Sandbox interaction details by selecting the Test button on hover over the IVR icon from the channels page.

Limitations

The platform supports only a limited number of concurrent lines hence calls to your bots via IVR Sandbox may not be responded to at times.
We strongly recommend you use IVR Sandbox only for serving internal testing purposes and not for the end-users of your bots as there might be some functional limitations.

Configuring Grammar

You will need to define at least one Speech Grammar to the IVR system.
There is no default Grammar that will be considered by the system. In this section, we will walk you through the steps needed to configure a Grammar system for the bot to function on the IVR system.

Typically for an IVR enabled bot, the speech utterance of the user will be vetted and parsed by the Grammar syntax at the IVR system before being diverted to the Bot.

Kore.ai supports the following Grammar systems:

Nuance
Voximal
UniMRCP

Each one requires their own configuration.

Nuance

In case you want to use grammar syntax rules from Nuance Speech Recognition System, you need get a license for the same. Once you register and obtain a license from Nuance, you will be given access to two files – dlm.zip & nle.zip. Ensure that the path to these VXML is accessible to the bot.

Configurations:

Set Enable Transcription to no
In the Grammar section:
- Select Speech or DTMF option as per your requirement.
- In the text box to define vxml enter the vxml path to dlm.zip file. The url will be of the format: http://nuance.kore.ai/downloads/kore_dlm.zip?nlptype=krypton&dlm_weight=0.2&lang=en-US
- Replace the above path according to your setup
- The language code “lang=en-US” will be based on your setup
Add Grammar to add another path to nle.zip. Follow the above-mentioned steps.
Save the settings.

Voximal/UniMRCP

In case you want to use grammar syntax rules from Voximal or UniMRCP, you need to specify the transcription source.

Configurations:

Set Enable Transcription to yes
In the Transcription engine source text box that appears:
- for Voximal, enter “builtin:grammar/text”
- for UniMRCP, enter “builtin:grammar/transcribe”
You can leave the Grammar section blank, the above transcription source uri will handle the syntax and grammar vetting of the speech.
Save the settings.

Dialog Settings

Step 2: Setting Up IVR Settings for Dialog Nodes

On the IVR Properties panel for a node, you can enter node-specific prompts, grammar, as well as parameters for call-flow behavior such as time-out and retries. If not enabled, you can use the enable button to enable the IVR settings for the Bot and then customize for the specific node.

IVR settings apply only for the following nodes and message types:

Entity Node
Message Node
Confirmation Node
Standard Responses
Welcome Message

Note: Most IVR settings are the same for all nodes, with a few exceptions.

Configuring IVR Settings for a Node

To configure IVR settings for a node, hover over the node in the Dialog task and click the Settings icon. On the Properties panel, click the IVR icon.

IVR Settings Field Reference
The following sections provide detailed descriptions of each IVR setting, including descriptions, applicability to nodes, default values and other key information.

Prompts:
- You can enter prompts in one of these formats: Plain text, Script, File location of an audio file. If you want to define JavaScript or attach an audio file, click the icon before the prompt text message box and select a mode. By default, it is set to Text mode.
- You can enter more than one prompt messages of different types. You can define their order of sequence by dragging and dropping them.
- Multiple prompts are useful in scenarios where the prompt has to be played more than once, to avoid repetition, since the prompts are played in order.
Initial Prompts
Apply to: Entity, Confirmation, Message nodes; Standard Responses and Welcome Message
Prompts that are played when the IVR first executes the node. If you do not enter a prompt for a node, the default user prompt for the node plays by default. If you do not enter a prompt for Standard Responses and Welcome Message, the default Standard Response and Welcome Message are played by default.
Timeout Prompts
Apply to: Entity, Confirmation; Standard Responses and Welcome Message
Prompts that are played on the IVR channel when the user has not given any input within the specified time. If you do not enter a prompt for a node, the default Error Prompt of the node is played. Standard Responses and Welcomes have a default Timeout Prompt that plays if you don’t define No Match Prompts.
No Match Prompts
Apply to: Entity, Confirmation; Standard Responses and Welcome Message
Prompts that are played on the IVR channel when the user’s input has not matched any value in the defined grammar. If you do not enter a prompt here or select No Grammar option for an Entity or Confirmation node, the default Error Prompt of the node is played. Standard Responses and Welcomes have a default No Match Prompt that plays if you do not enter it.
Error Prompts
Apply to: Entity, Confirmation;
Prompts that are played on the IVR channel when user input is invalid Entity type. If you do not enter a prompt here, the default Error Prompt of the node is played.
Grammar
Applies to: Confirmation; Standard Responses and Welcome Message
Define the grammar that should be used to detect user’s utterance. You can define one or more grammars for a node.

Note: If the Enable Transcription option is enabled for the bot along with specifying the source of the transcription engine, defining grammar isn’t mandatory.

To define the grammar
1. Select Speech or DTMF as the input type.
2. Source of grammar can be Custom or Link from the drop-down list
  1. For Custom, write VXML grammar in the textbox below.
  2. For Link, enter the URL of the grammar. Ideally, the URL should be accessible to the IVR system so that the resource can be accessed while executing the calls at runtime.

Advanced Options
These properties override the properties set in the Bot IVR Settings page.

Field	Description
Timeout	Select the maximum wait time to receive user input from the drop-down list, from 1 second up to 60 seconds. The default value is the same as defined in the Bot IVR Settings page.
No. of Retries	Select the maximum number of retries to allow. You can select from just 1 retry up to 10 retries. The default value is the same as defined in the Bot IVR Settings page.
Behavior on Exceeding Retries (applies only to entity node)	Define behavior when either the timeout or number of retry attempts exceed the specified limit. Options include: Invoke CallTermination Handler Initiate Dialog: Select a Dialog task from the list of bot tasks. Jump to specific node in current task: Select a node from the list of nodes in the current Dialog task. Post v7.3, this feature has been enhanced so that on exceeding entity error count, the platform will trigger the Behavior on Exceeding Retries behavior, when the transcription is enabled.
Barge-In	Select whether you want to allow a user input while a prompt is in progress. If you select no, the user input is not considered until the prompt is completed. The default value is No.
VXML Properties	Click Add Property. Enter property names and values to use in defining the VXML definition. These values defined for a node or a standard response override the global VXML properties defined in the Bot IVR settings page.
Log	Select Yes if you want to send the chat log to the IVR system. The default value is No.
Recording	Define the state of recording to be initiated. The default value is Stop.

Channel Override
You can write JavaScript code for the prompts in Entity nodes, Standard Messages, and Welcome Message to take full control of the call behavior. In such cases, you should write channel override JavaScript that generates the entire VXML code as the Bots Platform doesn’t append the IVR VXML snippet, but substitutes it with the code you write.
Follow these steps to write channel override for an Entity node:

Hover over the Entity node and click the icon.
UnderUser Prompts or Error Prompts section, click Manage Prompts or Manage Errors respectively.
Click Add Prompt Message.
From the Channels drop-down list, select IVR.
On the Message editor, click JavaScript.

Define JavaScript that generates the entire VXML code, and click Save.

Follow these steps to write channel override for a Standard Response:

Hover over the select Standard Response and select Add Channel Response > IVR.
On the Add Channel Overrides window, select the following:
1. Channel: IVR
2. Task and node for which to write the override.
Under the Response editor, click Advanced Mode and type the code.

Channel Settings

Step 3: Setting Up IVR Channel for the Bot

After configuring IVR Settings at both the Bot and the Dialog levels, you should configure IVR Channel for the bot. IVR channel provides a generic integration to connect bots with IVR systems. Kore.ai platform generates required VXML files to be exchanged as part of bot interaction with the end user via the IVR systems.
Enabling IVR Channel and Associating an APP
Kore.ai Bots require a JWT token to authenticate the incoming requests from IVR. For generating JWT token, you should associate an app with the bot. You can select any of the existing Apps available in your Kore.ai account or create a new app.

Hover over the side navigation panel of the bot and click Channels.
On the Channels page, click IVR. The IVR Channel Instructions page opens.
Click the Configuration tab.
From the Select App drop-down list, select an existing App. If you do not have any app to associate the bot with, click Add.
Copy the following:
1. WebHook URL: For calling the bot from IVR.
2. Client Secret: To generate JWT token that must be appended to the WebHook URL.
Select Yes for Enable Channel.

Generating JWT Token

Go to https://jwt.io/ nd scroll down the page to the Decoded section.
Replace the contents in the Payload box with
- sub – set to user name or call Id; and
- appId – set to Client ID of the app copied in the previous section
Scroll to Verify Signature section. In the Your-256-bit secret placeholder field, enter the copied Client Secret.
Click Share JWT. The JWT token gets copied.
JWT has to be passed in the IVR hook URL as value for the query parameter “token”:
https://bots.kore.ai/ivr/hooks/{{botId}}?token={{JWT}}

Calling Bot from IVR Call flow
You can pass data to the bot from the IVR call flow using VXML <subdialog> as shown in the picture below. The subdialog src should be Webhook URL with JWT Token which takes the following parameters as Input

message : Message from User

from: Unique User’s Identity Ex: Phone Number

to: Bot Stream Id

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

On this Page