smart ivr 接口说明(电话机器人二次开发接口)
2018-02-03 11:09
1251 查看
smart ivr 接口说明
smartivr 是一个基于Freeswitch的电话机器人二次开发接口(restful),支持和Asterisk对接使用指南
用户自己实现 httpAPI,机器人程序去调用这个接口,不是 机器人提供httpapi给用户调用。外呼程序呼叫电话接通后,或者客户主动呼入接通后 机器人程序 向 webserver post 发送
smartivr –> web
``` { "calleeid": "8888abc", //被叫号码 "callerid": "abc", //主叫号码 "callid": "1fe74812-e376-4319-b335-3de1b494325c", //每个通话的唯一ID "errorcode": 0, //错误代码 "flowdata": null, //流程数据 "flowid": "abc", //流程ID "notify": "enter" //通知类型 } ```
webserver根据业务逻辑 返回 json数据 比如 下面的命令就是 启动后台ASR,并且播放一个声音
smartivr <– web
``` { "action": "start_asr", //第一个动作 start_asr是一个异步函数,只需要执行一次,启动后会一直进行VAD和ASR,直到调用sotp_asr "flowdata": "流程选择", //流程数据,类似浏览器的Cookie,机器人后续httpapi请求会把这个数据发送回来。 "params": { "min_speak_ms": 100, //最小说话时间,默认值100,单位毫秒,说话时间小于这个值,会被认为是无效声音。 "max_speak_ms": 10000, //最大说话时间,默认值10000,单位毫秒,说话时间超过这个值,就停止录音,直接提交ASR服务器识别。 "min_pause_ms": 300, //最小停顿时间,默认值300,单位毫秒,默认值用户停顿时间超过这个值,会提交到ASR识别。识别完成后发送asrprogress事件。 完成后的意思是 ASR服务器可能 300-800ms才返回识别接口。 "max_pause_ms": 600, //最大停顿时间,默认值600,单位毫秒,用户停顿时间超过这个值,认为一句话说完,所有识别完成后发送asrmessage事件。所有识别完成后的意思是,所有提交到asr服务器的识别结果都返回了。 注意 min_pause_ms 必须大于min_pause_ms。 "pause_play_ms": 200, //触发暂停放音时间,默认值0:就是禁用自动暂停,单位毫秒,建议设置200-1000,用户说话时间超过这个值,就暂停放音。 有时候用户一直持续说话,中间没停顿,所以还没提交到ASR服务器识别,不能使用关键词打断,可以先暂停放音。 "threshold": 0, //VAD阈值,默认0,建议不要设置,如果一定要设置,建议 2000以下的值。 "recordpath": "", //录音文件路径,如果不设置:就会使用配置文件中的路径,每天生成一个文件夹,如果设置了,就会使用这个参数中的目录,文件格式是 recordpath/被叫号码_Unique-ID_序号.wav "volume": 50 //音量标准化的值。0-100,0不使用音量标准化,其他值 音量把录音音量调整到这个值后,再提交ASR识别。 }, "after_action": "playback", "after_ignore_error": false, //如果action动作(start_asr)执行失败是否继续执行after_action(playback)。 "after_params": { "prompt": "您好,欢迎致电顶顶通软件,这里是电话机器人演示系统,请说要进入的测试流程,比如,房产!", //可以直接播放声音文件。规则就是如果最后4个字是.wav,就直接播放wav文件。 "wait": 5000, //单位毫秒,放音结束后等待时间。用于等待用户说话。 "retry": 0 //重播次数。就是wait时间内用户不说话,就重新播放声音。 } } ```
机器人程序执行 “action”:”start_asr” 开始后台ASR识别,然后执行”after_action”: “playback”开始播放声音文件。
当用户说话后,机器人发送 识别进度,也就是用户暂停说话时间超过 min_pause_ms
smartivr –> web
``` { "asrelapse": 391, //asr识别服务器消耗的时间,单位毫秒。 "asrtextall": "1.识别结果;", //包含之前停顿的识别结果的组合。 格式是 录音序号.识别结果;这样组合多个识别结果。 "asrtype": "aiui", //本次使用那个asr识别 "calleeid": "8888abc", "callerid": "abc", "callid": "1aec14af-d6a8-49e4-96fc-fb5f7cfdb893", "errorcode": 0, //asr返回错误,0无错误。 "flowdata": "流程选择", "flowid": "abc", "message": "识别结果", "notify": "asrprogress_notify", "recordindex": "1", //录音序号 "recordfile": "", //录音文件 "recordms": 931, //录音时间,单位毫秒。 "volumegain": 5.95330699999 //音量标准化放大或者缩小的倍数。 } ```
webserver根据业务逻辑返回是否需要暂停放音
smartivr <– web
``` { "action": "console_playback", "flowdata": "流程选择", "params": { "command": "pause" } } ```
当用户说完一整句话,机器人发送 完整的识别结果,也就是用户暂停说话时间超过 max_pause_ms
smartivr –> web
``` { "calleeid": "8888abc", "callerid": "abc", "callid": "ea6d1235-aaab-4251-b03b-3b53ca32e00d", "errorcode": 0, "flowdata": "流程选择", "flowid": "abc", "message": "1.你好;2.什么事;", "notify": "asrmessage_notify", "speakms": "1162" //整句话的说话时间,包含暂停时间 } ```
webserver根据业务流程,执行话说逻辑,播放声音。
smartivr <– web
``` { "action": "playback", "flowdata": "回答", "params": { "prompt": "先生你好,请问你最近需要买房吗", "wait": 3000, "retry": 2 } } ```
当用户一直不说话,声音播放完成并且等待时间超过,机器人发送 playback_result
smartivr –> web
``` { "calleeid": "8888abc", "callerid": "abc", "callid": "35bca774-5b3e-4129-a5e7-1c3c86605071", "errorcode": 0, "flowdata": "", "flowid": "abc", "message": "FILE PLAYED", "notify": "playback_result" } ```
webserver根据业务流程发送 继续放音,提示用户回答问题。
smartivr <– web
``` { "action": "playback", "flowdata": "提示选择流程", "params": { "prompt": "请问你要进入哪个测试流程,比如,房产", "wait": 3000, "retry": 2 } } ```
webserver 结束流程,播放一个提示声音,结束通话。
smartivr <– web
``` { "action": "playback", "suspend_asr": true, //播放提示音时候暂停ASR识别 "flowdata": "", "params": { "prompt": "谢谢你的使用,再见" }, "after_action": "hangup", "after_ignore_error": true, "after_params": { "cause": 0, "usermsg": "" } } ```
faq
asrprogress_notify 的 asrmessage_notify 区别
简单点说asrprogress_notify就是用来控制是否需要打断,asrmessage_notify用来控制是否需要播放一个新的声音。* asrprogress_notify 是识别进度通知,只能返回noop或者console_playback(pause)暂停放音。不能执行其他动作。asrprogress_notify后面可能再次出现asrprogress_notify,用户一整句话说完了,就会发送 asrmessage_notify 通知。
* asrmessage_notify 是识别完成通知,可以执行 playback 操作。播放一个新的声音,也可以noop,等其他任意动作。
* playback_result 声音播放完了,等待时间也超过了,还没检测到声音就发送这个通知。
console_playback(resume)恢复放音什么时候执行。
用户说话超过 pause_play_ms ,就会自动暂停放音,asrprogress_notify通知,ASR识别返回的是空,就是没识别到有效文本的时候,就可以返回 console_playback(resume) 来恢复放音了。可能不怎么好理解, 就是 start_asr 的 pause_play_ms 参数,可以设置,检测到用户说话时间超过这个参数,就自动停止放音, 如果是噪音的话,asrprogress_notify返回的是无效文本,就可以利用asrprogress_notify来恢复这个给自动暂停的放音。
playback_result 什么时候有这个通知
执行 playback后,播放完成并且等待超时,就会发送playback_result 通知。如果识别到用户说话,在 asrmessage_notify 事件中返回命令playback,播放了一个新的声音,那么上个playback会给强制终止(上次的playback_result就不会发送了。),新的播放完成时,才会发送playback_result。
如果识别到用户说话,在 asrmessage_notify 事件中返回命令noop,或者console_playback(resume),没去播放新的声音,那么还会发送playback_result 通知的。
自动放音暂停(打断)
start_asr 有一个参数 pause_play_ms,demo是200, 就是检测到声音持续时间时间超过pause_play_ms,就自动暂停放音。如果你不需要这个功能设置为0, 如果你启用了这个功能,asrmessage_notify通知你没播放一个新的声音就必须要恢复放音console_playback(resume)。否则会一直暂停。怎么实现关键词打断
asrprogress_notify 的识别结果如果是关键词 返回 console_playback(pause),如果不是关键词 返回 console_playback(resume)asrmessage_notify 的整句话识别结果如果匹配,直接播放新的声音文件,执行新的业务流程,如果不匹配,返回console_playback(resume)。
playback_result 收到这个通知,说明声音播放完成,等待用户说话超时,必须播放一个声音,提示用户说话。
接口说明
注意:请求和返回都采用JSON格式,编码为utf8,所有参数区分大小写,数字和字符串类型注意区分,参数未说明数字类型就是字符串类型。请求通用参数
calleeid 通话被叫号码callerid 通话被叫号码
callid 通话ID
notify 通知类型
enter 进入流程 比如来电应答后,外呼接通后进入流程
leave 离开流程 比如挂机,转移,直接转接等。
getdtmf_result 获取按键(dtmf)结果
playback_result 放音结果
bridge_result 转接结果
start_asr_result 后台ASR启动结果
stop_asr_result 后台ASR停止结果
asrprogress_notify ASR识别进度
asrmessage_notify ASR识别结果
flowdata 流程数据
flowid 流程ID
errorcode 错误代码 无错误时不存在这个值或者等于0
message 自定义消息
响应通用参数
action 执行的动作名getdtmf 获取DTMF按键
playback 播放声音
bridge 转接到电话号码
deflect 转移(SIP REFER )
hangup 挂断通话
noop 无操作,就是不需要执行任何动作。
start_asr 启动后台ASR
stop_asr 停止后台ASR
console_playback 控制放音
params action的参数,具体参考具体动作。
after_ignore_error 如果action执行是否是否继续执行after_action
after_action 可选参数 JOSN对象。用于连续执行2个动作,比如playback后执行挂机。
after_params 可选参数,JSON对象。after_action的参数内容。
flowdata 可选参数,JOSN对象。动作执行完成的notify请求里会把这个数据发送回来(用来携带流程数据 类似cookie)。
suspend_asr 可选参数,BOOL,如果之前已经执行了start_asr,通过通过这个参数,来暂停停用ASR,比如希望本次放音(playback),不要执行ASR,就可以把这个参数设置true.
notify 描述
enter 进入流程 比如来电应答后,外呼接通后进入流程
{"calleeid":"996","callerid":"linphone","callid":"e56aff85-f8e9-4385-a67b-b7881329860d","notify":"enter"}
leave 离开流程 比如挂机(hangup),deflect,transfer。
{“calleeid”:”996”,”callerid”:”linphone”,”callid”:”ceff27c7-fcd9-407c-9f9f-9ddea1a8aa5b”,”flowdata”:”“,”notify”:”leave”}asrprogress_notify
说话停顿min_speak_ms时间后返回的识别结果。asrtype 本次使用那个asr识别
message 本次asr识别结果
asrtextall 包含之前停顿的识别结果的组合。 格式是 录音序号.识别结果;这样组合多个识别结果。
asrelapse asr识别服务器消耗的时间,单位毫秒。
errorcode asr返回错误,0无错误。
volumegain 音量标准化放大或者缩小的倍数。
recordms 录音时间,单位毫秒。
recordindex 录音序号
recordfile 录音文件
asrmessage_notify
说话停顿max_speak_ms时间后返回的真句话的识别结果。message 整句话的识别结果。 格式是 录音序号.识别结果;这样组合多个识别结果。
speakms 整句话的说话时间,包含暂停时间
getdtmf_result
“* message 获取到的DTMF按键内容
* errorcode 错误代码
* terminator 结束符
* result 返回原因 success:按键个数等于max,或者输入结束符。timeout:按时返回
playback_result
{"calleeid":"996","callerid":"linphone","callid":"4e11935d-127f-45d0-b395-9d6aa4d3430d","errorcode":0,"flowdata":""message":"FILE PLAYED","notify":"playback_result"}
* errorcode 0 播放完成,其他播放错误
* message 错误信息。
bridge_result
{"calleeid":"996","callerid":"linphone","callid":"d0a3e9a8-2ce2-42e3-8fa7-55c5eb15326d","errorcode":480,"flowdata":"","hangupcause":"Temporarily Unavailable","message":"NO_USER_RESPONSE","notify":"bridge_result"}
* errocde sip返回的错误代码
* message 结果描述
* hangupcause SIP挂断原因
action 描述
start_asr
start_asr 是一个异步函数,只需要执行一次,启动后会一直进行VAD和ASR,直到调用sotp_asrmin_speak_ms 最小说话时间,默认值100,单位毫秒,说话时间小于这个值,会被认为是无效声音。
max_speak_ms 最大说话时间,默认值10000,单位毫秒,说话时间超过这个值,就停止录音,直接提交ASR服务器识别。
min_pause_ms 最小停顿时间,默认值300,单位毫秒,默认值用户停顿时间超过这个值,会提交到ASR识别。识别完成后发送asrprogress事件。 完成后的意思是 ASR服务器可能 300-800ms才返回识别接口。
max_pause_ms 最大停顿时间,默认值600,单位毫秒,用户停顿时间超过这个值,认为一句话说完,所有识别完成后发送asrmessage事件。所有识别完成后的意思是,所有提交到asr服务器的识别结果都返回了。 注意 min_pause_ms 必须大于min_pause_ms。
pause_play_ms 触发暂停放音时间,默认值0,就是禁用自动暂停,单位毫秒,建议设置200-1000,用户说话时间超过这个值,就暂停放音。 有时候用户一直持续说话,中间没停顿,所以还没提交到ASR服务器识别,不能使用关键词打断,可以先暂停放音。
threshold VAD阈值,默认0,建议不要设置,如果一定要设置,建议 2000以下的值。
recordpath 录音文件路径,如果不设置(使用配置文件设置录音目录(smartivr.json),),如果设置了会保存录音文件到这个目录,文件格式是 recordpath/被叫号码Unique-ID序号.wav
volume 音量标准化的值。0-100,0不使用音量标准化,其他值 音量把录音音量调整到这个值后,再提交ASR识别。
start_asr使用的配置文件
linux /etc/smartivr.json,windows freeswitchconsole.exe同一个目录
``` { "asr": { "aiui": { "key1": { "appid": "5a519267", "appkey": "e212fc8e4c9747a39fa1c56940e705be" }, "key2": { "appid": "5a519267", "appkey": "e212fc8e4c9747a39fa1c56940e705be" } } }, "system": { "record": { "path": "/var/smartivr/record" } } } ```
* aiui 是科大讯飞webapi接口的KEY,可以配置多个。
* record.path 是录音路径。
playback
播放一个声音文件prompt 声音内容wav文件(只支持8000hz,16位,单声道)或者文本。prompt 提示文本(如果最后4个字是.wav,就是录音文件放音,否则会调用TTS生成声音文件)。同样的文字TTS只转换一次,后续会使用缓存的文件
wait 单位毫秒,放音结束后等待时间。用于等待用户说话。
retry 重播次数。就是wait时间内用户不说话,就重新播放声音。
多文件或者TTS和录音文件混合放音
prompt 使用数值方式就可以,比如
``` [ "/var/wav/1.wav", "tts文字转声音", "/var/var/2.wav" ] ```
sotp_asr
停止后台ASR。console_playback
用于播放控制,用户说话开始,先暂停播放,如果说的是无效声音,可以恢复播放。command
pause 暂停播放
resume 恢复播放
stop 停止播放
bridge 转接电话
{"action":"bridge","flowdata":"","params":{"number":"sofia\/external\/a8008@sip.ddrj.com:16080","callerid":"","gateway":"","prompt":"\u6b63\u5728\u8f6c\u63a5\u4e2d\uff0c\u8bf7\u7b49\u5f85","background":"wating.wav"}}
* number 被叫号码,如果gateway没设置,必须是完整呼叫串类似:sofia/external/电话号码@网关Ip
* callerid 可选参数 主叫号码(对方看到的来电显示)
* gateway 可选参数 网关名字
* background 可选参数 背景音乐
* prompt 可选参数 提示文本 prompt 提示文本(如果最后4个字是.wav,就是录音文件放音,否则会调用TTS生成声音文件)。
hangup 挂机
{"action":"hangup","params":{"usermsg":"not found notify"}}
* cause [数字] 可选参数 挂断原因根据sip信令设置 详细看 https://freeswitch.org/confluence/display/FREESWITCH/Hangup+Cause+Code+Table
* usermsg 可选参数 里面可以放置调试信息,smartivr会打印到日志文件。
noop 不需要执行任何动作时可以返回这个,比如(leave,asr_progress 通知可以返回noop)
{"action":"noop","params":{"usermsg":""}}
* usermsg 可选参数 里面可以放置调试信息,smartivr会打印到日志文件。
deflect 执行后会直接离开流程,收到 leave 通知
{"action":"deflect","flowdata":"","params":{"number":"1001"}}
* number 要转移的目的地(由呼叫方处理) 即: SIP REFER 的 URI。
getdtmf 接收用户按键
{"action":"getdtmf","flowdata":"","params":{"prompt":"","invalid_prompt":"","min":0,"max":128,"tries":1,"timeout":5000,"digit_timeout":3000,"terminators":"#"}}
* min [数字] 最少按键个数(minimum value of 0)
* max [数字] 最多按键个数(maximum value of 128)
* tries [数字] 提示音播放次数
* timeout [数字] 等待按键最大时间,声音播放结束开始算起。
* terminators 结束输入按键,默认是#。
* prompt 提示音
* invalid_prompt 输入错误提示音
* regexp 输入按键规则(正则表达式)
* digit_timeout [数字] 按键超时时间,如果超时没有新按键,就认为输入完成。
相关文章推荐
- 电话机器人 开发 接口 适合那些用户
- Senparc.Weixin.MP SDK 微信公众平台开发教程(八):通用接口说明
- 工商银行EBank B2C支付接口v1.0.0.11 开发说明
- 关于eoLinker-AMS开源版 前端二次开发说明
- IE8 新增的Javascript 开发接口说明
- 你所在的专业最常用的支持二次开发软件是什么?它的开发接口都支持什么编程语言?
- YbSoftwareFactory 代码生成插件【三】:二次开发之 IPlugInRepository 接口的实现
- 开发编辑电话接口
- 微信公众平台消息接口开发 小黄鸡(小贱鸡)机器人 微信公众平台 公众号聊天机器人 ,消息,接口,小黄鸡,小贱鸡,机器人
- Caysn打印机IOS平台打印开发包、接口说明文档及示例程序_20170717
- ABB机器人ROBOTSTUDIO中轨迹与二次开发的问答
- Ecmall二次开发指南手册,ECMALL模板解析机制.MVC架构分析及文件目录说明.
- Senparc.Weixin.MP SDK 微信公众平台开发教程(十):多客服接口说明
- iOS开发:GET与POST接口网络请求以及对AFNetworking的二次封装
- 多口短信猫设备及相应二次开发接口程序
- ecshop二次开发的简单实例说明
- YbSoftwareFactory 代码生成插件二次开发IPlugInRepository接口的实现
- U850EAI二次开发说明,用友EAI二次开发说明下载
- 短信猫二次开发接口函数及规范
- Senparc.Weixin.MP SDK 微信公众平台开发教程(十三):地图相关接口说明