MYVOIPAPP

IVR-XML技术规范

索引
1. 概述

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

miniSIPServer 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>元素都指示 miniSIPServer 该做什么，<action>的顺序就描绘了IVR的工作流程。该元素有以下属性：

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

'method'属性有以下取值：

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

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

4. 动作
4.1 callto

miniSIPServer 完成callto操作，向目的号码发起呼叫。如果没有监视指定的呼叫事件，整个IVR-XML过程就结束了。

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

destination M 可以是电话号码、用户输入的数字或者从HTTP应用程序中返回的结果。 miniSIPServer 将向该目的号码发起呼叫。
monitor-events O 如果设置了该子元素，IVR流程在本动作产生的呼叫中，将监视指定的呼叫事件，并以此改变IVR的流程。

示例：



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

      

        
          

            url
            M
            
              HTTP URL地址，例如"http://www.myvoipapp.com/cgi-bin/demo.php"。 miniSIPServer 将使用该地址发起HTTP请求。

              每个'geturl'动作只能包含一个'url'地址。		
          

          

            
              parameter
            
            O
            定义在HTTP请求中的参数。我们可以使用该元素携带动态参数。每个'geturl'中最多只能包含5个参数。
          

        
      

      
示例：

      

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


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

      

        
          

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

        
      

      
示例：

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

        

        
            

                digit
                O
                如果用户输入该数字或者号码， miniSIPServer 将跳转到指定的动作执行IVR过程。

                    如果没有任何'digit'元素，当前动作将保存用户输入结果并直接继续下一个动作。		
            

            

                error-first-digit-timeout
                O
                如果用户没有输入任何数字，则我们可以通过该子元素处理这种异常情况。
            

            

                error-improper-caller-response
                O
                用户输入了一些数字，但是没有达到IVR要求的最小号码长度，则我们可以通过该子元素处理这种异常情况。
            

        
        

        
示例 1: 没有'digit'元素
        
        

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

        
示例 3: 异常情况处理
        
        
    
        
        
4.5 playandwaitinput
 
            
该动作用于向用户放音，并等待用户的输入。当用户输入号码时，播放的语音将被打断。

            
该动作包含以下元素：

            

            
                

                    playaudio
                    M
                    这是个子元素，用于向主叫用户播放语音提示。

                        请点击 这里了解该元素的更多细节信息。
                    		
                

                

                    minnumofdigits
                    O
                    ‘最少号码（Mininum number of digits）‘指示 miniSIPServer 至少应当等待用户输入多少位号码。

                        如果没有该元素，则缺省值为1，要求 miniSIPServer 至少等待用户输入一位号码。		
                

                

                    maxnumofdigits
                    O
                    '最多号码（maximum number of digits）'指示 miniSIPServer 最多应当等待用户输入多少位号码。

                        如果没有该元素，则缺省值为32，即 miniSIPServer 最多只需要等待用户输入三十二位号码。		
                

                

                    firstdigittimeout
                    O
                    ‘首位超时（first digit time-out）’是定时器值， miniSIPServer 等待用户输入第一个号码的时间。如果首位定时器超时， miniSIPServer 将认为这是用户没有输入任何信息的错误。

                    如果没有该元素，则缺省值为30秒。		
                

                

                    intervaldigittimeout
                    O
                    ‘位间超时（interval digit time-out）’也是定时器值， miniSIPServer 等待用户输入后续号码的时间。如果该定时器超时， miniSIPServer 将认为用户结束输入号码。

                    如果没有该元素，则缺省值为15秒。		
                

                

                    enddigit
                    O
                    '结束数字（End digit）'用于指示用户结束了输入，即只要用户输入该数字（字符），即可判定为用户结束输入。

                    如果没有该元素，则缺省值为'#'。		
                

                

                    canceldigit
                    O
                    '取消数字（Cancel digit）'用于指示用户取消了当前输入， miniSIPServer 需要重新播放语音并再次等待用户输入。

                        如果没有该元素，则缺省值为'*'。		
                

            
            

            
示例：

            

        
        
4.6 playannouncement

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

        

        
            

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

        
        

        
        
4.7 releasecall

        

        
            

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

        
        

        
示例：

        
        
    
 
    
 
    
 
    
    

    

    

    5. 子元素 
    

    

        
