SMS API

透過 Contact Center AI 平台 (CCAI 平台)，您可以使用 SMS API 處理內送和外寄簡訊。

驗證

如要使用 SMS API，您需要憑證。

如要建立 SMS API 的憑證，請按照下列步驟操作：

  1. 在 CCAI Platform 入口網站中，依序點選「設定」 >「開發人員設定」 >「API 憑證管理」。

  2. 按一下「+ 新增 API 憑證」按鈕。系統會開啟「新增 API 憑證」訊息。

  3. 輸入憑證的「Name」(名稱)。

  4. 點選「建立」。

Outbound SMS API

外寄簡訊 API 提供端點，可啟動外寄簡訊訊息。您可透過程式輔助，向消費者傳送簡訊。

使用這項 API 時，請考量以下三項重點：

  • 這項服務並非設計為一次傳送數萬則訊息。目標是事件導向訊息。

  • 消費者可以回覆簡訊，啟動支援工作階段。

  • 如果需要在同一天內傳送多則簡訊到同一個號碼，這個 API 就無法使用。

應用實例

外送 SMS API 的用途示例是以事件為基礎。舉例來說，如果你想通知消費者訂單已可取貨，並提供回覆選項，系統會在傳送外送簡訊時建立有效工作階段；客戶回覆時，系統會將其轉送給服務專員。

這項 API 與無工作階段外送簡訊 API 的差異在於，無工作階段 API 只會傳送通知，如果消費者回覆，系統會傳送預設訊息 (如有設定)，且不會將消費者轉接給服務專員。

其他可能的用途：

  • 帳戶登入。
  • 帳戶活動。
  • 重要的帳戶使用事件。
  • 偵測已連線裝置的問題。
  • 隨選服務的預計抵達時間通知，例如外送和共乘。
  • 預約提醒。
  • 主動發出服務或帳戶警示。
  • 雙重驗證 (客戶必須有現有的代碼產生器和服務程序)。

外送 SMS API 端點

這個新端點的基礎 URI 為：

POST https://<subdomain>.<domain>/apps/api/v1/sms

支援接收簡訊

如果環境要支援接收簡訊回覆，也必須將外撥號碼設為指派給佇列的接收簡訊號碼。每個簡訊電話號碼只能指派給一個佇列。詳情請參閱「一般簡訊即時通訊設定」。

如果使用者回覆以這種方式設定的簡訊，系統會將他們帶往指派給來電簡訊電話號碼的簡訊佇列選單。詳情請參閱「簡訊訊息對話設定 - 電話號碼」。

API 作業

本節將說明 API 作業、主體參數和回應代碼。

Body 和 Params

API 要求主體應包含下列欄位：

欄位名稱 類型 必填 說明 值 附註
agent_id 整數 否 如果提供的號碼之間沒有對話，系統會將這個 ID 對應的服務專員指派給新的對話。如果服務專員已連線至現有即時通訊，系統會代表服務專員傳送訊息。
agent_email 字串 否 服務專員的電子郵件地址。
chat_type 字串 是 簡訊 SMSAP
chat_subtype 字串 是 api_initiated
end_user_number 字串 是 要傳送簡訊的號碼 驗證：有效電話號碼：+18882468888 (美國電話號碼)
outbound_number 字串 是 用於傳送簡訊的外撥電話號碼 驗證：a) 電話號碼必須是與租戶相關聯的簡訊電話號碼，b) 缺少電話號碼，c) 電話號碼格式不正確：+18882468888 (美國電話號碼)
訊息 字串 是 要傳送給消費者的簡訊 長篇訊息：將長篇訊息拆分成多則訊息 (應涵蓋現有的外送簡訊功能) 驗證：a) 缺少訊息，b) 訊息超過字元數上限 (x 個字元)
ticket_id id 否 將工作階段與特定 CRM 支援單 ID 建立關聯 注意：系統會忽略無效的票證 ID。

錯誤和成功

