感測資料

伺服器連線位址:iot.cht.com.tw,連接埠1883 與 8883 (TLS 加密連線)
支援 MQTT Protocol V3.1 與 V3.1.1

協定名稱
訂閱感測資料變動通知
Topic
/v1/device/${device_id}/sensor/${sensor_id}/rawdata
協定描述
訂閱感測資料變動通知。當感測資料有變動時,系統將會發送變動資訊給訂閱感測資料變動的終端裝置
模式

Subscribe

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Response 說明
{ "id": "light0001", "deviceId": "7432", "time": "2016-03-30T08:28:47.532Z", "value":["1"] }
備註
1.device_id 為裝置 ID,而 sensor_id 為指定裝置 ID 下的sensor ID
2.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
3.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
4.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
5.MQTT 訂閱通知訊息的反應時間會依據平台目前訊息量多寡而影響快慢,平均 3秒內可接收到通知訊息。
6.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

協定名稱
訂閱感測資料變動通知(CSV)
Topic
/v1/device/${device_id}/sensor/${sensor_id}/csv
協定描述
訂閱感測資料變動通知。當感測資料有變動時,系統將會以CSV格式發送變動資訊給訂閱感測資料變動的終端裝置
模式

Subscribe

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Response 說明
2016-03-30T08:28:47.532Z,7432,light0001,1
備註
1.回傳CSV格式為:日期,裝置編號,感測器識別代碼,感測器數值
2.device_id 為裝置 ID,而 sensor_id 為指定裝置 ID 下的sensor ID
3.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
4.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
5.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
6.MQTT 訂閱通知訊息的反應時間會依據平台目前訊息量多寡而影響快慢,平均 3秒內可接收到通知訊息。
7.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

協定名稱
發佈感測資料
Topic
/v1/device/${device_id}/rawdata
協定描述
發佈感測資料
模式

Publish

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Message 說明
[ { "id": "loading", "time": "2014-12-11T10:43:58", "value": [ "96.3", "77.4" ] },{ "id": "loading", "time": "2014-12-11T10:45:58", "value": [ "97.7", "71.5" ] } ]
備註
1.device_id 為裝置 ID,而 id 為指定裝置 ID 下的sensor ID
2.time 為時間,格式為 ISO 8601 [optional]
3.lat 為緯度 (latitude) [optional]
4.lon 為經度 (longitude) [optional]
5.value 為原始資料數值,格式為字串,可以多筆數據。
6.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
7.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
8.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
9.MQTT 發布訊息的內容 Payload 大小為 5KB,若超過大小,平台將會捨棄訊息。
10.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

感測控制

伺服器連線位址:iot.cht.com.tw,連接埠1883 與 8883 (TLS 加密連線)

協定名稱
訂閱感測控制通知
Topic
/v1/device/${device_id}/sensor/${sensor_id}/command
協定描述
訂閱感測控制通知。當感測控制變動時,系統將會發送控制資訊給訂閱感測控制通知的終端設備
模式

Subscribe

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Response 說明
{ "id": "cin", "deviceId": "266148835", "time": "2017-03-28T07:09:05.699Z", "cmd": "close" }
備註
1.device_id 為設備 ID,而 sensor_id 為指定設備 ID 下的sensor ID
2.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
3.device key 為設備專屬的金鑰,可以從設備管理查詢得知
4.time 為感測控制資料系統接收時間,格式為 ISO 8601
5.cmd 為控制指令(使用者自行定義指令),格式為字串。
6.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
7.MQTT 訂閱通知訊息的反應時間會依據平台目前訊息量多寡而影響快慢,平均 3秒內可接收到通知訊息。
8.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

協定名稱
發佈感測控制
Topic
/v1/device/${device_id}/command
協定描述
發佈感測控制
模式

Publish

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Message 說明
[ { "id":"cin", "lat":24.1, "lon":121.23, "save":true, "cmd":"open" } ]
備註
1.device_id 為設備 ID,而 id 為指定設備 ID 下的sensor ID
2.lat 為緯度 (latitude) [optional]
3.lon 為經度 (longitude) [optional]
4.cmd 為控制指令(使用者自行定義指令),格式為字串。
5.save true:永久儲存,可於歷史紀錄中查詢該筆控制指令;false:暫時儲存,會被之後的資料所取代,無法於歷史紀錄中查詢。預設為true[optional]
6.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
7.device key 為設備專屬的金鑰,可以從設備管理查詢得知
8.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
9.MQTT 發布訊息的內容 Payload 大小為 5KB,若超過大小,平台將會捨棄訊息。
10.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

