智能电话机器人话术开发接口

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

  1. 外呼程序呼叫电话接通后,或者客户主动呼入接通后 机器人程序 向 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"			//通知类型
    }
    
  2. 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时间内用户不说话,就重新播放声音。
    	}
    }
    
  3. 机器人程序执行 “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
      	}
      }
      
  4. 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返回播放新的声音,就会停止播放当前的声音。

怎么禁用打断功能

  1. 机器人放音的时候可以识别用户说话,但是不打断机器人放音:playback的allow_interrupt设置-1,关闭自动打断。asrprogress_notify返回 noop。 asrmessage_notif
    如果playstate等于false(当前没放音),执行业务逻辑播放新的声音。asrmessage_notif如果playstate等于true(当前在放音,不处理),返回noop,并且把识别结果记录到flowdata,等paly_result的时候再处理识别结果。如果paly_result的时候检测放音过程是否有识别结果,如果有执行业务逻辑处理流程,如果没有返回wait.

  2. 放音的时候直接暂停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,否则必须播放一个声音,提示用户说话。

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

  1. start_asr 开始asr,设置 pause_play_ms 为 200-1000之间 (设置自动打断时间)
  2. playback wait设置 3000-5000,并且设置allow_interrupt动态修改自动打断时间,
  3. asrprogress_notify 检查是否有关键词有关键词返回console_playback(pause),没关键词返回 noop
  4. asrmessage_notify 根据识别结果,playms(用来判断 是否 机器人刚说话,用户也开始说话) ,playstate(用来判断 用户说话结束的时候,机器人是否也放音完成),等条件返回console_playback(resume)继续放音,或者返回playback播放一个新的声音。
  5. 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可能男 其他系统错误

噪音人声识别(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 注意问题

  1. 例如 after:sotp_asr after_action:bridge, 如果没有先执行start_asr,那么sotp_asr就会失败,如果没设置after_ignore_error:true,就不会执行bridge。 注意点 after_ignore_error:true,才会不管第一个指令是否成功都执行第二个指令。
  2. 例如 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。

你可能感兴趣的:(机器人,ai智能,智能语音,机器人)