一起养成写作习惯！这是我参与「掘金日新计划 · 4 月更文挑战」的第19天，点击查看活动详情。
smartivr 接口说明
smartivr 是一个基于Freeswitch的电话机器人二次开发接口（restful），支持和Asterisk对接
使用指南 用户自己实现 httpAPI,机器人程序去调用这个接口，不是 机器人提供httpapi给用户调用。
外呼程序呼叫电话接通后，或者客户主动呼入接通后 机器人程序 向 webserver post 发送
smartivr --> web
{
"calleeid": "weixin@yuyinjiqiren", //被叫号码
"callerid": "abc", //主叫号码
"callid": "weixin@yuyinjiqiren", //每个通话的唯一ID
"errorcode": 0, //错误代码
"flowdata": null, //流程数据
"flowid": "abc", //流程ID
"notify": "enter" //通知类型
}
1 2 3 4 5 6 7 8 9 10 11 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时间内用户不说话，就重新播放声音。
}
}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 机器人程序执行 “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": "weixin@yuyinjiqiren",
"errorcode": 0, //asr返回错误，0无错误。
"flowdata": "流程选择",
"flowid": "abc",
"message": "识别结果",
"notify": "asrprogress_notify",
"recordindex": "1", //录音序号
"recordfile": "", //录音文件
"recordms": 931, //录音时间，单位毫秒。
"volumegain": 5.95330699999 //音量标准化放大或者缩小的倍数。
}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 webserver根据业务逻辑返回是否需要暂停放音 smartivr <-- web
{
"action": "console_playback",
"flowdata": "流程选择",
"params": {
"command": "pause"
}
}
1 2 3 4 5 6 7 8 9 当用户说完一整句话，机器人发送 完整的识别结果，也就是用户暂停说话时间超过 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" //整句话的说话时间，包含暂停时间
}
1 2 3 4 5 6 7 8 9 10 11 12 13 webserver根据业务流程，执行话说逻辑，播放声音。 smartivr <-- web
{
"action": "playback",
"flowdata": "回答",
"params": {
"prompt": "先生你好，请问你最近需要买房吗",
"wait": 3000,
"retry": 2
}
}
1 2 3 4 5 6 7 8 9 10 11 当用户一直不说话，声音播放完成并且等待时间超过，机器人发送 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"
}
1 2 3 4 5 6 7 8 9 10 11 12 webserver根据业务流程发送 继续放音,提示用户回答问题。 smartivr <-- web
{
"action": "playback",
"flowdata": "提示选择流程",
"params": {
"prompt": "请问你要进入哪个测试流程，比如，房产",
"wait": 3000,
"retry": 2
}
}
1 2 3 4 5 6 7 8 9 10 11 webserver 结束流程，播放一个提示声音，结束通话。
smartivr <-- web
{
"action": "playback",
"suspend_asr": true, //播放提示音时候暂停ASR识别
"flowdata": "",
"params": {
"prompt": "谢谢你的使用，再见"
},
"after_action": "hangup",
"after_ignore_error": true,
"after_params": {
"cause": 0,
"usermsg": ""
}
}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 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_asr
min_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"
}
}
}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 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"]
1 2 3 4 5 6 7 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信令设置 详细看 freeswitch.org/confluence/… 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 [数字] 按键超时时间，如果超时没有新按键，就认为输入完成。
————————————————
