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.
miniSIPServer 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.
Below figure describes our 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.
miniSIPServer 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 miniSIPServer 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 miniSIPServer core. miniSIPServer will process different work-flow according to different methods. |
The 'method' property can be following values:
| callto | miniSIPServer need make a call to destination |
| geturl | miniSIPServer invokes HTTP request to web site. This action can be used to interwork with web servers and application servers. |
| geturlresult | Result of 'geturl'. miniSIPServer gets result from website and process different actions according to the result. |
| input | miniSIPServer process digits user inputed. |
| playandwaitinput | miniSIPServer plays audio to caller party and wait user inputing digits. |
| playannouncement | miniSIPServer plays an audio announcement to caller party, for example, playing a music tone. |
| releasecall | miniSIPServer 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.1 Action 'callto'
When miniSIPServer processes 'callto' action, it will make call to the destination number. If there isn't event to be monitored, the whole IVR-XML process will be 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. miniSIPServer will try to make a call to such destination. |
| monitor-events | O | If this element is set, IVR procedure will monitor events in the call invoked by this action. |
Example:
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". miniSIPServer 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:
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', miniSIPServer should jump to indicated action. If there isn't any 'result' element, miniSIPServer should save the result and go to next action directly. |
Example:
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, miniSIPServer 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
Example 2: with 'digit' element to indicate next action
Example 3: error procedures
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 miniSIPServer 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 miniSIPServer 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 miniSIPServer to wait user input the first digit. If the timer is expired, miniSIPServer 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 miniSIPServer to wait user input subsequent digits. If the timer is expired, miniSIPServer 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 miniSIPServer need play audio again to wait new input. If there isn't this element, default value will be '*'. |
Example:
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'
Example:
5.1 <destination>
<destination> has two kinds of value:
- number
- <input />
Example 1:
Example 2:
If the value is number, miniSIPServer will route call to it directly. If the value is <input />, that means miniSIPServer 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 miniSIPServer should not care what user inputted and jump to 'nextaction' directly. |
| nextaction | M | It is name of next action miniSIPServer should process according to digits user inputted. |
Example :
5.3 <error-first-digit-timeout>
<error-first-digit-timeout> has following attributes:
| nextaction | M | It is name of next action miniSIPServer should process if user doesn't input any digit required by IVR. |
Example :
5.4 <error-improper-caller-response>
<error-improper-caller-response> has following attributes:
| nextaction | M | It is name of next action miniSIPServer 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 :
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'. miniSIPServer will get result from such action as input of current action. If there isn't this attribute, miniSIPServer will always get result from the latest user input. |
Example:
5.6 <monitor-events>
<monitor-events> is used to monitor some specific events in a call flow which is invoked by 'callto' action.
| monitor-event | M | Specific event. It MUST has one or more child elements 'monitor-event'. |
5.7 <monitor-event>
<monitor-event> is used to monitor a specific event in a call flow and indicate the IVR-XML procedure to next action if the event is caused.
| detection | M | It means what event is checked in current call. It can be following values:
|
| nextaction | M | It is name of next action miniSIPServer should process if current event is caused. |
Example:
5.8 <playaudio>
<playaudio> indicates miniSIPServer how to play audio announcement, it has following child elements:
| id | M | ID of audio file. In miniSIPServer, 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 miniSIPServer 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:
5.9 <parameter>
| name | M | This element is the name of current parameter. |
| value | M | Value of current parameter. |
Example:
5.10 <result>
<result> has following attributes:
| value | O | It is ANSI string from HTTP response. If there isn't this attribute, that means miniSIPServer 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 miniSIPServer should process according to result value. |
5.11 <value>
<value> can be following value:
- string
- <input />
- <callernbr />
- <callednbr />