IVR 基础命令

来自落地电话、呼叫中心等语音和IVR、短信的SDK文档—云通讯平台
跳转到: 导航, 搜索

1 基础IVR命令

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

1.1 获取按键

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

属性

名称
属性值
默认值
说明
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
座机号码、手机号、VOIP号码
必填
被咨询者的号码
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
座机号码、手机号、VOIP号码 必填
被咨询者的电话号码
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>