smartivr 接口说明 (智能电话机器人话术开发接口) | 顶顶通 - 呼叫中心二次开发接口,smartivr,mod_vad,FreeSWITCH,语音识别,呼叫中心中间件,电话机器人,空号检测,智能外呼。

使用指南

smartivr 为福州晋安区顶顶通软件有限公司开发的软件产品，受中华人民共和国著作权法保护，侵权必究

用户自己实现 httpAPI,机器人程序去调用这个接口，不是机器人提供httpapi给用户调用。

外呼程序呼叫电话接通后，或者客户主动呼入接通后机器人程序向 webserver post 发送

smartivr –> web

{
	"calleeid": "8888",			//被叫号码 对于自动外呼是是流程ID
	"callerid": "1500000",		//主叫号码 对于自动外呼是被叫号码
	"origcallerid": "",			//原始主叫 对于自动外呼是主叫号码
	"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)暂停放音，console_playback(resume)恢复放音。不能执行其他动作。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 通知的。
如果asrprogress_notify 返回 console_playback(pause)暂停了播放，asrmessage_notify没有返回console_playback(resume)恢复放音，那么就一直卡着。这样的用法是错误的，asrmessage_notify 如果没有返回playback播放新的声音，就必须console_playback(resume)恢复放音。

自动打断（就是检测到声音，就自动停止放音）

start_asr 有一个参数 pause_play_ms，demo是200，就是检测到说话声音持续时间时间超过pause_play_ms，就自动暂停放音。如果你不需要这个功能设置为0，如果你启用了这个功能，asrmessage_notify通知每播放一个新的声音就必须要恢复放音console_playback(resume)。否则机器人放音一直暂停着(收不到playback_result通知)。

业务打断(就是流程停止放音，或者播放一个新的声音实现打断。)

asrprogress_notify返回 console_playback(pause)，或者asrmessage_notify返回播放新的声音，就会停止播放当前的声音。

怎么禁用打断功能

机器人放音的时候可以识别用户说话，但是不打断机器人放音：playback的allow_interrupt设置-1,关闭自动打断。asrprogress_notify返回 noop。 asrmessage_notif
如果playstate等于false（当前没放音），执行业务逻辑播放新的声音。asrmessage_notif如果playstate等于true（当前在放音，不处理），返回noop，并且把识别结果记录到flowdata,等paly_result的时候再处理识别结果。如果paly_result的时候检测放音过程是否有识别结果，如果有执行业务逻辑处理流程，如果没有返回wait.
放音的时候直接暂停asr, 自然也就不会打断了。playback的block_asr设置为-1.本次放音，禁用了asr，就可以了。

噪音打断怎么解决(升级到5.0使用噪音人声识别可以解决噪音问题)

如果要完全避免噪音打断可以把自动打断关闭，使用关键词打断。如果要求不高可以把pause_play_ms设置大些，比如1000。playback新加了一个自动打断控制参数，可以设置本次机器人放音多久才启用自动打断。

怎么实现关键词打断

start_asr的pause_play_ms 设置 0 ，关闭自动打断
asrprogress_notify 的识别结果如果是关键词返回 console_playback(pause)，如果不是关键词返回 noop
asrmessage_notify 的整句话识别结果如果匹配，直接播放新的声音文件，执行新的业务流程，如果不匹配, 判断playstate（户说话结束的时候，机器人是否也放音完成），playstate为true返回console_playback(resume),playstate为false,执行playback_result通知一样的流程。
playback_result 收到这个通知，说明声音播放完成，等待用户说话超时，asrstate为true是表示用户当前已经在说话，可以返回noop，否则必须播放一个声音，提示用户说话。

多种打断方案集合使用流程

start_asr 开始asr,设置 pause_play_ms 为 200-1000之间（设置自动打断时间）
playback wait设置 3000-5000,并且设置allow_interrupt动态修改自动打断时间，
asrprogress_notify 检查是否有关键词有关键词返回console_playback(pause)，没关键词返回 noop
asrmessage_notify 根据识别结果，playms(用来判断是否机器人刚说话，用户也开始说话) ，playstate（用来判断用户说话结束的时候，机器人是否也放音完成），等条件返回console_playback(resume)继续放音，或者返回playback播放一个新的声音。
playback_result asrstate为true是表示用户当前已经在说话，可以返回noop，否则必须播放一个声音，提示用户说话。

怎么实现放音的时候暂停ASR（就是机器人说话的时候，不识别用户说话，也不打断机器人说，类似单工模式一个人说一个人听。）

2.3版本playback添加了一个参数block_asr,playback的时候把block_asr设置为-1，就可以了。

机器人刚放音，用户也开始说话,或者用户刚开始说话机器人也开始放音，怎么解决。

asrprogress_notify和asrmessage_notify 新加了一个参数 playms,playms意思是用户开始说话时机器人放音时间（如果大于0就是放音时间），0就是机器人没在放音。
asrmessage_notify 的参数 playstate 表示用户说话结束的时候（发送asrmessage的时候）机器人是否在放音。
由此可以推断出 asrmessage_notify 的时候如果 playms>0并且<2000（自己定义一个合适的）,说明机器人刚开始放音用户就开始说话了。
如果 playms等于0，playstate等于true,说明用户刚开始说话，机器人也开始放音了。

超时的时候，用户刚好开始说话了怎么办

wait_result 和 playback_result 新加了1个参数 asrstate为true是表示用户当前已经在说话，可以返回noop。否则必须返回wait,或者playback.

性别识别（男性女性声音识别）

asrprogress_notify 加了一个参数 gender 0未识别 1女 2男 3可能女 4可能男其他系统错误

噪音人声识别(mod_vad 5.0开始支持)

如果有噪音识别授权 start_asr的filter_level 设置为 0.6：一句话结束判断声音是否是噪音。 0.7: 噪音的时候不掉用ASR。 0.8：VAD算法集成噪音和人声识别。在0.6和0.7时设置asrprogress_notify 参数 noise 0:人声 1:噪音 -1:未启用。

怎么获取录音文件名

asrprogress_notify 通知的 recordfile 字段就是本次识别的录音文件。
asrmessage_notify 通知的 message 格式是录音序号.识别结果; 其实通过这个录音序号就知道录音文件名的。因为录音文件名规范是 recordpath/callerid_callid_recordindex.wav 这样固定的格式的。你可以把被叫号码，callid，录音序号组合一下就知道这个识别结果关联的文件名了。

一句话怎么有时候有多个录音文件

因为用户说话停顿时间超过 min_pause_ms ，就提交ASR识别（如果配置了保存录音会生成一个录音文件），识别结果通过 asrprogress_notify 通知业务程序。
停顿时间超过 max_pause_ms 认为说完一整句话，就发送asrmessage_notify通知给业务程序。
如果说一句话的过程，用户多次停顿，并且时间在 min_pause_ms和max_pause_ms之间，就会产生多个录音文件。
对接暂时界面上，好比我们微信聊天，对方说2句你回复1句是完全正常的情况，网页上展示2个或者多个录音文件就可以。
如果你想尽量的不要出现多次asrprogress_notify，可以把 min_pause_ms 设置大些，比如 min_pause_ms和max_pause_ms都设置800。这时候用户停顿800，才提交ASR，ASR识别的时候如果用户不说话，识别完成马上就发送asrmessage_notify通知，如果识别过程，用户又说话了，还是需要等新的ASR识别结果返回后，在发送asrmessage_notify，就出现多个asrprogress_notify了。

怎么知道主叫挂断还是被叫挂断

leave新加了一个参数 hangup_disposition recv_bye：对方先挂机， send_bye：机器人先挂机。

怎么把通话转接给分机或者手机

bridge就是实现这个功能的，可以把用户电话转接给分机或者客服手机，具体看bridge和bridge_result说明。

机器人一直不说话

流程出现这个问题一般是 playback_result通知asrstate等于false时没播放新的声音，或者asrmessage_notify没匹配关键词，并且playstate等于false的时候没播放新的声音。 playback_result通知asrstate等于false时和asrmessage_notify通知playstate等于false，这2个情况必须播放一个声音或者执行wait, 千万不要返回noop或者console_playback。

after_action 注意问题

例如 after:sotp_asr after_action:bridge, 如果没有先执行start_asr,那么sotp_asr就会失败，如果没设置after_ignore_error:true,就不会执行bridge。注意点 after_ignore_error：true，才会不管第一个指令是否成功都执行第二个指令。
例如 after:sotp_asr after_action:bridge，sotp_asr指令还没执行的时候，可能出现asrmessage_notify通知，这样就破坏了组合指令的执行，设置 suspend_asr：true,系统就不会把 asrmessage_notify 通知发送给接口，避免 after和after_action之间出现asrprogress_notify和asrprogress_notify 通知干扰。

执行palyabck之后，收到了上一个palyback放音的识别结果，怎么区分。

3.0版本 asrprogress_notify 的 asrmessage_notify 通知加了一个lag参数，lag为true，就是上一个动作的识别结果。

场景说明，用户先说，哪里，过了1秒再说，哦不需要了。 smartivr先通知 “哪里”的识别结果，流程返回playback,这个声音文件还没开始播放， smartivr又通知 “哦不需要了”的识别结果。 “哦不需要了”的识别结果的lag会为true,流程判断lag就可以处理这样的情况了。

接口说明

注意：请求和返回都采用JSON格式，编码为utf8,所有参数区分大小写,数字和字符串类型注意区分，参数未说明数字类型就是字符串类型。

请求通用参数

calleeid 通话被叫号码自动外呼是流程ID（可以用来区分流程）
callerid 通话主叫号码自动外呼是被叫号码
origcallerid 通话原始主叫号码自动外呼是主叫号码
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识别结果
- wait_result 等待超时
- transfer_result 转接完成
flowdata 流程数据
flowid 流程ID（可以设置为外呼任务ID）
errorcode 错误代码无错误时不存在这个值或者等于0
message 自定义消息
duration 持续时间，enter开始计时，可以用于控制对话总时间，比如持续时间超过3分钟就挂断通话。
duration 持续时间，enter开始计时，可以用于控制对话总时间，比如持续时间超过3分钟就挂断通话。
hangup 通话是否挂断，true已经挂断，false,未挂断。比如playback_result,wait_result,可以见检测一下通话是否挂断，如果已经挂段直接返回noop就可以。(注意发现FS在高并发下有BUG，会乱送CHANNEL_HANGUP消息，导致这个属性不准，请忽略这个属性,如果要解决放音的时候用户挂机问题，要结合 “errorcode”:-1, “message”:”PLAYBACK ERROR”,”notify”:”playback_result” 一起判断)

响应通用参数

action 执行的动作名

* getdtmf   获取DTMF按键
* playback  播放声音
* bridge    转接到电话号码
* deflect   转移（SIP REFER ）
* hangup    挂断通话
* noop      无操作，就是不需要执行任何动作。
* start_asr 启动后台ASR
* stop_asr  停止后台ASR
* console_playback 控制放音
* wait      等待 比如playback的时候设置suspend_asr关闭了ASR功能放音结束后可以用 wait + suspend_asr开启ASR功能，并且设置一个超时时间。
* transfer  转移，转移到指定的dialplan ,需要配合FreeSWITCH的dialplan使用
* redirect  重定向接口地址（4.3.2以上版本支持，只能enter通知时回复）

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. 注意：2.3版本后 playback添加了一个block_asr的参数可以更灵活的控制暂停识别。建议使用block_ack参数代替suspend_asr。

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"}

hangup_disposition recv_bye：对方先挂机， send_bye：机器人先挂机。

asrprogress_notify

说话停顿min_pause_ms时间后返回的识别结果。

asrtype 本次使用那个asr识别
message 本次asr识别结果
asrtextall 包含之前停顿的识别结果的组合。格式是录音序号.识别结果;这样组合多个识别结果。
asrelapse asr识别服务器消耗的时间，单位毫秒。
errorcode asr返回错误，0无错误。
volumegain 音量标准化放大或者缩小的倍数。
recordms 录音时间，单位毫秒。
recordindex 录音序号
recordfile 录音文件
gender 性别识别 0未识别 1女 2男 3可能女 4可能男其他系统错误每个电话只识别前3句话。
noise 0人声 1噪音 -1未启用
playms 检测到说话声音起点时播放声音时间，0没放音，其他放音时间
lag 布尔类型 true:本次识别结果是上一个动作的时候产生的,具体看faq lag说明
asrmessage_notify

说话停顿max_pause_ms时间后返回的真句话的识别结果。

message 整句话的识别结果。格式是录音序号.识别结果;这样组合多个识别结果。
speakms 整句话的说话时间，包含暂停时间
playms 检测到说话声音起点时播放声音时间，0没放音，其他放音时间
playstate 说话结束的时候（发送asrmessage的时候）是否还在放音。
quiescems 如果playstate 为false时会设置这个值（smartivr 5.13开始支持）放音停止时到当前的时间。
playpause 如果playstate为true的时候会这则这个值（smartivr 5.13开始支持）是否暂停了放音(比较自动打断)。
lag 布尔类型 true:本次识别结果是上一个动作的时候产生的具体看faq lag说明。

getdtmf_result

获取DTMF返回

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 错误信息。
asrstate 当前用户是否在在说话
bridge_result
转接结束，转接失败，或者转接成功通话结束才收到这个通知。收到这个通知后请挂断通话(返回 hangup)，也可以继续执行asr流程。
{"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返回的错误代码，0转接成功，
message 结果描述
hangupcause SIP挂断原因

transfer_result

{"calleeid":"8888","callerid":"linphone","callid":"1811135d-fae2-4550-978c-f5dd972a1483","errorcode":0,"flowdata":"","flowid":"","message":"_none_","notify":"transfer_result"}

转移到其他流程完成，注意电话挂断后才会发送 leave

stop_asr_result

停止后台asr完成

calleeid":"8888","callerid":"linphone","callid":"e757f1c1-c890-4b03-bced-dfdf84fd2419","errorcode":0,"flowdata":"","flowid":"","message":"SUCCEED","notify":"stop_asr_result"}

wait_result

等待超时

message 不使用
asrstate 当前用户是否在在说话

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服务器的识别结果都返回了。注意 max_pause_ms 必须大于min_pause_ms。
pause_play_ms 触发暂停放音时间，默认值0，就是禁用自动打断，单位毫秒，建议设置200-1000，用户说话时间超过这个值，就暂停放音。有时候用户一直持续说话，中间没停顿，所以还没提交到ASR服务器识别，不能使用关键词打断，需要自动暂停放音。playback的allow_interrupt可以动态调整这个值。
threshold VAD阈值，默认0，建议不要设置，如果一定要设置，建议 2000以下的值。
recordpath 录音文件路径，如果不设置(使用配置文件设置录音目录(smartivr.json)，)，如果设置了会保存录音文件到这个目录，录音文件名规范是 recordpath/callerid_callid_recordindex.wav。
volume 音量标准化的值。0-100，0不使用音量标准化，其他值音量把录音音量调整到这个值后，再提交ASR识别。
filter_level 防止干扰等级。0-1.0之间，无特殊要求设置为0。如果有噪音识别授权 0.6：一句话结束判断声音是否是噪音,通过asrprogress事件的noise标识。 0.7: 噪音的时候不掉用ASR。 0.8：VAD算法集成噪音和人声识别。
asr_configure_filename asr配置文件名。可以不同呼叫使用不同的ASR配置。不设置就是使用默认配置(smartivr.json)

start_asr使用的配置文件

linux /etc/smartivr.json,windows freeswitchconsole.exe同一个目录 ,具体看配置说明

playback

播放一个声音文件

prompt 声音内容wav文件(只支持8000hz,16位，单声道)或者文本。prompt 提示文本（如果最后4个字是.wav，就是录音文件放音，否则会调用TTS生成声音文件）。同样的文字TTS只转换一次，后续会使用缓存的文件
wait 单位毫秒，放音结束后等待时间。用于等待用户说话。
retry 重播次数。就是wait时间内用户不说话，就重新播放声音。
block_asr 本次放音是否暂停ASR，（也就是关闭打断，同时不识别用户说话）
- -1 放音的时候不识别，进入等待的时候开启识别，比如 playback(file=”1.wav”,wait=5000) 就是播放1.wav的时候不识别，进入等待(5000毫秒)的时候开始识别用户说话。
- 0 禁用这个参数，不改变ASR状态。
- 大于0 单位毫秒，放音前面多少秒不识别。 playback(file=”1.wav”,wait=5000,block_asr=3000) 假如1.wav长度10秒，就是1.wav播放3秒后启动识别，前3秒忽略用户说话。
tts_configure_filename tts配置文件名(绝对路径)，不设置会使用默认smartivr.json.
allow_interrupt 本次放音是否允许自动打断，0使用start_asr的pause_play_ms参数，，-1禁用自动打断（忽略start_asr->pause_play_ms参数），大于0就是覆盖start_asr->pause_play_ms参数设置。默认自动打断时间是 start_asr->pause_play_ms参数指定的。注意：这个只是动态修改pause_play_ms的参数，对于业务控制的打断（暂停放音）没作用。
block_interrupt 放音前面多少毫秒内禁止自动打断（smartivr 5.1.3 update 20230323开始支持）。

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

prompt 使用数组方式就可以，比如

[
	"/var/wav/1.wav",
	"tts文字转声音",
	"/var/var/2.wav"
]

sotp_asr

:{"action":"stop_asr","flowdata":"\u8bed\u97f3\u8bc6\u522b"}

停止后台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 可选参数网关名字，如果注册模式也可以直接 user/分机号这样的格式。
background 可选参数背景音乐
prompt 可选参数提示文本 prompt 提示文本（如果最后4个字是.wav，就是录音文件放音，否则会调用TTS生成声音文件）。
timeout 可选参数设置转接超时。

注意请先执行 stop_asr,不然转接后还会继续进行语音识别

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) ，注意最小和最大按键个数只有放音的按键才行，等待时候按键达到最小按键就返回了。如果最小按键设置为0，那么就不会等待按键，放音完成就返回。
max [数字] 最多按键个数(maximum value of 128)
tries [数字] 提示音播放次数
timeout [数字] 等待按键最大时间，声音播放结束开始算起。
terminators 结束输入按键，默认是#。
prompt 提示音
invalid_prompt 输入错误提示音
regexp 输入按键规则（正则表达式）
digit_timeout [数字] 按键超时时间，如果超时没有新按键，就认为输入完成。

transfer 执行后，要等电话挂断才会收到 leave 通知

action":"stop_asr","flowdata":"\u8bed\u97f3\u8bc6\u522b","after_action":"transfer","after_ignore_error":false,"after_params":{"destnumber":"test","dialplan":"XML","context":"default"}}

destnumber 要转移的目的地
dialplan 默认XML
context 默认default

注意请先执行 stop_asr,不然还是继续进行语音识别

wait 等待

{"action":"wait","flowdata":"","params":{"timeout":1000}}

timeout 数字型单位毫秒

redirect 重定向接口地址

（4.3.2以上版本支持，只能enter通知时回复,会对新的接口地址重新发送enter,flowdata如果不为空，会使用返回的flowdata,如果空，使用默认的）

{"action":"redirect","flowdata":"","url":"新接口地址"}

url 新的接口地址

流接口支持(3.0版本开始支持)

流接口是VAD检测到开始说话就把语音流直接提交到 ASR 进行实时识别，这样识别速度比HTTP接口更实时。流接和http接口asrprogressnotify 、asrmessagenotify 通知参数有些差异，本文档将描述这些差异。

启用流接口

start_asr的asrconfigurefilename参数设置为 stream:127.0.0.1:9988,就可以了，格式是 stream:流识别代理服务器IP：端口。
流接口不支持男女识别，start_asr的volume 参数不会使用。

asrprogress_notify （流接口每说1-2个字就会发出 asrprogress_notify 通知。）

{“asrtype”:”stream”,”calleeid”:”8888”,”callerid”:”1000”,”callid”:”2df6b327-a8ef-416d-9504-721c5d71ce35”,”duration”:15,”errorcode”:0,”flowdata”:null,”flowid”:””,”hangup”:false,”message”:”你”,notify”:”asrprogress_notify”,”origcallerid”:”1000”,”playms”:0}

{“asrtype”:”stream”,”calleeid”:”8888”,”callerid”:”1000”,”callid”:”2df6b327-a8ef-416d-9504-721c5d71ce35”,”duration”:15,”errorcode”:0,”flowdata”:null,”flowid”:””,”hangup”:false,”message”:”你好”,notify”:”asrprogress_notify”,”origcallerid”:”1000”,”playms”:0}

比http接口少了以下参数。
asrtextall
asrelapse
errorcode
volumegain
recordms
recordindex
recordfile
gender
noise

录音文件http接口是 asrprogressnotify 通知的时候生成录音文件。流接口是 asrmessagenotify 通知的时候生成录音文件。
识别结果，http接口是一段话通知一次识别结果，流接口是1-2个字通知一次识别结果。

asrmessage_notify

{“calleeid”:”8888”,”callerid”:”1000”,”callid”:”2df6b327-a8ef-416d-9504-721c5d71ce35”,”duration”:17,”errorcode”:0,”flowdata”:null,”flowid”:””,”hangup”:false,”message”:”你好?,”notify”:”asrmessage_notify”,”origcallerid”:”1000”,”playms”:0,”playstate”:false,”recordfile”:”./asr/20190531/1000_2df6b327-a8ef-416d-9504-721c5d71ce35_1.wav”,”speakms”:1285}

加了recordfile参数
message参数没有序号。

人工监听和接管(3.02版本开始支持)

就是坐席可以监听机器人和客户对话，通过按DTMF*，可以直接接管机器人直接和客户对话。

监听

{“action”:”eavesdrop”,”flowdata”:{“flowtype”:”default”},”params”:{“dialstring”:”user\/1001”,”callerid”:”8888”},”after_action”:”playback”,”after_ignore_error”:true,”after_params”:{“prompt”:”开始呼叫分机实施监听，机器人流程可以继续执行”}}

action:eavesdrop，params.dialstring:这个是一个拨号串，分机例子：user/1000，外线例子:sofia/external/电话号码@vosip
系统会呼叫这个电话，电话接通后，就处于监听模式，听到机器人和用户对话。

是否已经开始监听成功，没有事件通知，如果需要知道是否监听成功，请使用sip.js,sipml5，或者sip客户端，接到电话去反馈结果。

如果需要分机接通后自动接管eavesdrop动作添加一个参数 “skip_eavesdrop”:true (smartivr 4.8.5 开始支持)

如果需要分机接通后，等待机器人当前放音完成时自动接管eavesdrop动作添加一个参数 “auto_bridge”:1或者2，模式1：放音暂停时就自动接管，模式2：放音完成时才自动接管。(smartivr 5.1.2 开始支持),如果设置了skip_eavesdrop，这个参数会给忽略。

人工接通后对人工端也开启实时质检 (smartivr 5.13版本开始支持) 添加了一个参数 asrparam:{“notify_url”:”http://ip/asrnotify",其他参看start_asr动作文档}，可以把坐席端ASR识别结果通知到URL。用户端ASR继续通过samrtivr接口通知，返回noop就可以。

接管

在监听模式，按DTMF *，就进入接管模式。

{“calleeid”:”8888”,”callerid”:”1000”,”callid”:”f01c16f1-0096-490e-80fa-7d32812580b6”,”duration”:56,”errorcode”:0,”flowdata”:{“flowtype”:”default”},”flowid”:””,”hangup”:false,”lag”:false,”notify”:”bridge_notify”,”origcallerid”:”1000”}

进入接管模式，会发送”notify”:”bridge_notify”通知，直接返回 action:noop就可以了。这时停止了ASR识别和机器人放音，直到电话挂断，发送 action:levea，注意进入接管模式不能返回机器人对话的。

使用指南

faq

asrprogress_notify 的 asrmessage_notify 区别

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

playback_result 什么时候有这个通知

自动打断（就是检测到声音，就自动停止放音）

业务打断(就是流程停止放音，或者播放一个新的声音实现打断。)

怎么禁用打断功能

噪音打断怎么解决(升级到5.0使用噪音人声识别可以解决噪音问题)

怎么实现关键词打断

多种打断方案集合使用流程

怎么实现放音的时候暂停ASR（就是机器人说话的时候，不识别用户说话，也不打断机器人说，类似单工模式一个人说一个人听。）

机器人刚放音，用户也开始说话,或者用户刚开始说话机器人也开始放音，怎么解决。

超时的时候，用户刚好开始说话了怎么办

性别识别（男性女性声音识别）

噪音人声识别(mod_vad 5.0开始支持)

怎么获取录音文件名

一句话怎么有时候有多个录音文件

怎么知道主叫挂断还是被叫挂断

怎么把通话转接给分机或者手机

机器人一直不说话

after_action 注意问题

执行palyabck之后，收到了上一个palyback放音的识别结果，怎么区分。

接口说明

请求通用参数

响应通用参数

notify 描述

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

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

asrprogress_notify

asrmessage_notify

getdtmf_result

playback_result

bridge_result

transfer_result

stop_asr_result

wait_result

action 描述

start_asr

start_asr使用的配置文件

playback

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

sotp_asr

console_playback

bridge 转接电话

hangup 挂机

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

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

getdtmf 接收用户按键

transfer 执行后，要等电话挂断才会收到 leave 通知

wait 等待

redirect 重定向接口地址

流接口支持(3.0版本开始支持)

启用流接口

asrprogress_notify （流接口 每说1-2个字 就会发出 asrprogress_notify 通知。）

asrmessage_notify

人工监听和接管(3.02版本开始支持)

监听

接管

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

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

asrprogress_notify （流接口每说1-2个字就会发出 asrprogress_notify 通知。）