IVR-XML技术规范文档 (V1.5)

MYVOIPAPP技术支持团队

support@myvoipapp.com

索引

1. 概述

IVR (互动式语音应答)在企业通信应用中是非常有用的特性,例如,自动话务员业务就是非常典型的IVR业务。在V6.1以前的版本中,我们采用Python脚本来实现强大的IVR业务,但是缺点在于Python脚本对于普通小企业客户而言是比较复杂的。所以在V6.1版本中,我们引入了IVR-XML来支持IVR业务。这也就意味着我们可以编写XML文件来实现简单的IVR业务流程,而大部分客户是非常熟悉XML文件及其语法。

MSS IVR-XML不是VoiceXML, CCXML,也不是CallXML。我们认为所有这些关于IVR的XML规范对于小企业客户而言还是过于复杂,并且部分概念也不太容易让人理解。IVR-XML则简单得多并且非常容易使用。在本文中,我们将结合一个简单的IVR流程来说明IVR-XML的各部分细节。

2. IVR过程

下图描述了我们的示例IVR过程,这是个自动话务员业务流程:

Demo IVR process in auto-attendant service

这个IVR流程非常简单,包含两级语音菜单。所有的操作最后都是将呼叫路由给某个分机。

点击这里下载或者显示上述IVR流程的IVR-XML文件。我们将基于这个文件来说明IVR-XML。

3. IVR-XML结构

IVR-XML文件必须采用utf-8编码,并且所有元素的关键词,例如属性名称等,都必须是小写字符串。

每个IVR-XML文件必须包含一个而且只能有一个<mssxml>元素。

<mssxml>包含多个动作(<action>子元素)。整个IVR流程将根据<action>的指示一步一步进行。

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

3.1 <mssxml>

<mssxml>是IVR流程的根元素,它有以下属性:

version M 指示当前IVR-XML文件的版本号。目前阶段,该属性值总是'1'。

在本文中,'M'是指必须具备的,而'O'指可选的。

3.2 <action>

每个<action>元素都指示MSS该做什么,<action>的顺序就描绘了IVR的工作流程。该元素有以下属性:

name M 当前操作(action)的名称。在整个IVR-XML文件中,每个操作的名称都必须是唯一的、不能重复。
method M 要求MSS进行的具体操作,MSS将根据不同的操作方法对工作流进行不同的处理。

'method'属性有以下取值:

callto MSS向目的号码发起呼叫。
geturl MSS发起HTTP请求。该动作可用于IVR与web服务器以及应用服务器进行交互。
geturlresult 'geturl'动作的结果处理。MSS从web服务器中得到响应,并根据响应信息进行不同的处理。
input MSS需要处理用户输入的数字。
playandwaitinput MSS应当给主叫播放语音并且等待用户输入数字。
playannouncement MSS向主叫用户播放语音,例如,播放音乐。
releasecall MSS释放当前呼叫。

<action>元素根据不同的'method'属性有不同的子元素。实际上,我们根据'method'属性区分不同的动作。例如,当我们提到‘playandwaitinput’动作,意思就是指method属性为‘playandwaitinput’的动作(action).

4. 动作

4.1 callto

MSS完成callto操作后,向目的号码发起呼叫,整个IVR-XML过程就结束了。

每个'callto'动作只能包含一个<destination>。

destination M 可以是电话号码、用户输入的数字或者从HTTP应用程序中返回的结果。MSS将向该目的号码发起呼叫。

示例:

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

4.2 geturl

该动作可用于向用户的应用程序提供信息或者数据。

url M HTTP URL地址,例如"http://www.myvoipapp.com/cgi-bin/demo.php"。MSS将使用该地址发起HTTP请求。
每个'geturl'动作只能包含一个'url'地址。
parameter O 定义在HTTP请求中的参数。我们可以使用该元素携带动态参数。每个'geturl'中最多只能包含5个参数。

示例:

    <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>
  

在上述示例中,最终的HTTP请求将是'http://www.myvoipapp.com/cgi-bin/demo.php?card=xxx&password=xxx',其中'xxx'取决于具体的输入值。

4.3 geturlresult

每个'geturlresult'动作最多只能包含3个'result'子元素。

result O 如果HTTP服务器返回该'result',MSS将跳转到指定的动作继续执行。如果没有定义任何'result',MSS将保存用户的输入并直接继续下一个动作。

4.4 input

'input'动作是'playandwaitinput'动作的反馈结果,用于处理用户输入的数字或者号码。该动作可以包含不超过10个<digit>子元素。

digit O 如果用户输入该数字或者号码,MSS将跳转到指定的动作执行IVR过程。
如果没有任何'digit'元素,当前动作将保存用户输入结果并直接继续下一个动作。
error-first-digit-timeout O 如果用户没有输入任何数字,则我们可以通过该子元素处理这种异常情况。
error-improper-caller-response O 用户输入了一些数字,但是没有达到IVR要求的最小号码长度,则我们可以通过该子元素处理这种异常情况。

示例 1: 没有'digit'元素

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

示例 2:携带'digit'元素指定下一个动作

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

示例 3: 异常情况处理

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

4.5 playandwaitinput