協定名稱
訂閱感測控制確認通知
Topic
/v1/device/${device_id}/sensor/${sensor_id}/ack
協定描述
訂閱感測控制確認通知,用於確認資料有無正確的傳輸到接收端。當平台接收到確認感測控制訊息時,系統將會發送控制資訊給訂閱感測控制確認通知的終端設備
模式

Subscribe

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Response 說明
{ "id": "cin", "deviceId": "266148835", "time": "2017-03-28T07:09:05.699Z", "ack": "close" }
備註
1.device_id 為設備 ID,而 sensor_id 為指定設備 ID 下的sensor ID
2.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
3.device key 為設備專屬的金鑰,可以從設備管理查詢得知
4.time 為感測控制資料系統接收時間,格式為 ISO 8601
5.ack 為控制確認訊息(使用者自行定義確認訊息),格式為字串。
6.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
7.MQTT 訂閱通知訊息的反應時間會依據平台目前訊息量多寡而影響快慢,平均 3秒內可接收到通知訊息。
8.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

協定名稱
發佈感測控制確認資訊
Topic
/v1/device/${device_id}/ack
協定描述
發佈感測控制確認資訊,用於確認資料有無正確的傳輸到接收端
模式

Publish

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Message 說明
[ { "id":"cin", "time": "2017-08-03T09:28:47.532Z", "save":true, "ack":"open" } ]
備註
1.device_id 為設備 ID,而 id 為指定設備 ID 下的sensor ID
2.lat 為緯度 (latitude) [optional]
3.lon 為經度 (longitude) [optional]
4.ack 為控制確認訊息(使用者自行定義確認訊息),格式為字串。
5.save true:永久儲存,可於歷史紀錄中查詢該筆控制指令;false:暫時儲存,會被之後的資料所取代,無法於歷史紀錄中查詢。預設為true[optional]
6.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
7.device key 為設備專屬的金鑰,可以從設備管理查詢得知
8.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
9.MQTT 發布訊息的內容 Payload 大小為 5KB,若超過大小,平台將會捨棄訊息。
10.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

裝置狀態監控

伺服器連線位址:iot.cht.com.tw,連接埠1883 與 8883 (TLS 加密連線)
由裝置主動上傳HeartBeat訊息讓系統依據頻率資訊判斷設備狀態

協定名稱
發送 HeartBeat
Topic
/v1/device/${device_id}/heartbeat
協定描述
發送 HeartBeat
模式

Publish

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Message 說明
{ "pulse": "1000" }
備註
1.pulse 裝置發送訊息間隔時間
2.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
3.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
4.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
5.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

協定名稱
訂閱 HeartBeat 通知
Topic
/v1/device/${device_id}/heartbeat
協定描述
訂閱 HeartBeat 通知
模式

Subscribe

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Response 說明
{ "pulse": "1000", "from": "223.140.31.51", "last": "2016-03-30T08:28:47.532Z", "time": "2016-03-30T09:28:47.532Z", "type": "Lost", "deviceId": "853435970" }
備註
1.pulse 裝置發送訊息間隔時間
2.from 裝置最後一次發送訊息IP
3.last 裝置最後一次發送訊息時間
4.time 目前時間
5.type 裝置狀態 [Live: 裝置第一次連上IoT智慧聯網大平台並開始傳送HeartBeat時。Lost: 沒有在時間內收到通知。ReLive: 裝置中斷HeartBeat後,重新連回IoT智慧聯網大平台時。LastInfo: 裝置最後一次HeartBeat的資訊]
6.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
7.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
8.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
9.MQTT 訂閱通知訊息的反應時間會依據平台目前訊息量多寡而影響快慢,平均 3秒內可接收到通知訊息。
10.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

設備主動狀態監控

伺服器連線位址:iot.cht.com.tw,連接埠1883 與 8883 (TLS 加密連線)
由系統主動透過設備上傳感測數據頻率判斷設備狀態

協定名稱
訂閱設備主動監控狀態
Topic
/v1/device/${device_id}/active
協定描述
訂閱設備主動監控狀態
模式

