繁依Fanyi0

这个屌丝很懒，什么也没留下！

热门标签

smartivr 接口说明（电话机器人二次开发接口）_二次开发ivr

作者：繁依Fanyi0 | 2024-08-21 07:20:55

踩

二次开发ivr

smartivr 接口说明

smartivr 是一个基于Freeswitch的电话机器人二次开发接口（restful），支持和Asterisk对接

联系我

微信：cdevelop qq:1280791187 我的网站:www.ddrj.com

使用指南

用户自己实现 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"			//通知类型
 }
 ```
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": "1aec14af-d6a8-49e4-96fc-fb5f7cfdb893",
 	"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信令设置详细看 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 [数字] 按键超时时间，如果超时没有新按键，就认为输入完成。

声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/繁依Fanyi0/article/detail/1010763

smartivr 接口说明（电话机器人二次开发接口）_二次开发ivr

smartivr 接口说明

联系我

使用指南

faq

asrprogress_notify 的 asrmessage_notify 区别

console_playback(resume)恢复放音什么时候执行。

playback_result 什么时候有这个通知

自动放音暂停（打断）

怎么实现关键词打断

接口说明

请求通用参数

响应通用参数

notify 描述

enter 进入流程 比如来电应答后，外呼接通后进入流程

leave 离开流程 比如挂机(hangup)，deflect，transfer。

asrprogress_notify

asrmessage_notify

getdtmf_result

playback_result

bridge_result

action 描述

start_asr

start_asr使用的配置文件

playback

多文件或者TTS和录音文件混合放音

sotp_asr

console_playback

bridge 转接电话

hangup 挂机

noop 不需要执行任何动作时可以返回这个，比如(leave,asr_progress 通知可以返回noop)

deflect 执行后会直接离开流程，收到 leave 通知

getdtmf 接收用户按键

enter 进入流程比如来电应答后，外呼接通后进入流程

leave 离开流程比如挂机(hangup)，deflect，transfer。