IVR 基础命令

应用服务器侧发给云通讯平台的命令,包括获取按键放音播放混合音录音播放TTS咨询呼叫咨询呼叫桥接呼叫转接发送DTMF业务跳转通话连接应用侧挂机拒接暂停空指令等。

1. 获取按键

  • 获取用户按键信息,只能作为主命令使用。命令名称为<Get>。

  • 属性
    名称属性值默认值说明
    action
    相对URL
    当前文档URL/dtmfreport
    按键上报通知的地址,参数为空或者不带此参数再回调dtmfreport的地址。如果用户输入DTMF按键,不论是否满足按键的条件(按键的位数或按键结束符),<Get>将提交给action的URL处理,<Get>后的动词将不会执行。如果用户未输入按键超时, <Get>将不会执行action的URL,而是会执行副命令中的呼转命令。
    method
    GET、POST
    POST
    请求方法
    timeout
    正整数
    20秒
    等待时间
    finishkey
    数字、#、*
    #
    结束符
    numdigits
    >=1的正整数12
    接收的按键个数
  • 嵌套规则
  • 在<Get>中可以嵌套:<Play>、<PlayTTS>。

  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <Get action="handle-user-input.jsp" numdigits="1">
  •         <Play>menu.wav</Play>
  •     </Get>
  •     <Play>sorrybye.wav</Play>
  •     <Redirect>/welcome/voice</Redirect>
  • </Response>

  • 示例解释
    • 获取用户按键,同时播放语音文件提示用户,若用户按键则云平台向应用侧action属性对应的URL发起请求,若用户按键超时则播放sorrybye.wav语音,语音播放完或按键打断后业务流程重定向到Redirect指向的URL。

2. 放音

  • 播放语音文件,支持wav和mp3语音格式文件,可作为主、副命令使用,放音完成后跳转将执行后续副命令中的呼转命令。命令名称为<Play>。
  • 属性
    名称属性值默认值说明
    loop
    整数,0不播放 -1无限循环播放
    1
    播放次数
    finishkey
    数字、*、#

    结束键
    isrecordtrue or falsefalse,不是录音文件是否是平台录音文件

  • 嵌套规则
    • 此命令不支持嵌套。

  • 示例
  • <?xml version="1.0" encoding="UTF-8" ?>
  • <Response>
  •     <Play>cowbell.wav</Play>
  •     <Redirect>otherservice</Redirect>
  • </Response>
  • 放音文件说明
    • 当isrecord=“true”的时候,放音文件名必需是云通讯返回的录音文件名,放音文件的格式样本如下:位速 128kbps,音频采样大小16位,频道 1(单声道), 音频采样级别 8 kHz,音频格式 PCM。这样能保证放音的清晰度。

3. 播放混合音

  • 播放语音文件,播放混合音,内容为数字或字母与文件名拼成的串,以分号分隔,字母不区分大小写。可作为主、副命令使用,放音完成后跳转将执行后续副命令中的呼转命令。命令名称为<PlayMix>。

  • 属性
    名称属性值默认值说明
    finishkey
    数字、*、#
    0123456789#*
    结束键
    type0字符串、1日期时间、 2钱、  3数字、 4文件默认值为0混合音类型
  • 嵌套规则
    • 此命令不支持嵌套。

  • 示例
  •     <?xml version="1.0" encoding="UTF-8" ?>
  • <Response>
  •     <PlayMix type="4140">hello.wav;2013-7-30;welcome.wav;1234</PlayMix>
  •     <Redirect>otherservice</Redirect>
  • </Response>


  • 示例解释
    • 用户听到的内容为:“尊敬的用户您好,今天是2013年7月30日欢迎光临云通讯平台1234”。

4. 录音

  • 电话录音功能,只能作为主命令使用。命令名称为<Record>。

  • 属性
    名称属性值默认值说明
    action
    相对的URL
    当前文档的URL/ recordover
    录音完成的后续处理URL,任何在<Record>后的动词将不会执行,如果静音超时,平台不会向action指定的URL发起请求,<Record>后的动词将被执行
    method
    GET、POST
    POST
    请求方法
    timeout
    正整数
    5秒
    开始录音前静音时长和结束录音静音时长
    finishkey
    数字、#、*
    1234567890#*
    录音结束符,在提示期间按结束键则执行后续命令
    maxlength
    大于1的整数
    120秒
    录音最长时间
    playbeep
    true、false
    true
    录音前是否播放beep声

  • 嵌套规则
    • 可以嵌套Play命令,播放录音前提示音。

  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <Record>
  •        <Play>promt.wav</Play>
  •     </Record>
  •     <Play>test.wav</Play>
  •     <Redirect tag="9">dfaa</Redirect>
  • </Response>


  • 示例解释
    • 平台执行<Record>,呼叫者在听到”beep”声后开始录音。若呼叫者静默5秒钟后输入结束键,或者已到录音最长时间,平台将携带参数“RecUrl”将向“action”指定的URL发起指定方法请求。

