電話連結服務

MQTT

伺服器連線位址:iot.cht.com.tw,連接埠2883 (SSL 加密連線)
協定名稱
取得電話通告的結果
Topic
phone-conn/calloutResult/${SNKey}
協定描述
訂閱電話通告API執行結果的回報訊息
模式

Subscribe

帳號與密碼
username: API金鑰,登入IOT大平台後,在[帳號資訊]底下[API金鑰管理]獲得,需先勾選使用的服務
password: 同 username 欄位
參數說明
SNKey:在租用服務電話號碼API時回報的服務電話SNKey數值
Messgae 範例
{ "groupId": "39ju39rdnkkw3f", "phone": "034240099", "status": "reject", "time": "2016-03-30T08:28:47.532Z" }
Messgae 說明
groupId:使用電話通告 API時回傳的通告電話群組識別號
phone:此電話回應訊息是回報電話群組中的哪支電話號碼
status:此電話號碼的回應狀態。會回報下列的狀態值其中的一種:
answered:對方接聽電話,或是對方有設定語音信箱時,在振鈴時間過長或是拒接電話時會進入語音信箱,此時系統就會回應answered狀態
reject:行動電話拒接電話或是行動電話忙線中
busy:市內電話使用中
timeout:市內電話或是行動電話對方沒有接聽電話
notfound:所撥打的電話號碼不存在
failed:此通電話呼叫發生錯誤,請稍候再試
time:取得此電話回應狀態的時間,使用ISO 8601日期時間表示格式,以Z結尾代表表示的時間是世界協調時間(UTC+0),轉換為台北時間(UTC+8)則是要自行加上8個小時。
協定名稱
取得DTMF按鍵及電話事件
Topic
phone-conn/callEvent/${SNKey}
協定描述
取得DTMF按鍵及電話事件。在電話連結服務運作過程中,若需要向創客的AP詢問如何執行下一個動作以回應用戶,則在用戶撥打電話服務號碼時,會透過 MQTT topic發送service request向創客的應用程式請求回應。 此topic也會在用戶電話撥入及電話掛斷時,傳送對應的電話事件通知
模式

Subscribe

帳號與密碼
username: API金鑰,登入IOT大平台後,在[帳號資訊]底下[API金鑰管理]獲得,需先勾選使用的服務
password: 同 username 欄位
參數說明
SNKey:在租用服務電話號碼API時回報的服務電話SNKey數值
Messgae 範例
{ "id": "CaYUd3gVpx", "type": "request", "phone": "034240099", "node": "MAIN,1", "time": "2018-03-30T08:28:47.532Z" }
node 屬性回應MAIN,1 代表用戶目前執行到phoneConfig API輸入的JSON資料的MAIN節點,並且用戶按下數字鍵1。
{ "id": "CaYUd3gVpx", "type": "request", "phone": "034240099", "node": "MAIN,timeout", "time": "2018-03-30T08:28:47.532Z" }
若是有開啟 collectText功能,回應的訊息則是語音轉文字(STT)的結果,結果中node屬性包含中文字以及 / 辨識信心值,信心值越高代表用戶的語音較清晰,可能辨識結果的準確率較高:
{ "id": "CaYUd3gVpx", "type": "request", "phone": "034240099", "node": "queryNode,台北/0.9", "time": "2018-03-30T08:28:47.532Z" }
node 屬性回應MAIN,timeout 代表用戶目前執行到phoneConfig API輸入的JSON資料的MAIN節點,但是太久沒有輸入任何數字
電話狀態事件通知:
當系統接聽電話,開始播放語音時,會收到CallEstablished事件。
{ "id": "CaYUd3gVpx", "type": "event", "phone": "034240099", "event": "CallEstablished", "time": "2018-03-30T08:28:47.532Z" }
當用戶掛斷電話時,會收到CallHangUp事件。
{ "id": "CaYUd3gVpx", "type": "event", "phone": "034240099", "event": "CallHangUp", "time": "2018-03-30T08:33:56.472Z" }
當有開啟錄音功能時,在錄音完成後,會回報下列錄音事件:
{ "id": "CaYUd3gVpx", "type": "recordEvent", "phone": "034240099", "data": "6KiI566X5qmf5q235Y+yCuioiOeul+apn+", "time": "2018-03-30T08:28:47.532Z" }
Messgae 說明
id:request識別碼,請在 response中的 id欄填入相同的識別碼
phone:撥入電話連結服務號碼的用戶電話號碼(Caller)
type:說明此訊息的型式。若是 request,則需要依「發佈電話連結服務的服務流程回應」的規範回覆訊息給伺服器。若 type為event則是搭配 event屬性通知創客目前用戶的通話狀態。若 type 為 recordEvent代表是回報錄音檔事件。若type為calloutRequest代表是互動式電話通告的事件,type為calloutEvent則是互動式電話通告接通及掛斷的事件通知。
node:對應之前在 phoneConfig API中ivrData中所設定的節點的 node屬性值,代表目前撥打電話的用戶正在執行phoneConfig API中的某個節點所設定的動作。例如收到的是 "node": "vt,1",代表目前的電話選單,用戶正操作到節點vt按下dtmf 1,等候創客的應用程式回覆service request給電話連結系統,電話連結系統會再將創客的回應轉換為語音播放給用戶聽。若有開啟collectText語音辨識功能,回應的訊息則是語音轉文字(STT)的結果及辨識結果的信心值。
event:當系統接通電話開始播放語音時,會收到CallEstablished 事件通知,當用戶掛斷電話後,會收到CallHangUp 事件通知。
recordType:數值為1,代表回傳錄製一般留言的事件。
time:取得此電話回應狀態的時間,使用ISO 8601日期時間表示格式,以Z結尾代表表示的時間是世界協調時間(UTC+0),轉換為台北時間(UTC+8)則是要自行加上8個小時。
data:若接收到是 type: recordEvent,此屬性標示的是錄音檔案以base64演算法編碼後的檔案內容。
text:若接收到是 type: recordEvent,此屬性的內容是該錄音檔案經由TTS辨識後轉換為文字的內容。
協定名稱
發佈電話執行動作
Topic
phone-conn/callAction/${SNKey}
協定描述
發佈電話執行動作。此功能需配合前項「取得DTMF按鍵及電話事件」使用,用來回覆電話連結服務所發出的service requset訊息。
模式