该动作用于向用户放音,并等待用户的输入。当用户输入号码时,播放的语音将被打断。

该动作包含以下元素:

playaudio M 这是个子元素,用于向主叫用户播放语音提示。
请点击 这里了解该元素的更多细节信息。
minnumofdigits O ‘最少号码(Mininum number of digits)‘指示MSS至少应当等待用户输入多少位号码。
如果没有该元素,则缺省值为1,要求MSS至少等待用户输入一位号码。
maxnumofdigits O '最多号码(maximum number of digits)'指示MSS最多应当等待用户输入多少位号码。
如果没有该元素,则缺省值为32,即MSS最多只需要等待用户输入三十二位号码。
firstdigittimeout O ‘首位超时(first digit time-out)’是定时器值,MSS等待用户输入第一个号码的时间。如果首位定时器超时,MSS将认为这是用户没有输入任何信息的错误。
如果没有该元素,则缺省值为30秒。
intervaldigittimeout O ‘位间超时(interval digit time-out)’也是定时器值,MSS等待用户输入后续号码的时间。如果该定时器超时,MSS将认为用户结束输入号码。
如果没有该元素,则缺省值为15秒。
enddigit O '结束数字(End digit)'用于指示用户结束了输入,即只要用户输入该数字(字符),即可判定为用户结束输入。
如果没有该元素,则缺省值为'#'。
canceldigit O '取消数字(Cancel digit)'用于指示用户取消了当前输入,MSS需要重新播放语音并再次等待用户输入。
如果没有该元素,则缺省值为'*'。

4.6 playannouncement

该动作用于向主叫用户播放音乐。这个动作非常类似前面的'playandwaitinput'动作,区别在于当前操作不要求用户输入信息,并且语音不能被打断。

playaudio M 向主叫用户播放语音提示。

4.7 releasecall

cause O 该元素指示释放当前呼叫时需要采用的原因值,采用ITU Q.850定义的标准原因值。 MSS将在SIP消息中携带该原因值。如果没有定义该元素,则缺省值总是"normal clear",在Q.850中定义为0x10。

示例:

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

5. 子元素

5.1 <destination>

<destination>可以有两种类型的值:

示例 1:

    <destination>1234</destination>

示例 2:

    <destination><input /></destination>

如果值是号码,MSS将直接使用该号码。如果值是<input>,那就意味这MSS将采用用户的输入值或者HTTP请求的返回值。

5.2 <digit>

<digit>具有以下属性:

value O 用户输入的数字。如果没有该属性,意味这MSS将不关心用户的输入值,直接跳转到'nextaction'继续IVR过程。
nextaction M 下一个动作的名称。

示例:

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

5.3 <error-first-digit-timeout>

<error-first-digit-timeout>用于指示首位超时的异常情况,包含以下属性:

nextaction M 下一个动作的名称。如果IVR要求用户输入数字,而用户没有输入任何数字, 则IVR过程跳转到该动作。

示例 :

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

5.4 <error-improper-caller-response>

<error-improper-caller-response>指示用户不正确的响应,包含以下属性:

nextaction M 下一个动作的名称。如果IVR要求用户输入数字,并有最小号长的要求,而用户虽然输入了部分数字,但是没有达到IVR的最小号长要求,则IVR跳转到该动作进行处理。
例如,IVR要求最小号长是三位数字,而用户只输入了两位数字,则系统会上报该异常给IVR继续后续处理。

示例 :

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

5.5 <input>

<input>元素通常用于传递用户的输入信息或者HTTP请求的响应信息,它包含以下属性:

from O 该属性指明'input'动作或者'geturlresult'动作的名称。MSS将根据该名称,从这些动作中获取结果作为当前动作的输入信息。
如果没有这个属性,MSS将总是采用最新的用户输入信息作为返回结果。

示例:

    <input from="inputPassword"/>

5.6 <playaudio>

<playaudio>指示MSS如何播放语音,它包含以下子元素:

id M 语音文件ID。
在MSS中,每个语音文件都有一个ID。实际上,语音ID也是语音文件的文件名,我们可以非常容易地定制自己的语音。请点击这里了解更多MSS语音文件的细节。
在我们的演示流程中,我们定制了两个语音文件'0a080002'和'0a080003'。
duration O 指示该语音文件应当播放多长时间。
如果没有该元素,则缺省值为0,即循环播放。
repeat O 语音文件的播放次数。
如果没有该元素,则缺省值为1,即只播放一次语音文件。

示例1:

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

5.7 <parameter>

name M 当前参数的名称。
value M 当前参数的值。

示例:

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

5.8 <result>

<result>有以下属性:

value O 从HTTP响应消息中返回的字符串。如果没有该属性,意味着无论HTTP响应的值是什么,MSS将直接跳转到'nextaction'指定的动作继续IVR过程。
该结果的字符串应少于60个字符。
nextaction M 根据result值,MSS下一步应当处理的动作的名称。

5.9 <value>

<value>有以下几种取值:

示例1:

    <value>1234</value>

示例2:

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

示例3: 获取主叫号码

    <value><callernbr /></value>

示例4: 获取被叫号码

    <value><callednbr /></value>