5. 播放TTS

  • 播放文本转语音,将用户的文本转换语音文件进行播放,文本中的汉字需要用utf8编码,可作为主、副命令使用,放音完成后跳转将执行后续副命令中的呼转命令。命令名称为<PlayTTS>。

  • 属性
    名称属性值默认值说明
    loop
    整数,-1无限循环播放
    1
    播放次数
    finishkey
    数字、*、#
    0123456789#*
    结束键
    lastplay
    是否播放上一次转换后的内容false
    true播发上次转换后的内容,false不播发
    speed
    发音速度
    0
    -500~+500,默认值为0
    volume
    音量
    0
    -20 - +20,默认值为0
    pitch
    音调
    0
    -500 - +500,默认值为0

  • 嵌套规则
    • 此命令不支持嵌套。

  • 示例
  •     <?xml version="1.0" encoding="UTF-8" ?>
  • <Response>
  •     <PlayTTS>您好,这里云通讯开放平台系统</PlayTTS>
  •     <Redirect>otherservice</Redirect>
  • </Response>

6. 咨询呼叫

  • 为用户发起咨询呼叫,被咨询者接听后自动与用户进行话路桥接,只能作为主命令使用。命令名称<ConsultationCall>。

  • 属性
    名称属性值默认值说明
    number
    座机号码、手机号、通讯账号
    必填
    被咨询者的号码
    action
    相对的URL

    被咨询侧接听后请求的URL,若为空则自动桥接咨询侧与被咨询侧。不为空,被咨询侧应答就上报通知消息(需要在上报的通知消息返回咨询呼叫桥接命令,否则不会桥接造成无法通话)。被咨询侧接听则< ConsultationCall >后的动词将不会执行;如果被咨询侧未接听、占线或拒接,将被执行<ConsultationCall>中noanswerurl的被咨询侧未接听挂机通知,noanswerurl空则将被执行<ConsultationCall>后的呼转通知。
    ringbacktrue or falsefalse咨询侧是否听被咨询侧回铃音;当action参数为空时有效;
    methodGET、POSTPOST请求方法
    timeout正整数一直等待被咨询侧接听超时时长,被咨询侧超时未接听后会执行后续的呼转命令
    finishkey数字、#、*空,用户无法结束咨询呼叫结束符,在被咨询者未接听前,结束键始终有效,咨询侧按结束符,将被执行咨询侧主动结束呼叫的回调地址
    cancelurl相对URLcancelconsultation咨询侧主动结束呼叫的回调地址
    recordtrue、falsefalse是否进行通话录音
    recordurl相对URL相对url录音完成的后续处理URL
    calltime正整数0(不限时)咨询通话的时间长度,单位是秒
    calltimeoverurl相对URL咨询通话设置时间结束咨询侧通知请求的URL地址,如果为空,通话时间到后咨询侧自动挂机
    calltimeoverconsulurl相对URL相对url咨询通话设置时间结束被咨询侧通知url地址,为空通话时间到后则自动挂断被咨询侧电话,可通过此通知回响应命令控制被咨询侧后续业务逻辑。
    calltimeoverprompt语音文件通话到时的提示音;语音播放完成或20秒后双方就会断开通话。为空则不播放
    hangupurl相对URL被咨询侧接听并挂机后发起请求的URL地址
    noanswerurl相对URL被咨询侧未接听挂机通知的url地址,为空则将被执行<ConsultationCall>后的呼转命令。当设置了timeout参数时,被咨询侧在timeout设置的时间超时则执行后续的呼转命令。
    transferurl相对的URL指定呼转请求的URL地址。被叫按*+分机号+#即可
    countdowntime正整数咨询通话倒计时时间,必须是与calltime同时使用,并且设置播放提示音,且小于calltime时间,单位秒
    countdowntimeplayfile语音文件名咨询通话倒计时时间到,播放的提示音文件名
    consulurlafterhangup相对URL咨询侧挂机后给被咨询侧回调通知的URL地址,用于控制咨询侧挂机后被咨询侧的后续逻辑处理。若为空则自动挂断被咨询侧
  • 嵌套规则
    • 只能嵌套<Play>,为用户播放等待音。
  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <ConsultationCall number=”13800138000” record=”true”>
  •         <Play>waitmusic.wav</Play>
  •     </ConsultationCall>
  •     <Play>sorry.wav</Play>
  •     <Redirect>continue</Redirect>
  • </Response>

7. 咨询呼叫桥接

  • 若咨询呼叫不是自动桥接,需要能过此命令进行桥接,用于主命令。命令名称<ConsultationBridge>。

  • 属性
    名称属性值默认值说明
    action
    相对URL
    必填
    连接成功的回调URL地址

  • 嵌套规则
    • 可嵌套<Play>、<PlayTTS>命令。

  • 示例
  •     <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <ConsultationBridge>
  •         <Play>prompt.wav</Play>
  •     </ConsultationBridge>
  •     <Redirect>connectfail</Redirect>
  • </Response>