Subscribe

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Response 說明
start 狀態
{ "deviceId": "786727741", "status": "start", "createTime": "2019-07-10T02:55:12.512Z" }
online 狀態
{ "deviceId": "786727741", "status": "online", "lastDataTime": "2019-07-10T02:55:17.000Z", "createTime": "2019-07-10T02:55:18.031Z" }
abnormal 狀態
{ "deviceId": "786727741", "status": "abnormal", "record": 2, "lastDataTime": "2019-07-10T02:56:45.000Z", "createTime": "2019-07-10T02:58:09.106Z" }
offline 狀態
{ "deviceId": "786727741", "status": "offline", "lastDataTime": "2019-07-10T03:35:37.000Z", "createTime": "2019-07-10T03:38:10.069Z" }
stop 狀態
{ "deviceId": "786727741", "status": "stop", "createTime": "2019-07-10T03:40:43.585Z" }
備註
1.deviceId 為設備編號
2. status 為設備主動監控狀態,狀態分為: start 啟動設備主動監控狀態; online: 設備上線狀態; offline: 設備離線狀態; abnormal: 設備接收數據頻率異常狀態; stop: 設備停止主動監控狀態
3. record 異常頻率資訊(指定週期內接收到的感測數據筆數)
4. lastDataTime 最後一筆收到設備資料時間
5. createTime 設備主動監控狀態判斷時間
6.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
7.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
8.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
9.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

自動化裝置納管

伺服器連線位址:iot.cht.com.tw,連接埠1883 與 8883 (TLS 加密連線)

協定名稱
訂閱裝置組態設定異動通知
Topic
/v1/registry/${product_code+serial_id}
協定描述
允許實體裝置(例如 Gateway )訂閱裝置組態設定異動通知。當用戶透過自動化裝置納管流程 Registry RESTful API時,實體裝置將會收到裝置組態資訊(例如存取協定的金鑰或裝置編號)
模式

Subscribe

帳號與密碼
username: "chtregistry"
password: "chtregistry"
Response 格式說明
回傳內容依據 RESTful 註冊協定 參數不同而有所不同。若op為Reconfigure,則回傳內容如下
{ "op": "Reconfigure", "ck": "aabbccdd" }
或op為SetDeviceId,則回傳內容如下
{ "op": "SetDeviceId", "ck": "aabbccdd", "deviceId": "7432" }
備註
1.product_code 為供應商裝置於IoT智慧聯網大平台註冊的產品代碼, serial_number 為供應商裝置出貨的流水號,每個裝置必須不同; 例如:產品代碼 (product_code) 為 pi,流水號 (serial_number) 為 00001,則 ${product_code+serial_number} 應為 pi00001
2.op 為裝置組態設定操作,兩種回傳資訊:Reconfigure/SetDeviceId; Reconfigure為要求裝置主動於平台建立組態資料時回傳之內容;SetDeviceId為要求裝置變更所屬的裝置編號
${product_code+serial_number} 3.ck 為IoT專案的專屬金鑰 Project Key 或裝置的專屬金鑰 Device Key(回傳哪一種金鑰類型可於 RESTful Registry 指令中指定)
4.deviceId 為裝置於IoT智慧聯網大平台建立的裝置唯一識別碼
5.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
6.MQTT 訂閱通知訊息的反應時間會依據平台目前訊息量多寡而影響快慢,平均 3秒內可接收到通知訊息。
7.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

Last Will and Testament

伺服器連線位址:iot.cht.com.tw,連接埠1883 與 8883 (TLS 加密連線)
IoT MQTT 最後遺言機制(Last Will and Testament, LWT)

協定說明
終端Client連結遺願設定
Last-Will Topic
/v1/lwt/${custom}
custom 為自訂名稱,最少由4個英數字(a-zA-Z0-9)組成
協定描述
設定終端Client非正常斷開連接時,會向遺願主題(Last-Will Topic)發布一條客製化訊息(Last-Will Message)。遺願是在建立連線時,在CONNECT封包中設置的。
模式

Last-Will

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Last-Will Message
客製化遺願訊息,為字串格式。
例如: Oh no! Unexpected disconnection!
Last-Will QoS
只提供 QoS 0 服務
Last-Will Retain
支援 Last-Will Retain 機制,可保留遺願訊息(系統只保留遺願訊息7天)
備註
1.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
2.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
3.遺願只有當底下非正常中斷連線的狀態下,才會發送訊息,若正常透過發送Disconnect Package中斷連線則不會發送
  a. Broker 檢測到底層的I/O 異常;
  b. Client 未能在 Keep Alive 的間隔內和 Broker 之間有訊息交換;
  c. Client 在關閉底層TCP 連接前沒有發送DISCONNECT Package;
  d. Broker 因為協議錯誤關閉和Client 的連接,比如Client 發送了一個格式錯誤的MQTT 封包。