案件 預期結果 複製
已啟用簡訊服務
已啟用傳出簡訊服務
chat_type 值為「OutboundSMSAPI」
已提供格式正確的 end_user_number
已提供格式正確的 outbound_number
非美國電話號碼：已啟用非美國電話號碼
已提供訊息
outbound_number 和 end_user_number 之間沒有進行中的對話		 成功 (200) Success Response Sample
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
提供服務專員 ID 和電子郵件地址 錯誤 只能提供 agent_id 或 agent_email 其中之一。
提供服務專員 ID 或電子郵件地址
服務專員未連線至現有即時通訊		 錯誤 無法傳送外寄簡訊。服務專員未連線至即時通訊。
未啟用簡訊服務 錯誤 「SMS service is not enabled」(未啟用簡訊服務)。
未啟用外送簡訊服務 錯誤 「Outbound SMS service is not enabled」(未啟用外送簡訊服務)
未提供 chat_type 錯誤 「chat_type needs to be provided」(必須提供 chat_type)
已提供 chat_type，但未設為「sms」 錯誤 「必須提供有效的 chat_type」
提供 end_user_number，但格式不正確 錯誤 「end_user_number is invalid」
(注意：美國電話號碼的有效電話號碼為「+18882468888」)
未提供 end_user_number 錯誤 「end_user_number is required」(必須提供 end_user_number)
提供 outbound_number，但格式不正確 錯誤 「outbound_number is invalid」
(注意：有效電話號碼：「+18882468888」為美國電話號碼)
提供 outbound_number，但該房客不存在 錯誤 「outbound_number is not found」(找不到外撥號碼)
未提供 outbound_number 錯誤 「outbound_number is required」(必須提供 outbound_number)
outbound_number 不是美國電話號碼，且未啟用「非美國電話號碼服務」 錯誤 「Non US phone number service is not enabled」(未啟用非美國電話號碼服務)
注意：取決於「Non-US phone number」(非美國電話號碼) 設定，請依序前往「設定」>「通話中簡訊」>「Non-US Phone Number Configurations」(非美國電話號碼設定)
訊息為空白 錯誤 「message is required」(必須提供訊息)
outbound_number 和 end_user_number 之間的有效即時通訊 錯誤 「無法傳送外寄簡訊。消費者已處於有效簡訊工作階段中。」
已填寫 ticket_id，但 CRM 中沒有這個 ID 錯誤 「找不到票證」

簡訊有效期限

外寄簡訊會在傳送後立即生效。

如要建立新的簡訊對話工作階段，必須先結束特定外撥電話號碼與消費者電話號碼之間的任何簡訊對話。包括使用 API 傳送的外寄簡訊。如果傳出簡訊的電話號碼與消費者電話號碼之間已有進行中的對話，任何傳出簡訊都會失敗。

自動逾時結束對話選項

自動聊天逾時選項可在「設定」>「即時通訊」>「簡訊到期時間和全域逾時」中設定。如果即時通訊工作階段流程沒有任何活動或進度，這項設定可控制即時通訊工作階段的有效時間。

即時通訊狀態的區別

以下是即時通訊程序狀態變更的區別：

  • 佇列選取狀態 - Chat 逾期使用 API 傳送的出站訊息會視為處於佇列選取狀態，直到消費者回覆為止

    未進入佇列選取狀態的任何即時通訊工作階段。包括傳送給消費者但未收到回覆的簡訊。您可以定義聊天室在過期前可維持此狀態的時間長度 (傳送訊息後，消費者未在計時器時間內回覆 - 聊天室過期)。

  • 未回覆的簡訊即時通訊對話逾時 (在服務時間內)：在特定佇列的服務時間內，即時通訊對話在佇列中未獲回覆的逾時時間長度。

  • 未回覆的簡訊對話到期時間 (在非上班時間)：在特定佇列的設定營業時間外，對話在佇列中未獲回覆的到期時間長度。

  • 傳出簡訊對話逾時：如果傳出簡訊對話工作階段閒置 [x] 分鐘，系統會自動終止工作階段。

即時通訊狀態詳細資料

  • 使用 API 傳送外送 SMS 時，系統會將對話視為「有效」，但不會視為「已連線」

  • 這些活躍的出站簡訊對話會處於佇列選取狀態，直到消費者回覆為止

  • 消費者回覆訊息並指派服務專員後，即視為已連線