5.1 <destination>

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

        
        
示例 1:

        
  
        
示例 2:

        


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

        
        
5.2 <digit>

        
<digit>具有以下属性：

        

        
            

                value
                O
                用户输入的数字。如果没有该属性，miniSIPServer 将不关心用户的输入值，直接跳转到'nextaction'继续 IVR 过程。
            

            

                nextaction
                M
                下一个动作的名称。
            
      
                
        

        
示例:

        
  

        
5.3 <error-first-digit-timeout>

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

        

                
            

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

        
示例 :

        

        
        
5.4 <error-improper-caller-response>

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

        

                
            

                nextaction
                M
                下一个动作的名称。如果 IVR 要求用户输入数字，并有最小号长的要求，而用户虽然输入了部分数字，但是没有达到 IVR 的最小号长要求，则 IVR 跳转到该动作进行处理。

                    例如，IVR 要求最小号长是三位数字，而用户只输入了两位数字，则系统会上报该异常给IVR继续后续处理。		
            
      
                
        

        
示例 :

        


        
5.5 <input>

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

        

        
            

                from
                O
                该属性指明'input'动作或者'geturlresult'动作的名称。 miniSIPServer 将根据该名称，从这些动作中获取结果作为当前动作的输入信息。

                如果没有这个属性， miniSIPServer 将总是采用最新的用户输入信息作为返回结果。		
            

            
        

        
示例： 

        
    

        
5.6 <monitor-events>

        
<monitor-events> 在'callto'动作产生的呼叫中，监视指定的呼叫事件，并在事件触发时，执行IVR的下一个动作，更改整个IVR的流程。
 
        

            
                

                    monitor-event
                    M
                    特定的呼叫事件。本元素必须包含一个或者多个'monitor-event'子元素。
                
                
                
        


        
5.7 <monitor-event>

        
<monitor-event> 用于指定呼叫过程中需要监视的特定事件。
 
        

            
                

                    detection
                    M
                    当前呼叫过程中需要检测的事件，目前可以设置为以下参数值：

                        
    
                            
  • busy. 目标用户正忙。
    • 
                            
  • no-answer. 目标用户没有应答呼叫。
    • 
                            
  • reject. 由于某种未知的原因，当前呼叫被对方拒绝。
    • 
                            
  • disconnect. 被叫已经应答呼叫，双发通话后，呼叫释放。
    • 
                        

                    		
                
  
                

                    nextaction
                    M
                    事件发生后，IVR 流程需要执行的下一个动作的名称。
                
                
                
        

        
示例：

        


        
5.8 <playaudio>

        
<playaudio>指示 miniSIPServer 如何播放语音，它包含以下子元素：

        

        
            

                id
                M
                语音文件ID。

                在 miniSIPServer 中，每个语音文件都有一个ID。实际上，语音ID也是语音文件的文件名，我们可以非常容易地定制自己的语音。请点击这里了解更多 miniSIPServer 语音文件的细节。

                在我们的演示流程中，我们定制了两个语音文件'0a080002'和'0a080003'。		
            

            

                duration
                O
                指示该语音文件应当播放多长时间。

                    如果没有该元素，则缺省值为0，即循环播放。		
            

            

                repeat
                O
                语音文件的播放次数。

                    如果没有该元素，则缺省值为1，即只播放一次语音文件。		
            

            
        

        
示例1：

        
  
        
        
5.9 <parameter>

        

        
            

                name
                M
                当前参数的名称。
            

            

                value
                M
                当前参数的值。
            

            
        

        
示例：

        
    
        
        
5.10 <result>

        
<result>有以下属性：

        

        
            

                value
                O
                从HTTP响应消息中返回的字符串。如果没有该属性，意味着无论HTTP响应的值是什么， miniSIPServer 将直接跳转到'nextaction'指定的动作继续IVR过程。

                    该结果的字符串应少于60个字符。		
            

            

                nextaction
                M
                根据result值， miniSIPServer 下一步应当处理的动作的名称。
            
  
                
        

        
        
5.11 <value>

        
<value>有以下几种取值：

        
    
            
  • 字符串
    • 
            
  • <input />
    • 
            
  • <callernbr />
    • 
            
  • <callednbr />
    •