smart ivr 接口说明

使用指南

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

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

    smartivr –> web

    {
    "calleeid": "8888abc", //被叫号码
    "callerid": "abc", //主叫号码
    "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 通知的。

自动放音暂停(打断)

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

怎么实现关键词打断

  • start_asr的pause_play_ms 设置 0 ,关闭自动打断
  • asrprogress_notify 的识别结果如果是关键词 返回 console_playback(pause),如果不是关键词 返回 console_playback(resume)
  • asrmessage_notify 的整句话识别结果如果匹配,直接播放新的声音文件,执行新的业务流程,如果不匹配,返回console_playback(resume)。
  • playback_result 收到这个通知,说明声音播放完成,等待用户说话超时,必须播放一个声音,提示用户说话。

噪音打断,怎么解决

start_asr 有一个参数 filter_level 防止干扰等级。0-1.0之间,建议 0.3。你可以设置这个参数来防止噪音和身边的周围的人说话声音导致的打断。

性别识别(男性女性声音识别)

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

怎么实现部分放音的时候不打断(就是声音播放完了,才识别)

playback的时候设置suspend_asr为true(wait,和retry设置为0),就可以临时关闭ASR, playback_result的时候返回 wait,设置一个等待说话时间,就可以实现这个功能了。

怎么获取录音文件名

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

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

因为用户说话停顿时间超过 min_pause_ms ,就提交ASR识别,生产一个录音文件,停顿时间超过 max_pause_ms 就发送asrmessage_notify通知认为说话完成。 如果用户停顿时间在 min_pause_ms和max_pause_ms,就会产生多个录音文件。 好比我们微信聊天,对方说2句你回复1句是完全正常的情况,你网页上展示2个或者多个录音文件就可以。

接口说明

注意:请求和返回都采用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识别结果
    • wait_result 等待超时
    • transfer_result 转接完成
  • flowdata 流程数据
  • flowid 流程ID
  • errorcode 错误代码 无错误时不存在这个值或者等于0
  • message 自定义消息
  • duration 持续时间,enter开始计时,可以用于控制对话总时间,比如持续时间超过3分钟就挂断通话。

响应通用参数

  • 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使用
    
  • 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 录音文件
  • gender 性别识别 0未识别 1女 2男 3可能女 4可能男 其他系统错误 每个电话只识别前3句话。

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挂断原因

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

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

停止后台asr完成

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/被叫号码UniqueID序号.wav
  • volume 音量标准化的值。0-100,0不使用音量标准化,其他值 音量把录音音量调整到这个值后,再提交ASR识别。
  • filter_level 防止干扰等级。0-1.0之间,建议 0.3。
  • 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时间内用户不说话,就重新播放声音。
  • tts_configure_filename tts配置文件名(绝对路径),不设置会使用默认smartivr.json.
多文件或者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 可选参数 网关名字
  • background 可选参数 背景音乐
  • prompt 可选参数 提示文本 prompt 提示文本(如果最后4个字是.wav,就是录音文件放音,否则会调用TTS生成声音文件)。

hangup 挂机

{"action":"hangup","params":{"usermsg":"not found notify"}}

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 [数字] 按键超时时间,如果超时没有新按键,就认为输入完成。

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 数字型 单位毫秒