聊天室狀態對已套用計時器的影響

  • 使用 API 傳送的有效對話，如果消費者尚未回覆，就會受到佇列選取狀態計時器的影響

  • 與服務專員連線的即時通訊會受到「傳出」逾時計時器的影響

  • 如果消費者回覆初始訊息，但系統從未指派服務專員，即時通訊就不會連線，且會受到未回覆即時通訊逾時計時器影響，無論是否在營業時間內

API 訊息流程和狀態範例：

  1. 系統使用 API 將簡訊傳送給消費者 - 即時通訊處於佇列選取狀態，且未連線至服務專員

  2. 佇列選取狀態即時通訊到期計時器會開始計時。如果消費者未在計時器時間範圍內回覆，即時通訊就會逾時並結束。

  3. 消費者回覆即時通訊訊息 - 即時通訊現在已連線至服務專員。

  4. 消費者傳送最後一則訊息 - 外寄簡訊對話逾時計時器啟動。

  5. 已達到外送 SMS 即時通訊逾時計時器門檻，即時通訊已結束。

沒有即時通訊關閉計時器 - 對於 API 啟動的外送簡訊工作階段，即時通訊關閉計時器不會運作，因此即使消費者回覆訊息，該即時通訊以傳入即時通訊的形式傳入後，也不會發生即時通訊關閉事件。

回覆定義

API 會傳回單一通話物件，如 /calls 中的模型所示。

無工作階段外送 SMS API

CCAI Platform 提供 Outbound SMS API，可支援傳出簡訊，無須連結任何工作階段。

這項 API 呼叫會啟動非工作階段連結的簡訊訊息，可在現有工作流程中使用 CCAI 平台觸發。

如果只是要傳送一次性訊息給消費者，且不需要開啟 CRM 服務單，建議使用無工作階段的簡訊。

這個 Outbound SMS API 每次 API 呼叫最多可傳送 500 則訊息。

應用實例

無工作階段簡訊的常見用途包括：

  • 設定動態密碼。

  • 驗證碼。

  • 預約提醒。

  • 意見回饋連結。

  • 行銷或宣傳訊息。

Sessionless Outbound API 和Outbound SMS API 的差異在於，使用 Outbound SMS 時，如果消費者回覆，系統會啟動有效的工作階段，並將消費者轉送給服務專員。雖然兩者有類似的用途 (傳送通知、預約提醒)，但消費者回覆時的處理方式不同。他們可能會收到預設的「請勿回覆」通知，但如果使用外送簡訊，系統會將他們轉接給服務專員。

無工作階段的出站 SMS API 端點

這個端點的基礎 URI 為：

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

新增 API 憑證

  1. 在 CCAI Platform 入口網站中，依序前往「Settings」(設定) >「Developer Settings」(開發人員設定) >「API Credential management」(API 憑證管理)。

  2. 按一下「+ 新增 API 憑證」按鈕。系統會開啟「新增 API 憑證」訊息。

  3. 輸入憑證名稱 。

  4. 點選「建立」。

傳送簡訊

如要傳送無工作階段的外送簡訊，請呼叫 POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms 並傳遞下列要求參數：

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
欄位名稱 類型 必填 說明 附註
from_phone 字串 是 傳送訊息的電話號碼。 必須是有效的美國電話號碼。
如果發生下列情況，API 呼叫會傳回錯誤：
* 電話號碼不是與房客相關聯的簡訊電話號碼
* from_phone 欄位空白
* 電話號碼格式有誤。舉例來說，以下是有效的美國電話號碼：+18882468888
to_phones 陣列 [字串] 是 訊息傳送對象的電話號碼。 為確保 API 呼叫成功，請：
* 確認電話號碼有效，例如 +18882468888
每個 API 呼叫最多可傳送 100 個電話號碼。
訊息 陣列 [字串] 是 要傳送的訊息。 最多可傳送 5 則獨立訊息。
每則訊息的字元數上限為 320 個，不得超過此限制。

API 回應

如果 API 呼叫成功，您會看到：

  • code: 200

  • 要求 ID

    請務必在系統記錄中記錄要求 ID。如需排解問題，支援團隊需要要求 ID 才能提供協助。

如果 API 呼叫失敗，您會看到：

  • 代碼：4xx

  • 錯誤訊息

簡訊限制

  • API 每分鐘最多可處理 300 則訊息。

  • 所有未處理的訊息會在 2 小時後過期。