4.LWT遺願 Retain 的設置最多於系統保留7天。
5.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
6.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

協定說明
訂閱終端Client遺願
Topic
/v1/lwt/${custom}
協定描述
訂閱終端Client遺願
模式

subscribe

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Response 格式說明
回傳內容依據用戶遺願設定時設定的遺願訊息回覆。
備註
1.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
2.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
3.遺願只有當底下非正常中斷連線的狀態下,才會發送訊息,若正常透過發送Disconnect Package中斷連線則不會發送
  a. Broker 檢測到底層的I/O 異常;
  b. Client 未能在 Keep Alive 的間隔內和 Broker 之間有訊息交換;
  c. Client 在關閉底層TCP 連接前沒有發送DISCONNECT Package;
  d. Broker 因為協議錯誤關閉和Client 的連接,比如Client 發送了一個格式錯誤的MQTT 封包。
4.LWT遺願 Retain 的設置最多於系統保留7天。
5.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
6.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

協定說明
發佈遺願訊息(清除Retain遺願)
Topic
/v1/lwt/${custom}
協定描述
發佈遺願訊息(主要用來清除Retain遺願)
模式

publish

帳號與密碼
username: PROJECT_KEY or DEVICE_KEY
password: PROJECT_KEY or DEVICE_KEY
Message 說明
遺願訊息為用戶自訂的字串訊息。
此協定用來協助清除遺願的Retain訊息,避免每次重新訂閱時,會重複取得已得知異常的遺願資訊。
備註
1.project key 為專案的專屬金鑰,可以從專案管理 > 權限資料查詢得知
2.device key 為裝置專屬的金鑰,可以從裝置管理查詢得知
3.遺願只有當底下非正常中斷連線的狀態下,才會發送訊息,若正常透過發送Disconnect Package中斷連線則不會發送
  a. Broker 檢測到底層的I/O 異常;
  b. Client 未能在 Keep Alive 的間隔內和 Broker 之間有訊息交換;
  c. Client 在關閉底層TCP 連接前沒有發送DISCONNECT Package;
  d. Broker 因為協議錯誤關閉和Client 的連接,比如Client 發送了一個格式錯誤的MQTT 封包。
4.LWT遺願 Retain 的設置最多於系統保留7天。
5.MQTT QoS 傳輸品質目前支援 QoS 0 最多傳送一次(at most once)模式。
6.MQTT 在網路階層架構中屬於應用層,它產生訊息並交給下一層(TCP)處理, MQTT 本身並不清楚最底層的網路是否壅塞甚至斷線,因此 MQTT 不保證能百分之百交付訊息。

電話連結服務(TAS)

伺服器連線位址:iot.cht.com.tw,連接埠2883,需使用 SSL 加密連線

協定名稱
訂閱電話通告的結果回報
Topic
phone-conn/calloutResult/${SNKey}
協定描述
訂閱電話通告API執行結果的回報訊息
模式

Subscribe

