IVR API

IVR API

IVR (Interactive Voice Response) uses pre-recorded voice prompts and menus to provide information and options in order to receive responses from the users via keypad dialling. IVR applications are programs that control and respond to calls on the IVR platform.

In creating an IVR application, developer needs to upload the audio files which need to be played and the JSON response formats which are required to manage the audio files to the Idea Mart hosting server. Once a user dials an IVR number, the call is received by Idea Mart. Then Idea Mart routes the call to the relevant application and sends the response to the call listener.

1.1 JSON Objects

JSON objects are used as the requests and responses for the application. JSON is an open, text-based data exchange format; it is human-readable, independent, and supports a wide availability of implementations.

All JSON strings in contain key-value pairs to represent information. It is a set of two linked data items: a key, which is a unique identifier for some item of data, and the value, which is the data that is identified or a pointer to the location of that data.

2 JSON Responses

Idea Mart hosting space should be used to host the IVR application. In this process simpler JSON responses as “response.json” can be uploaded using the key generator.

sudo –u hsenidivr key_generator <path_to_file>/file.zip <path_to_file>/response.json

Please refer section 3.2 for details on key generation.

A developer can create two types of IVR menus.

Single Audio Response: When a user calls the IVR number only a single audio file is played.

Simple IVR Menu: When a user calls the IVR number he/she first listens to a generic message that provides a list of options, requiring an input. Then based on the input of the caller the next audio is played. This sequence can be continued until the required closure is obtained, when the caller receives the desired outcome and terminates the call.

The request sent from Idea Mart to the application is handled by the system internally. For the response sent from application to Idea Mart, response parameters which describe the flow on which audio files should be played.

Responses related to each above instance is described below.

2.1 Single Audio Response

 


{

      "name":"play-once",

      "audio":"app1_header.wav",

      "refresh":"true"

}

 

Following are the Response parameters of the scenario.

 

Parameter Name

Description

Type

.Mandatory/ Optional

name
  Type of the call to be made. Whether it is a play         once or menu.
string
”play-once” – Mandatory
audio
Audio file uploaded when provisioning.
string
Mandatory
refresh
If provided true, IVR server will not cache the wav files.
 String
Optional

 

2.2 Simple IVR Menu

 


{
   "name": "menu", 
   "ivrMenu": { 
      "header": "header.wav", 
       "menu": { 
        "1": { 
         "audio": "file_1.wav", 
          "menu": {
           ...
          }
         }, 
         "2": { 
          "audio": "file_2_leaf.wav"
         }
       } 
    }
  }

 

Following are the Response parameters of the scenario.

 

Parameter Name Description Type Mandatory /Optional
name
menu (User inputs are used to continue with the call)
String
”menu” – Mandatory
header
The first audio file that shall be played. This could be the audio file for greeting.
String
Mandatory
menu
Represents the sub menu. Includes the user input value and the respective audio file that shall be played.
String
Optional
audio
The audio file that shall be played according to the user input.
String
Mandatory

3 File Upload

 

3.1 Zipping Audio Files
Audio files can be uploaded during application provisioning or later. Applications and the audio files of each application have to be approved by the Idea Mart admin separately. In addition each time audio files are updated Idea Mart admin has to approve the audio files if it’s a governed application.
After creating the application, developer has to create all the responses needed for the application in “.wav” format. Then, zip all audio files directly, rather than adding the files to a folder and then zipping them. These are the messages the user would listen when they call a particular application. Hence it is important to make sure that the audios are clear and detailed.
Following command format can be used in Linux platform to zip the audio files:
zip -r zip-file-name.zip a.wav b.wav c.wav
Make sure that you give names for your files, It is vital to give meaning full and appropriate names to the files in order to easily recognise.
For Windows, generic zipping software can be used to zip the files.
Select the audio files and right-click, point to “Send to” and then click “Compressed (zipped) folder”.
Consider that audio files should not be added to a folder and zipped.

NOTE: File should meet following criterions in order to successfully complete audio file upload 

Rate: 8000Hz 

Format: 32-bit float

Channel: Mono

Algorithm: A-Law 

Zipped file size: Should not be more than 30 MB

 

 

3.2 Uploading Files

After logging in using Idea Mart account to the Idea Mart hosting server, use the “key_generator” command to obtain a unique key and an identifier (md5sum) for the zip file. The generated key and identifier is used to map the uploaded files to the corresponding application. The generated key can be used during application provisioning and also can be used to update the audio files after the application is approved.
The sample command execution is shown below:
sudo –u hsenidivr key_generator <path_to_file>/file.zip <path_to_file>/response.json
Audio File Key* = 3ae4f0779694bf9fe7bee00c2370cc07_20150610105344.zip
Audio File MD5* = 3ae4f0779694bf9fe7bee00c2370cc07
NOTE: The command cannot be executed in the home directory. The command has to be executed in a sub directory.
The execution of the key generator is shown in the figure below.

1

4 Provisioning IVR Application

1. Click on Idea Pro icon as follows.

 

2

Figure 4.1

 

2.Click on Create Application

 

3

Figure 4.2

 

3. Fill application details as shown in the following figure. To create an IVR application, select “ivr” from the options available under “Resource Configurations” in the basic configurations page and set the necessary configuration details.

4

 

Figure 4.3

 

4.  Continue registering the application with the “Audio Key” and “Audio File MD5” obtained.
(Refer section Error! Reference source not found.)

 

5.  Use following as the “Connection URL”.
ws://ivr.static.app:8080/ivr/notify
Visit the following link for more detailed instructions on provisioning application.
http://www.ideamart.lk/idea-pro/how-to-provision-your-app
IVR Applications can be viewed in the Provisioning Home page as shown in the figure below.

5

 

Figure 4.4

 

Click on “Manage Audio Files” provides details of IVR application.
Click on “Edit” on the same page allows changing or adding audio files for the corresponding application.

6

 

Figure 4.5

 

Click on Edit directs to following page.

7

 

Figure 4.6

 

“Audio File Configurations” section should be filled using the keys generated (Refer section Error! Reference source not found.). Click on “Configure” saves the configurations made.

 

5 Error Response
In any case, if there is an error when processing the response from the application, Idea Mart sends an error response back to the application.
Following is a sample error response
{
  "messageType": "error-response", 
  "statusCode": "E1828", 
  "statusDescription": "No pending request found with sessionId 
  [http://10.48.248.104/ccxmlsession_104_628_2543191]"
 }
Parameter Name Description Type Mandatory /Optional
messageType
The type of the message error-response: App sends an error response to Ideamart.
String
Mandatory
statusCode
The error code for the entire request
String
Mandatory
statusDescription
The error detail for the entire request
String
Mandatory

 

Appendix A

Status Codes and Error Codes

 

8

 Error Codes

 

9

Definitions, Acronyms and Abbreviations used

What follows is a list of definitions of all terms, acronyms, and abbreviations required to interpret this document properly.
IVR – Interactive Voice Response
MSISDN – Mobile Station International Subscriber Directory Number
SDP – Service Delivery Platform
NCS – Network Capability Service