miniSIPServer IVR-XML (V1.5)

MYVOIPAPP Support Team

support@myvoipapp.com

Index

1. Description

IVR (Interactive Voice Response) is very useful in enterprise communication. For example, auto-attendant is a typical IVR service. In previous miniSipServer versions, we can use Python script to create powerful IVR services, but the shortage is that Python script is too complex to small business customers. So from miniSipServer V6.1 (and abover), IVR-XML is used to support IVR service. That means we can write simple IVR service in XML file which is very familiar for most customers.

MSS IVR-XML is not VoiceXML, CCXML or CallXML. We think all of them are still complex and hard to understand for small business. IVR-XML is much simpler and easy to use. In this document, we will give a demo IVR process to introduce the details of IVR-XML.

2. IVR process

Below figure describes our demo IVR process in auto-attendant service:

Demo IVR process in auto-attendant service

This IVR process is simple and includes two-levels audio menus. All actions will be routed to an externsion in the company finally.

Please click here to download or display the IVR-XML file for this process. We will describe IVR-XML based on this XML file.

3. Structure of IVR-XML

MSS IVR-XML file must be utf-8 encoding and all elements key words, such as property name, must be lower-case.

A IVR-XML file must include one and only one <mssxml> element.

A <mssxml> includes several <action> child elements. The IVR process will follow <action> instruction stey by step.

<mssxml>
    <action> ... ... </action>
    ... ...
    <action> ... ... </action>
</mssxml>

3.1 <mssxml>

'mssxml' is the root element of IVR process, it has following property:

version M It indicates which version current IVR-XML is. In current phase, it is always '1'.

In this document, 'M' means 'mandatory' and 'O' means 'optional'.

3.2 <action>

'action' element indicates MSS what to do. The order of 'action' elements describes IVR work-flow.

It has following properties:

name M It is indication of current action. It MUST be unique in the IVR-XML file.
method M It is instruction to MSS core. MSS will process different work-flow according to different methods.

The 'method' property can be following values:

callto MSS need make a call to destination
geturl MSS invokes HTTP request to web site. This action can be used to interwork with web servers and application servers.
geturlresult Result of 'geturl'. MSS gets result from website and process different actions according to the result.
input MSS process digits user inputed.
playandwaitinput MSS plays audio to caller party and wait user inputing digits.
playannouncement MSS plays an audio announcement to caller party, for example, playing a music tone.
releasecall MSS releases current call and disconnects the connection between caller party and called party.

Each 'action' element can have different child elements according to different 'method' property. In fact, we identify an action according to its 'method' property. For example, when we say 'playandwaitinput' action, it means the 'method' property of this action is 'playandwaitinput'.

4. Actions

4.1 Action 'callto'

When MSS finishs to invoke 'callto' action, the whole IVR-XML process is end.

Each 'callto' can have only one <destination>.

destination M It can be a phone number, digits from user input information or result of response from HTTP application. MSS will try to make a call to such destination.

Example:

    <action name="connectExtension" method="callto" >
        <destination><input /></destination>
    </action>

4.2 Action 'geturl'

This action can be used to provide some informations or data to customers' applications.

url M HTTP URL address, such as "http://www.myvoipapp.com/cgi-bin/demo.php". MSS will use it to invoke HTTP request.
Each 'geturl' action can include only one 'url' child element.
parameter O Parameters in HTTP request. We can use this element to carry dynamic variant. No more than 5 parameters can be included in one 'geturl' action.

Example:

    <action name="geturlTest" method="geturl" >
      <url>http://www.myvoipapp.com/cgi-bin/demo.php</url>
      <parameter>
        <name>card</name>
        <value><input from="inputCard"/></value>
      </parameter>
      <parameter>
        <name>password</name>
        <value><input from="inputPassword"/></value>
      </parameter>
    </action>
  

In above example, the final HTTP request will be 'http://www.myvoipapp.com/cgi-bin/demo.php?card=xxx&password=xxx'

4.3 Action 'geturlresult'

Each 'geturlresult' can include no more than 3 'result' child elements.

result O If HTTP server returns such 'result', MSS should jump to indicated action.
If there isn't any 'result' element, MSS should save the result and go to next action directly.

4.4 Action 'input'

Action 'input' is response to action 'playandwaitinput' to process user input digits. It can include one or several <digit> child elements.

digit O If user inputs such digits, MSS will jump to the indicated next action.
If there isn't any 'digit' element, current 'input' action will only save the digits user inputted, and go to next action.
error-first-digit-timeout O If user doesn't input any digit, this error will be reported and we can process it in IVR.
error-improper-caller-response O User has input some digits, but less than the minimum digit length, then this error will be reported and we can process it in IVR.

Example 1: without 'digit' element

    <action name="inputPassword" method="input">
    </action>

Example 2: with 'digit' element to indicate next action

    <action name="inputForMenu1" method="input">
        <digit value="11" nextaction="connectDISA" />
        <digit nextaction="connectExtension" />   
    </action>

