使用 REST API 來控制 SMS 階段作業

SMS Gateway 提供 REST API，讓您用於客服中心應用程式中，這樣服務專員就可以起始客戶與 SMS 代理程式之間的 SMS 階段作業。您可以使用其 cURL 指令，將 REST API 納入應用程式中。為了進行測試，您也可以透過其 Swagger 使用者介面，直接與 REST API 互動。

關於 REST API

透過 REST API，您可以執行一些可用的作業（例如：建立階段作業或測試配置），來控制 SMS 階段作業。REST API 會藉由傳遞兩種類型的 JSON 資料給 SMS Gateway，來控制 SMS 階段作業：

您可以透過 REST API Swagger 使用者介面，直接測試每一項作業，或是針對您客服中心應用程式內的每一項作業，使用 cURL 指令。

您可以執行的作業

利用 REST API，您可以執行下列作業。

只要有作業不成功，請檢查 SMS Gateway 日誌，取得哪裡出錯的相關資訊。

存取 REST API Swagger 使用者介面

部署 SMS Gateway 之後，您可以存取位於下列 URL 的 REST API Swagger 使用者介面：

在產生的 SMS Gateway API 頁面上，按一下列出作業，檢視 SMS 階段作業的可用作業。

測試作業

  1. 在資料類型直欄之下，按一下範例，在值欄位中預先移入資料。
  2. 修改值欄位中的 JSON 資料，例如：輸入使用者和租戶電話號碼。 重要事項：租戶電話號碼必須確實是 SMS Gateway 配置中指定的租戶電話號碼。
  3. 按一下試用看看！，來執行作業。
  4. 如果出現提示，請輸入使用者名稱和密碼。只有在您已啟用 REST API 的鑑別，才會提示您進行鑑別。

在您嘗試執行作業之後，介面會顯示下列資訊：

使用 cURL 指令

您可以使用 cURL 指令（在指令行上，或是將指令納入應用程式中），來執行 REST API 作業。Linux 型系統通常包含 cURL，但是如果您的作業系統不包含 cURL，您可以從 curl.haxx.se，下載並安裝適合您作業系統的套件。

指定用來傳送要求的指令時，請使用下列格式：

curl -X <HTTP request> --header 'Content-Type: application/json' --header 'Accept: application/json' -d <JSON data>

您也可以指定下列選項。如需每一個選項的詳細資料，請參閱 curl 說明文件。

指令範例

下列範例 curl 指令示範可利用 REST API 來執行的各種作業。當您執行範例指令時，請務必以您自己的值取代 smsUserPhoneNumber 和 smsTenantPhoneNumber 值。

重要事項：租戶電話號碼必須與 SMS Gateway 配置中指定的租戶電話號碼完全相符。指定使用者電話號碼時，其格式必須符合您 SMS 提供者的要求。例如，Twilio 電話號碼需要加號 (+)，但是指定 RestcommONE 電話號碼時，則不得有加號 (+)。

管理階段作業

使用下列指令來管理階段作業。

建立階段作業
curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsUserData": { "data": "Data"}, \
   "smsSessionTimeoutCount": 600 \
}' 'http://host:9080/sms.gateway/session'
刪除階段作業
curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789" \
}' 'http://host:9080/sms.gateway/session'

測試配置

使用下列指令來測試配置。

測試 SMS 提供者配置
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321", \
   "smsUserPhoneNumber": "+12345556789" \
 }' 'http://host:9080/sms.gateway/testConfig/SMSProvider'
測試 Watson Assistant 服務配置
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321", \
   "smsUserPhoneNumber": "+12345556789", \
   "smsUserData": { "data": "Data" }, \
   "smsSessionTimeoutCount": 600 \
}' 'http://host:9080/sms.gateway/testConfig/WCS'
測試 XSLD 快取伺服器配置
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsTenantPhoneNumber": "+18765554321" \
}' 'http://host:9080/sms.gateway/testConfig/XS'

整合 SMS Gateway 時支援 Voice Gateway 指令範例

下列的 curl 範例指令所示範的指令，供 SMS Gateway 用來支援客戶在通話期間，與 Voice Gateway 之間進行 SMS 訊息的傳送及接收。當您執行範例指令時，請以您自己的值取代 smsUserPhoneNumber 和 smsTenantPhoneNumber 值。為了讓範例指令能順利運作，您還必須在 SMS Gateway 伺服器 URL 中配置 host 和 port，以傳送要求。您的 SMS Gateway 伺服器 URL 可以是 http:// 或 https:// （此視何時配置安全埠而定），但一律必須包含 /sms.gateway/smsPipe。

您可以在 REST API Swagger 使用者介面上，找到要求和回應變數的說明。請參閱存取 REST API Swagger 使用者介面。

重要事項：租戶電話號碼必須與 SMS Gateway 配置中指定的租戶電話號碼完全相符。指定使用者電話號碼時，其格式必須符合您 SMS 提供者的要求。例如，Twilio 電話號碼需要加號 (+)，但是指定 RestcommONE 電話號碼時，則不得有加號 (+)。

建立 SMS 管道

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsResponseURL": "https://vgwServer:port/smsRecv", \
   "smsToken": "tokenID",\
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
        "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ], \
   "smsMessage": "Hello this is a chat message sent from Voice Gateway.",\
   "smsOpaqueData": { "data": "Data"} ,\
   "smsPipeTimeoutCount": 1200 \
}' 'http://host:port/sms.gateway/smsPipe'

使用 SMS 管道 ID 來傳送 SMS 或 MMS 訊息

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsMessage": "Hello this is a chat message sent from Voice Gateway.",\
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
           "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ], \
   "smsOpaqueData": { "data": "Data"}
 }' 'http://host:port/sms.gateway/smsPipe/pipeID/KzE1MTAzMzAyNTgyOisxOTE5Njk5MjYwzJjZmNhZC1lMzc/sms'

不使用 SMS 管道 ID 來傳送 SMS 或 MMS 訊息

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{ \
   "smsUserPhoneNumber": "+18765554321", \
   "smsTenantPhoneNumber": "+12345556789", \
   "smsMessage": "Hello this is a chat session starting from Voice Gateway."
 \
   "smsMediaURL": [ "https://media.com/media/l4JyRqcDU93S334KQ/first.gif", \
           "https://media.com/media/l4JyRqcDU93S334KQ/second.gif" ]
 }' 'http://host:port/sms.gateway/smsPipe/sms'

刪除 SMS 管道

curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{}' 'http://host:port/sms.gateway/smsPipe/pipeID/KzE1MTAzMzAyNTgyOisxOTE5Njk5MjYwzJjZmNhZC1lMzc'