IVR 基础命令_开发文档

名称	属性值	默认值	说明
action	相对URL	当前文档URL/dtmfreport	自定义url的地址，参数为空或者不带此参数再回调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。

1.2 放音

播放语音文件，支持wav和mp3语音格式文件，可作为主、副命令使用，放音完成后跳转将执行后续副命令中的呼转命令。命令名称为<Play>。

属性

名称	属性值	默认值	说明
loop	整数，0不播放 -1无限循环播放	1	播放次数
finishkey	数字、*、#	空	结束键
isrecord	true or false	false，不是录音文件	是否是平台录音文件

嵌套规则

此命令不支持嵌套。

示例


<?xml version="1.0" encoding="UTF-8" ?>
<Response>
    <Play>cowbell.wav</Play>
    <Redirect>otherservice</Redirect>
</Response>

放音文件说明

当isrecord=“true”的时候，放音文件名必需是云通讯返回的录音文件名，放音文件的格式样本如下：位速 128kbps，音频采样大小16位，频道 1(单声道)，音频采样级别 8 kHz，音频格式 PCM。这样能保证放音的清晰度。

1.3 播放混合音

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

属性

名称	属性值	默认值	说明
finishkey	数字、*、#	0123456789#*	结束键
type	0字符串、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”。

1.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发起指定方法请求。

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

1.6 咨询呼叫

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

属性

名称	属性值	默认值	说明
number	座机号码、手机号、通讯账号	必填	被咨询者的号码
action	相对的URL	空	被咨询侧接听后请求的URL，若为空则自动桥接咨询侧与被咨询侧。不为空，被咨询侧应答就上报通知消息(需要在上报的通知消息返回咨询呼叫桥接命令，否则不会桥接造成无法通话)。被咨询侧接听则< ConsultationCall >后的动词将不会执行；如果被咨询侧未接听、占线或拒接，将被执行<ConsultationCall>中noanswerurl的被咨询侧未接听挂机通知，noanswerurl空则将被执行<ConsultationCall>后的呼转通知。
ringback	true or false	false	咨询侧是否听被咨询侧回铃音；当action参数为空时有效；
method	GET、POST	POST	请求方法
timeout	正整数	一直等待	被咨询侧接听超时时长，被咨询侧超时未接听后会执行后续的呼转命令
finishkey	数字、#、*	空，用户无法结束	咨询呼叫结束符，在被咨询者未接听前，结束键始终有效，咨询侧按结束符，将被执行咨询侧主动结束呼叫的回调地址
cancelurl	相对URL	cancelconsultation	咨询侧主动结束呼叫的回调地址
record	true、false	false	是否进行通话录音
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>

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

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

1.9 发送DTMF

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

属性

名称	属性值	默认值	说明
action	相对URL	空	发送结果的回调通知地址
callid	字符串	必填	若是Rest接口调用需要携带callid参数
dtmf	0123456789*#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>

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

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

1.12 应用侧挂机

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

属性

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

嵌套规则

不能嵌套其它命令也不能被嵌套。

示例


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

1.13 拒接

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

属性

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

嵌套规则

可嵌套<Play>。

示例


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

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

1.15 空指令

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

属性

无

嵌套规则

不能嵌套也不能被嵌套。

示例

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