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”开始播放声音文件。
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 //音量标准化放大或者缩小的倍数。
}
```
smartivr <– web
```
{
"action": "console_playback",
"flowdata": "流程选择",
"params": {
"command": "pause"
}
}
```
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" //整句话的说话时间,包含暂停时间
}
```
smartivr <– web
```
{
"action": "playback",
"flowdata": "回答",
"params": {
"prompt": "先生你好,请问你最近需要买房吗",
"wait": 3000,
"retry": 2
}
}
```
smartivr –> web
```
{
"calleeid": "8888abc",
"callerid": "abc",
"callid": "35bca774-5b3e-4129-a5e7-1c3c86605071",
"errorcode": 0,
"flowdata": "",
"flowid": "abc",
"message": "FILE PLAYED",
"notify": "playback_result"
}
```
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": ""
}
}
```
简单点说asrprogress_notify就是用来控制是否需要打断,asrmessage_notify用来控制是否需要播放一个新的声音。
* asrprogress_notify 是识别进度通知,只能返回noop或者console_playback(pause)暂停放音。不能执行其他动作。asrprogress_notify后面可能再次出现asrprogress_notify,用户一整句话说完了,就会发送 asrmessage_notify 通知。
* asrmessage_notify 是识别完成通知,可以执行 playback 操作。播放一个新的声音,也可以noop,等其他任意动作。
* playback_result 声音播放完了,等待时间也超过了,还没检测到声音就发送这个通知。
用户说话超过 pause_play_ms ,就会自动暂停放音,asrprogress_notify通知,ASR识别返回的是空,就是没识别到有效文本的时候,就可以返回 console_playback(resume) 来恢复放音了。
可能不怎么好理解, 就是 start_asr 的 pause_play_ms 参数,可以设置,检测到用户说话时间超过这个参数,就自动停止放音, 如果是噪音的话,asrprogress_notify返回的是无效文本,就可以利用asrprogress_notify来恢复这个给自动暂停的放音。
执行 playback后,播放完成并且等待超时,就会发送playback_result 通知。
start_asr 有一个参数 pause_play_ms,demo是200, 就是检测到声音持续时间时间超过pause_play_ms,就自动暂停放音。如果你不需要这个功能设置为0, 如果你启用了这个功能,asrmessage_notify通知你没播放一个新的声音就必须要恢复放音console_playback(resume)。否则会一直暂停。
注意:请求和返回都采用JSON格式,编码为utf8,所有参数区分大小写,数字和字符串类型注意区分,参数未说明数字类型就是字符串类型。
{"calleeid":"996","callerid":"linphone","callid":"e56aff85-f8e9-4385-a67b-b7881329860d","notify":"enter"}
{“calleeid”:”996”,”callerid”:”linphone”,”callid”:”ceff27c7-fcd9-407c-9f9f-9ddea1a8aa5b”,”flowdata”:”“,”notify”:”leave”}
说话停顿min_speak_ms时间后返回的识别结果。
说话停顿max_speak_ms时间后返回的真句话的识别结果。
“
* message 获取到的DTMF按键内容
* errorcode 错误代码
* terminator 结束符
* result 返回原因 success:按键个数等于max,或者输入结束符。timeout:按时返回
{"calleeid":"996","callerid":"linphone","callid":"4e11935d-127f-45d0-b395-9d6aa4d3430d","errorcode":0,"flowdata":""message":"FILE PLAYED","notify":"playback_result"}
* errorcode 0 播放完成,其他播放错误
* message 错误信息。
{"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挂断原因
start_asr 是一个异步函数,只需要执行一次,启动后会一直进行VAD和ASR,直到调用sotp_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 是录音路径。
播放一个声音文件
prompt 使用数值方式就可以,比如
```
[
"/var/wav/1.wav",
"tts文字转声音",
"/var/var/2.wav"
]
```
停止后台ASR。
用于播放控制,用户说话开始,先暂停播放,如果说的是无效声音,可以恢复播放。
{"action":"bridge","flowdata":"","params":{"number":"sofia\/external\/[email protected]: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生成声音文件)。
{"action":"hangup","params":{"usermsg":"not found notify"}}
* cause [数字] 可选参数 挂断原因根据sip信令设置 详细看 https://freeswitch.org/confluence/display/FREESWITCH/Hangup+Cause+Code+Table
* usermsg 可选参数 里面可以放置调试信息,smartivr会打印到日志文件。
{"action":"noop","params":{"usermsg":""}}
* usermsg 可选参数 里面可以放置调试信息,smartivr会打印到日志文件。
{"action":"deflect","flowdata":"","params":{"number":"1001"}}
* number 要转移的目的地(由呼叫方处理) 即: SIP REFER 的 URI。
{"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 [数字] 按键超时时间,如果超时没有新按键,就认为输入完成。