8. 呼叫转接

  • 为用户发起呼叫转接,发起呼叫后主被叫会被立刻桥接,即主叫可以听到被叫的振铃音,只能作为主命令使用,如果被叫未接听、占线或拒接,将跳转到后续副命令中的呼转命令。命令名称<TransferCall>。

  • 属性
    名称属性值默认值说明
    number
    座机号码、手机号、通讯账号必填
    被咨询者的电话号码
    timeout
    正整数
    一直等待
    被叫未接听超时时长,被叫未接听超时后会执行后续的呼转命令
    record
    true、false
    false
    是否进行通话录音
    recordurl
    相对URL

    录音完成通知的回调地址
    calltime
    正整数
    0(不限时)
    设置通话的时间长度,单位是秒
    transferurl
    相对URL

    接通后被叫指定呼转请求的URL地址,被叫按*+分机号+#即可
    finishkey空。*键为功能键,不能设置为结束键。1234567890#结束键被叫未接通或接通后按此键结束呼叫。被叫未接通打断执行后续的呼转,接通后当hangupurl不为空的时候打断通话执行被叫挂机回调
    hangupurl相对URL

    被叫挂机回调的URL地址

  • 嵌套规则
    • 不支持嵌套命令。

  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <TransferCall number=”13800138000” record=”true”/>
  •     <Play>sorry.wav</Play>
  •     <Redirect>continue</Redirect>
  • </Response>

9. 发送DTMF

  • 发送DTMF按键。可作为主命令使用。若action为空则执行跳转命令。命令名称为<SendDTMF>。

  • 属性
    名称属性值默认值说明
    action
    相对URL

    发送结果的回调通知地址
    callid字符串必填
    若是Rest接口调用需要携带callid参数
    dtmf0123456789*#Ww必填按键内容,W表示延时1秒,w表示延时0.5秒
    waitresptime数字,单位毫秒
    500毫秒
    等待发送完成的时间; -1发送完成后上报、0立刻反回 >0等待的秒数,若发送优先完成则提前结束,不等待超时;默认值为-1

  • 嵌套规则
    • 此命令不支持嵌套。

  • 示例
  •     <?xml version="1.0" encoding="UTF-8"?>
  •     <Response>
  •       <SendDTMF action="senddtmfok" dtmf="123"/>
  •     <Redirect>otherservice</Redirect>
  •     </Response>

10. 业务跳转

  • 业务跳转到另一个URL地址,不可作为主命令使用。命令名称<Redirect>。返回呼转请求通知

  • 属性
    名称属性值默认值说明
    method
    GET、POST
    POST
    请求方法
    tag
    正整数
    0
    标识

  • 嵌套规则
    • 不嵌套其它命令也不能被嵌套。

  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <Play>paly.wav</Play>
  •     <Redirect tag="0">mmstory</Redirect>
  • </Response>

11. 通话连接

  • 将两用户进行连接通话,用户一方只能在做了Pause命令后才可执行此命令。命令名称<Connect>。

  • 属性
    名称属性值默认值说明
    mcallid
    十六进制串
    必填
    主叫用户callid
    scallid
    十六进制串
    必填
    被叫用户callid
    action
    相对URL

    连接成功的回调URL地址

  • 嵌套规则
    • 不支持嵌套命令。

  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  • <Connect mcallid ="13421304281638380001000000000001" callsid="16421304281638380001000000000002"/>
  •     <Redirect>connectfail</Redirect>
  • </Response>

12. 应用侧挂机

  • 应用侧挂机命令,可作为主、副命令使用,执行后会发起。命令名称<Hangup>。

  • 属性
    名称属性值默认值说明
    callid
    十六进制串
    必填
    呼叫id,平台侧为每个呼叫分配唯一id

  • 嵌套规则
    • 不能嵌套其它命令也不能被嵌套。

  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <Hangup callid ="13421304281638380001000000000009"/>
  • </Response>

13. 拒接

  • 应用侧拒接,可作为主命令使用,只能在启动业务请求后回复,其它情况下不建议使用。命令名称<Refuse>。

  • 属性
    名称属性值默认值说明
    reason
    refused、busy
    refused
    拒听原因

  • 嵌套规则
    • 可嵌套<Play>。

  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <Refuse reason="busy">
  •         <Play>SaySorry.wav</Play>
  •     </Refuse>
  • </Response>

14. 暂停

  • 命令说明:将用户的呼叫session暂停,并播放等待音,直AS侧再次发送命令来控制该用户。暂停时间到后会通<Redirect>命令反回给AS通知。命令名称<Pause>。

  • 属性
    名称属性值默认值说明
    callid十六进制串必填
    用户callid
    action相对URL
    成功后的回调地址
    pausetime数字1800秒暂停时长,单位是秒,默认是1800秒

  • 嵌套规则
    • 可嵌套<Play>。

  • 示例
  • <?xml version="1.0" encoding="UTF-8"?>
  • <Response>
  •     <Pause callid="13421304281638380001000000000001">
  •         <Play>waitmusic.wav</Play>
  •     </Pause >
  •     <Redirect>pausefinish</Redirect>
  • </Response>

15. 空指令

  • 应用侧只是对平台通知事件的响应,无需平台做任何事情。命令名称<CmdNone>。

  • 属性
  • 嵌套规则
    • 不能嵌套也不能被嵌套。

  • 示例
  • <?xml version="1.0" encoding="UTF-8" ?>
  • <Response>
  •     <CmdNone/>
  • </Response>