Publish

帳號與密碼
username: API金鑰,登入IOT大平台後,在[帳號資訊]底下[API金鑰管理]獲得,需先勾選使用的服務
password: 同 username 欄位
參數說明
SNKey:在租用服務電話號碼API時回報的服務電話SNKey數值
Messgae 範例
執行的動作不需播放等候音:
{ "id": "CaYUd3gVpx", "node":"play01", "text": "目前的氣溫是 25 度,PM2.5 是 20", "repeat": 1, "betweenTextRepeatDelay": 2, "promptMode": "M", "collectDTMF": true }
執行的動作需播放等候訊息時,回覆訊息,請先回應「等待訊息」,待執行的動作完成後,再回應「完成操作」的訊息,「等待訊息」如下:
{ "id": "CaYUd3gVpx", "isWaitText": true, "repeat": 1, "betweenTextRepeatDelay": 2, "text": "取得資料中,請稍候" }
「完成操作」訊息:
{ "id": "CaYUd3gVpx", "node": "final", "text": "目前的氣溫是 25 度,PM2.5 是 20" }
Messgae 說明
id:請填入與所要回覆的service request相同的識別碼,才可以在電話服務連結中與伺服器端的service request配對,正確回覆給撥打服務電話的用戶
node(必要):節點名稱,node 屬性的命名只允許[A-Za-z0-9_],且首字必須為英文字母,長度不可超過16個字元。不可命名為MAIN、CUSTOM、END,若沒有設定node屬性或是node屬性值不合法,則此訊息會被系統忽略。
text:電話連結服務流程將要回應給用戶的文字,字數長度限制最長200個字元(一個中文字或英數字,都算做一個字元)。
nextNode:選單間跳轉功能,例如要回到主選單,請填入MAIN關鍵字。可以選用的功能有END (執行後掛斷電話)、或是直接填寫node的名稱。nextNode不可填寫數值CONFIG。
repeat:可設定text訊息重複的次數,預設值為 1次,最大值為99
betweenTextRepeatDelay:填寫true或false,設定2次text訊息重複間的時間間隔,單位為「秒」,最小值為0,最大值為99,預設值為0。
promptMode:指定撥出時的聲音為女性(F)或是男性(M)發音可以填入 F 代表使用女性聲音發音,或是 M 代表使用男性聲音發音。預設值為M
collectDTMF:填寫true或false。填寫true代表需要等待用戶輸入DTMF按鍵,填寫false代表不需要收碼。預設值為 false。collectDTMF、collectDigits、collectText三項功能不可同時開啟。若collectDTMF設為true,maxRecordDuration屬性沒有任何作用,無法開啟錄音功能。
collectDigits:填寫true或false。填寫true代表開啟語音辨識「數字」的功能,填寫false代表不開啟此項功能。預設值為 false。collectDTMF、collectDigits、collectText三項功能不可同時開啟。若collectDigits設為true,maxRecordDuration屬性沒有任何作用,無法開啟錄音功能。
collectText:填寫true代表系統開啟語音辨識文字功能,系統會在播放完text屬性的文字後,開始錄音以進行語音辨識,並會透過MQTT callEvent topic將語音辨識的結果傳回給創客,填寫false代表系統不開啟此項功能。預設值為 false。collectDTMF、collectDigits、collectText三項功能不可同時開啟。若collectText設為true,maxRecordDuration屬性沒有任何作用,無法開啟錄音功能。
maxDTMF: 設定最多接收幾個 DTMF字元輸入,系統接收到指定數目的DTMF輸入後,會自動結束收碼的動作。多個 DTMF 輸入的結束鍵為 # 字號。例如設定 maxDTMF: 5 代表最多接收 5 個DTMF輸入,若用戶輸入 35# 時,系統只會接收到 35,若用戶輸入 23456 時,到達 5 個字元,系統會自動結束 DTMF 接收動作,最小值為1,最大值為20,預設值為 1。
collectDTMFTimeout:設定等待接收用戶DTMF輸入的時間長短,單位為秒,若接收到用戶輸入 # 字號時,會提早結束收碼的動作,不會等到Timeout。最小值為10,最大值為60,預設值為 maxDTMF 長度*2 秒。例如 maxDTMF 為 5,則 collectDTMFTimeout為 5*2 = 10 秒。
maxRecordDuration:在播放完 text 指定的文字後,指定錄音的秒數,若指定的數字大於 0,代表要開啟錄音功能。錄音期間接收到 # 字鍵,則結束錄音功能,錄音完成後,會生成一個錄音檔,下載的路徑會在錄音完成後,透過 MQTT callEvent topic 進行回報。錄音檔案的格式為 8k PCM wav 檔。最小值為0,最大值為999秒,預設值為 0,不開啟錄音功能。
recordToText:填寫true或false。在 maxRecordDuration 大於0時,若此項目設定為true,會在透過MQTT callEvent topic回傳錄音檔時,包含該錄音檔經TTS辨識轉換後的文字內容。

