電話連結服務 (TAS) API

{ "groupId": "39ju39rdnkkw3f", "phone": "034240099", "status": "reject", "time": "2016-03-30T08:28:47.532Z" }

groupId：使用電話通告 API時回傳的通告電話群組識別號
phone：此電話回應訊息是回報電話群組中的哪支電話號碼
status：此電話號碼的回應狀態。會回報下列的狀態值其中的一種：
answered：對方接聽電話，或是對方有設定語音信箱時，在振鈴時間過長或是拒接電話時會進入語音信箱，此時系統就會回應answered狀態
reject：行動電話拒接電話或是行動電話忙線中
busy：市內電話使用中
timeout：市內電話或是行動電話對方沒有接聽電話
notfound：所撥打的電話號碼不存在
failed：此通電話呼叫發生錯誤，請稍候再試
time：取得此電話回應狀態的時間，使用ISO 8601日期時間表示格式，以Z結尾代表表示的時間是世界協調時間(UTC+0)，轉換為台北時間(UTC+8)則是要自行加上8個小時。

{ "id": "CaYUd3gVpx", "type": "request", "phone": "034240099", "node": "MAIN,1", "time": "2018-03-30T08:28:47.532Z" }

{ "id": "CaYUd3gVpx", "type": "request", "phone": "034240099", "node": "MAIN,timeout", "time": "2018-03-30T08:28:47.532Z" }

{ "id": "CaYUd3gVpx", "type": "request", "phone": "034240099", "node": "queryNode,台北/0.9", "time": "2018-03-30T08:28:47.532Z" }

{ "id": "CaYUd3gVpx", "type": "event", "phone": "034240099", "event": "CallEstablished", "time": "2018-03-30T08:28:47.532Z" }

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

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辨識後轉換為文字的內容。

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

id：請填入與所要回覆的service request相同的識別碼，才可以在電話服務連結中與伺服器端的service request配對，正確回覆給撥打服務電話的用戶
node(必要)：節點名稱，node 屬性的命名只允許[A-Za-z0-9_]，且首字必須為英文字母，長度不可超過16個字元。不可命名為MAIN、CUSTOM、END，若沒有設定node屬性或是node屬性值不合法，則此訊息會被系統忽略。
text：電話連結服務流程將要回應給用戶的文字，字數長度限制最長200 (中文一個字計算為1，英文單字(word)每個計算為1，數字每個字元計算1，標點與空白不列入計算)。
textSpeed：設定產生語音檔的說話速度，可設定的數值範圍是0.0~10.0之間。若是promptMode是F或F1時，預設值是0.9，若promptMode是F2或M時，預設值是1.0。
nextNode：選單間跳轉功能，例如要回到主選單，請填入MAIN關鍵字。可以選用的功能有END (執行後掛斷電話)、或是直接填寫node的名稱。nextNode不可填寫數值CONFIG。
repeat：可設定text訊息重複的次數，預設值為 1次，最大值為99
betweenTextRepeatDelay：填寫true或false，設定2次text訊息重複間的時間間隔，單位為「秒」，最小值為0，最大值為99，預設值為0，設為 0 代表使用系統預設值。
promptMode：填入F、F1(與F相同)、F2則是使用女性聲音播放，填入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 且 sttMode設為stream時，maxRecordDuration屬性沒有任何作用。 若collectText設為true，sttMode設為record時，maxRecordDuration屬性可以指定用來語音辨識錄音長度的最大秒數。
sttMode：可填入的數值為stream或是record，用來配合collectText屬性值使用，指定語音辨識的方式是使用串流方式(辨識速度較快，但可能正確率較低)，或是使用「先錄音再辨識」的方式(辨識速度較慢，但可能有較高辨識率)。sttMode設定為record時，可配合指定maxRecordDuration的數值設定錄音長度，單位為「秒」，若沒有指定或是指定數值為0，會使用預設值10秒。配合collectText及sttMode: record時，設定maxRecordDuration不會透過MQTT回傳錄音檔。預設值為stream。
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辨識轉換後的文字內容。
playDTMF：指定由系統播放對應的DTMF按鍵音給用戶端。此訊息可以接受「數字0-9」、英文小寫w，一個w代表播放DTMF按鍵音間隔0.5秒。例如：playDTMF屬性值設為345ww1w23，代表系統會先連續播放DTMF按鍵音345後，暫停1秒，再播放數字1按鍵音，再暫停0.5秒後，連續播放2、3的按鍵音。此屬性最長可填入60個字元。
transferTo：填寫要轉接的電話號碼，例如：0233991111，若是轉接電話沒有被接聽，會再透過MQTT回傳電話狀態，應用程式可以選擇後續處理動作。轉接電話費用視為從TAS平台撥出一通電話方式計價。這個功能可使用於情境1：call-out(從TAS平台撥出電話)與情境2：call-in(從外部撥打進TAS平台分配的租用服務號碼)。
情境1，例如在TAS平台以租用服務號碼T call-out給用戶A時，TAS平台號碼T為主叫端，用戶A為被叫端，在執行transferTo功能轉接給電話B之後，主叫端變更為指定的電話號碼B，變成B(主叫端)與A(被叫端)進行通話，TAS平台會視為2通call-out電話依費率計費(1通從TAS平台call-out給A，另1通從TAS平台call-out給B)。
情境2，外部電話號碼A撥打給TAS平台分配的服務號碼T，A為主叫端，T為被叫端，之後使用transferTo轉接給指定的電話號碼B之後，變為A與B進行通話，TAS平台會視為1通從平台撥出call-out電話給B依費率計費。
ringingTimeout：選擇性參數，在配合transferTo功能使用時可設定轉接電話振鈴多少秒沒有被接聽時，視為timeout狀態，透過MQTT回傳電話狀態。此參數為整數型別，最小值為15秒，最大值為120秒，不指定時預設值為30秒。
sttEngineOptions: 選擇性參數，用於配合語音辨識(STT)功能使用，參數格式為一個 JSON 物件，目前可以設定為以下model：加強姓名辨識，請設定model 屬性為 wenet_eddie。加強辨識「是」或「否」等簡短回覆語句，請設定model 屬性為 wenet_yesno。用於一般對話情境辨識，請設定model 屬性為wenet_cs_general。

「等待訊息」格式說明：
id：請填入與所要回覆的service request相同的識別碼
text：用戶等待時要播放的等待訊息內容
isWaitText：值為true，若存在此訊息，代表此訊息為等待訊息
repeat：可設定text訊息重複的次數，預設值為 1次，最大值為99。等待訊息的文字語音播放完畢後，若系統還沒有接收到「完成操作」的訊息前，會自動播放等待音樂，最多播放4分鐘，若4分鐘後還沒有接到「完成操作」的訊息，則會自動掛斷此通電話呼叫。
betweenTextRepeatDelay：設定2次text訊息重複間的時間間隔，單位為「秒」，預設值為0，最大值為99，設為 0 代表使用系統預設值。
promptMode：填入F、F1(與F相同)、F2則是使用女性聲音播放，填入M則是使用男性聲音播放，預設值是M。

系統錯誤回應訊息，使用 JSON 格式訊息告知callAction topic訊息的錯誤。