smart ivr 接口說明

smartivr 是一個基於Freeswitch的電話機器人二次開發接口（restful），支持和Asterisk對接

使用指南

用戶自己實現 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"           //通知類型
}
```

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)暫停放音。不能執行其他動作。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"
        }
    }
}
```

* 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"
]
```

sotp_asr

停止後臺ASR。

console_playback

用於播放控制，用戶說話開始，先暫停播放，如果說的是無效聲音，可以恢復播放。

command
- pause 暫停播放
- resume 恢復播放
- stop 停止播放

bridge 轉接電話

{"action":"bridge","flowdata":"","params":{"number":"sofia\/external\/[email protected]: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 [數字] 按鍵超時時間，如果超時沒有新按鍵，就認爲輸入完成。

smart ivr 接口說明（電話機器人二次開發接口）

smart ivr 接口說明

使用指南

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 接收用戶按鍵

新一代FreeSWITCH電話機器人模塊

FreeSWITCH 背景音模塊

FreeSWITCH 語音識別 ASR 接口介紹科大訊飛百度阿里雲等接口實現

mod_vad 用於通話實時質檢

使用FreeSWITCH把回撥線路當成中繼(落地)使用可對接VOS

Mac下配置sublime實現LaTeX

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結

smart ivr 接口說明（電話機器人二次開發接口）

smart ivr 接口說明

使用指南

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。