帳號與密碼
username: API金鑰,登入IOT大平台後,在[帳號資訊]底下[API金鑰管理]獲得,需先勾選使用的服務
password: API金鑰,登入IOT大平台後,在[帳號資訊]底下[API金鑰管理]獲得,需先勾選使用的服務
參數說明
${SNKey}:在租用服務電話號碼API時回報的服務電話SNKey數值
Response 說明
{ "groupId": "39ju39rdnkkw3f", "phone": "0281920044", "status": "reject", "time": "2016-03-30T08:28:47.532Z" }
備註
1.groupId:使用電話通告 API時回傳的通告電話群組識別號
2.phone:此電話回應訊息是回報電話群組中的哪支電話號碼
3.status:此電話號碼的回應狀態。會回報下列的狀態值其中的一種:
answered:對方接聽電話,或是對方有設定語音信箱時,在振鈴時間過長或是拒接電話時會進入語音信箱,此時系統就會回應answered狀態
reject:行動電話拒接電話或是行動電話忙線中
busy:市內電話使用中
timeout:市內電話或是行動電話對方沒有接聽電話
notfound:所撥打的電話號碼不存在
4.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: API金鑰,登入IOT大平台後,在[帳號資訊]底下[API金鑰管理]獲得,需先勾選使用的服務
參數說明
${SNKey}:在租用服務電話號碼API時回報的服務電話SNKey數值
Response 說明
{ "id": "CaYUd3gVpx", "type": "request", "phone": "0281920044", "node": "MAIN,1", "time": "2018-03-30T08:28:47.532Z" }
node 屬性回應MAIN,1 代表用戶目前執行到phoneConfig API輸入的JSON資料的MAIN節點,並且用戶按下數字鍵1。
{ "id": "CaYUd3gVpx", "type": "request", "phone": "0281920044", "node": "MAIN,timeout", "time": "2018-03-30T08:28:47.532Z" }
node 屬性回應MAIN,timeout 代表用戶目前執行到phoneConfig API輸入的JSON資料的MAIN節點,但是太久沒有輸入任何數字
{ "id": "CaYUd3gVpx", "type": "request", "phone": "0281920044", "node": "queryNode,台北/0.9", "time": "2018-03-30T08:28:47.532Z" }
若是有開啟 collectText功能,回應的訊息則是語音轉文字(STT)的結果,結果中node屬性包含中文字以及 / 辨識信心值,信心值越高代表用戶的語音較清晰,可能辨識結果的準確率較高

電話狀態事件通知:

當系統接聽電話,開始撥放語音時,會收到CallEstablished事件。
{ "id": "CaYUd3gVpx", "type": "event", "phone": "0281920044", "event": "CallEstablished", "time": "2018-03-30T08:28:47.532Z" }
當用戶掛斷電話時,會收到CallHangUp事件。
{ "id": "CaYUd3gVpx", "type": "event", "phone": "0281920044", "event": "CallHangUp", "time": "2018-03-30T08:33:56.472Z" }
當有開啟錄音功能時,在錄音完成後,會回報下列錄音事件:
{ "id": "CaYUd3gVpx", "type": "recordEvent", "phone": "0281920044", "data": "6KiI566X5qmf5q235Y+yCuioiOeul+apn+", "time": "2018-03-30T08:28:47.532Z" }
備註
1.id:request識別碼,請在 response中的 id欄填入相同的識別碼
2.phone:撥入電話連結服務號碼的用戶電話號碼(Caller)
3.type:說明此訊息的型式。若是 request,則需要依「發佈電話連結服務的服務流程回應」的規範回覆訊息給伺服器。若 type 為event 則是搭配 event屬性通知創客目前用戶的通話狀態。若 type 為 recordEvent 代表是回報錄音檔事件。
4.node:對應之前在 phoneConfig API中ivrData中所設定的節點的 node屬性值,代表目前撥打電話的用戶正在執行phoneConfig API中的某個節點所設定的動作。例如收到的是 "node": "vt,1",代表目前的電話選單,用戶正操作到節點vt按下dtmf 1,等候創客的應用程式回覆service request給電話連結系統,電話連結系統會再將創客的回應轉換為語音撥放給用戶聽。若有開啟collectText語音辨識功能,回應的訊息則是語音轉文字(STT)的結果及辨識結果的信心值。
5.event:系統接通電話開始撥放語音時,會收到CallEstablished 事件通知,當用戶掛斷電話後,會收到CallHangUp 事件通知。
6.recordType:數值為1,代表回傳錄製一般留言的事件。
7.time:取得此電話回應狀態的時間,使用ISO 8601日期時間表示格式,以Z結尾代表表示的時間是世界協調時間(UTC+0),轉換為台北時間(UTC+8)則是要自行加上8個小時。
8.data:若接收到是 type: recordEvent,此屬性標示的是錄音檔案以base64演算法編碼後的檔案內容。
9.text:若接收到是 type: recordEvent,此屬性的內容是該錄音檔案經由TTS辨識後轉換為文字的內容。

協定名稱
發佈電話執行動作
Topic
phone-conn/callAction/${SNKey}
協定描述
發佈電話執行動作。此功能需配合前項「取得DTMF按鍵及電話事件」使用,用來回覆電話連結服務所發出的service requset訊息。
模式

Publish

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

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

協定名稱
取得電話執行動作除錯訊息
Topic
phone-conn/callActionDebug/${SNKey}
協定描述
取得電話執行動作除錯訊息。在發佈電話執行動作訊息後,若是訊息格式有錯誤,系統會透過這個topic發送訊息告知創客
模式

Subscribe

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