「等待訊息」格式說明:
id:請填入與所要回覆的service request相同的識別碼
text:用戶等待時要播放的等待訊息內容
isWaitText:值為true,若存在此訊息,代表此訊息為等待訊息
repeat:可設定text訊息重複的次數,預設值為 1次,最大值為99。等待訊息的文字語音播放完畢後,若系統還沒有接收到「完成操作」的訊息前,會自動播放等待音樂,最多播放4分鐘,若4分鐘後還沒有接到「完成操作」的訊息,則會自動掛斷此通電話呼叫。
betweenTextRepeatDelay:設定2次text訊息重複間的時間間隔,單位為「秒」,預設值為0,最大值為99
promptMode:指定撥出時的聲音為女性(F)或是男性(M)發音可以填入 F 代表使用女性聲音發音,或是 M 代表使用男性聲音發音。預設值為M
協定名稱
取得電話執行動作除錯訊息
Topic
phone-conn/callActionDebug/${SNKey}
協定描述
取得電話執行動作除錯訊息。在發佈電話執行動作訊息後,若是訊息格式有錯誤,系統會透過這個topic發送訊息告知創客
模式

Subscribe

帳號與密碼
username: API金鑰,登入IOT大平台後,在[帳號資訊]底下[API金鑰管理]獲得,需先勾選使用的服務
password: 同 username 欄位
參數說明
SNKey:在租用服務電話號碼API時回報的服務電話SNKey數值
Messgae 範例
Messgae 說明
系統錯誤回應訊息,使用 JSON 格式訊息告知callAction topic訊息的錯誤。