Example 3: error procedures

    <action name="inputForMenu1" method="input">
        ......
        <error-first-digit-timeout nextaction="connect103"/>    
        <error-improper-caller-response nextaction="connect104"/> 
    </action>

4.5 Action 'playandwaitinput'

This action is used to play audio to user and wait user to input some digits. When user inputs digits, the audio can be interrupted.

It can include following elements:

playaudio M This is a child element of action and used to play audio announcement to caller party.
Please click here for more details about this element.
minnumofdigits O 'Mininum number of digits' indicates how many digits MSS should wait user to input at lest.
If there isn't this element, default value will be 1.
maxnumofdigits O 'maximum number of digits' indicates how many digits MSS should wait user to input at most.
If there isn't this element, default value will be 32.
firstdigittimeout O It is a timer value for MSS to wait user input the first digit. If the timer is expired, MSS will treate it as error that user doesn't input anything.
If there isn't this element, default value will be 30 seconds.
intervaldigittimeout O It is a timer value for MSS to wait user input subsequent digits. If the timer is expired, MSS will treate it as user has finished inputing digits.
If there isn't this element, default value will be 15 seconds.
enddigit O 'End digit' is used to indicate that user has finished input.
If there isn't this element, default value will be '#'.
canceldigit O 'Cancel digit' is used to indicate that user has cancelled input and MSS need play audio again to wait new input.
If there isn't this element, default value will be '*'.

4.6 Action 'playannouncement'

This action is used to play audio to user. It is almost same with previous action 'playandwaitinput'. The different is that current action doesn't require user input anything and the announcement cannot be interrupted.

playaudio M This is a child element of action and used to play audio announcement to caller party.
Please click here for more details about this element.

4.7 Action 'releasecall'

cause O This element indicates the cause to release current call. Its value is defined in ITU Q.850 document. MSS will carry this cause value in SIP message. If there isn't this element, the default cause value will be "normal clear" which is defined as '0x10' in Q.850.

Example:

    <action name="releaseCall" method="releasecall"> 
        <cause>20</cause>    
    </action>

5. Child elements of actions

5.1 <destination>

<destination> has two kinds of value:

Example 1:

    <destination>1234</destination>

Example 2:

    <destination><input /></destination>

If the value is number, MSS will route call to it directly. If the value is <input />, that means MSS should route current call according to what user inputted or the result of HTTP request.

5.2 <digit>

<digit> has following attributes:

value O It is digits user inputted. If there isn't this attribute, that means MSS should not care what user inputted and jump to 'nextaction' directly.
nextaction M It is name of next action MSS should process according to digits user inputted.

Example :

    <digit value="11" nextaction="connectDISA" />    

5.3 <error-first-digit-timeout>

<error-first-digit-timeout> has following attributes:

nextaction M It is name of next action MSS should process if user doesn't input any digit required by IVR.

Example :

    <error-first-digit-timeout nextaction="connect103" />    

5.4 <error-improper-caller-response>

<error-improper-caller-response> has following attributes:

nextaction M It is name of next action MSS should process if user inputs some digits but less than the minimum digits length required by IVR.
For example, if the 'minnumofdigits' is 3, but user only inputs 2 digits, then this error will be reported to IVR.

Example :

    <error-improper-caller-response nextaction="connect104" />    

5.5 <input>

<input> is used to transfer data retrieved from user input or response of HTTP request. It has following attribute:

from O This attribute indicates the name of action 'input' or action 'geturlresult'. MSS will get result from such action as input of current action.
If there isn't this attribute, MSS will always get result from the latest user input.

Example:

    <input from="inputPassword"/>

5.6 <playaudio>

<playaudio> indicates MSS how to play audio announcement, it has following child elements:

id M ID of audio file.
In MSS, each audio file has a ID. In fact, the ID is also the audio file name. It is very easy to record and use your own audio files. Please click here for more details about MSS audio files.
In our demo IVR process, we record two audio files whose ID is '0a080002' and '0a080003'.
duration O How long the audio file should be played.
If there isn't this element, default value will be 0 and it means forever.
repeat O How many times the audio file should be played.
If there isn't this element, default value will be 1 and it means only play just one times.

Example 1:

    <playaudio>   
        <id>84080001</id>
        <duration>60</duration>
    </playaudio>    

5.7 <parameter>

name M This element is the name of current parameter.
value M Value of current parameter.

Example:

    <parameter>
        <name>password</name>
        <value><input from="inputPassword"/></value>
    </parameter>

5.8 <result>

<result> has following attributes:

value O It is ANSI string from HTTP response. If there isn't this attribute, that means MSS should jump to the 'nextaction' no matter what the HTTP response is.
The result string should be less than 60 characters.
nextaction M It is name of next action MSS should process according to result value.

5.9 <value>

<value> can be following value:

Example 1:

    <value>1234</value>

Example 2:

    <value><input from="inputPassword"/></value>

Example 3: get caller number

    <value><callernbr /></value>

Example 4: get called number

    <value><callednbr /></value>