外部工作階段事件

外部工作階段事件功能可讓您使用 Webhook，將 CCAI 平台的即時資料串流至外部系統。這樣一來，您就能立即掌握工作階段生命週期，以便製作自訂報表、更新 CRM 記錄，或自動執行互動後工作流程。

外部工作階段事件提供以推送為基礎的機制，可在即時通訊或語音通話狀態變更時通知伺服器。提供 API 端點後，CCAI 平台會在發生轉移時，將 JSON 格式的事件資料 POST 到您的基礎架構，例如通話已連線、已指派服務專員、工作階段已中斷連線。

設定外部工作階段事件

如要設定外部工作階段事件，請按照下列步驟操作：

  1. 在 CCAI Platform 入口網站中，依序點選「Settings」>「Developer Settings」。 如果沒有看到「設定」選單，請按一下「選單」圖示 。

  2. 在「Session Data Export」(工作階段資料匯出) 窗格中，按一下「Manage Data Export Settings」(管理資料匯出設定)。 「匯出工作階段資料」頁面隨即顯示。

  3. 前往「外部工作階段事件」窗格，然後點選切換按鈕，將其設為開啟。

  4. 執行下列任一操作或同時完成兩者：

    • 如要設定外部通話工作階段事件，請按照下列步驟操作：

      1. 勾選「通話事件 - 傳送通話工作階段事件」核取方塊。

      2. 在「API Endpoint」(API 端點) 欄位中，輸入目標 API 的完整 HTTPS 網址。

      3. 輸入使用者名稱和密碼。平台會使用這些資訊進行基本驗證。

    • 如要設定外部即時通訊工作階段事件，請按照下列步驟操作：

      1. 勾選「即時通訊事件 - 傳送即時通訊工作階段事件」核取方塊。

      2. 在「API Endpoint」(API 端點) 欄位中，輸入目標 API 的完整 HTTPS 網址。

      3. 輸入使用者名稱和密碼。平台會使用這些資訊進行基本驗證。

  5. 按一下 [儲存]。

事件生命週期和狀態邏輯

隨著對話階段的進展，CCAI 平台會傳送多項更新。每次更新都會在 item 物件中加入更多中繼資料。

狀態進展表

活動順序 狀態 參與者狀態 新增重要資料點
1. 開始 connected 外部：connected call_id，顧客 dn (電話號碼)。
2. 轉送 connected 外部：connected queue_path_names、initiator (虛擬服務專員)。
3. 已指派 connected 代理商：accepted 新增即時服務專員姓名和 ID。
4. 有效 connected 代理商：connected 建立媒體串流 (開始對話)。
5. 結束 disconnected 兩者皆是：disconnected 系統會填入 ends_at 時間戳記。
6. 決賽 disconnected 代理商：dispositionSubmitted 包含結尾代碼的 dispositions 物件。

事件資料結構定義參照

系統會以物件的形式將事件傳送至 Webhook。每個 Webhook 事件的結構都相同，如下表所示：

根物件

欄位 類型 說明
count 整數 目前酬載中的事件物件數量。
events 陣列 包含工作階段詳細資料的事件物件集合。

重要工作階段欄位

  • event_id：事件通知的 UUID。
  • timestamp：事件產生時的 Epoch 時間 (以毫秒為單位)。
  • connected_at 和 ends_at：工作階段時間長度的 ISO 8601 時間戳記。
  • initiator：識別處理狀態變更的實體，例如 virtual_agent_15 或 agent_1。
  • dispositions：包含 code、custom_code_id 和任何代理程式 note 的巢狀物件。

安全性

所有要求都會隨附標準授權標頭： Authorization: Basic <base64_encoded_credentials>

提交規定

  • 方法： POST
  • Content-Type: application/json
  • 逾時：伺服器應在五秒內回應。
  • 確認：端點必須傳回 200 OK 狀態碼。 如果收到非 200 的代碼，平台可能會使用指數輪詢重試。

酬載範例

以下是透過 Webhook 傳送的事件訊息中收到的範例酬載。

進行中的對話 (已連線媒體)

{
  "count": 1,
  "events": [
    {
      "event_id": "fc066edb-d99f-4db4-ba04-fb5dfea0e86a",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "connected",
        "queue_path_names": "Test/Talk to Andrew/English",
        "participants": [
          { "state": "connected", "type": "external", "dn": "+15555555555" },
          { "state": "connected", "type": "agent", "name": "Joe Smith", "agent_number": "528431" }
        ]
      }
    }
  ]
}

最終處置 (通話後處理工作)

{
  "count": 1,
  "events": [
    {
      "event_id": "479798ff-b1ed-4a5c-a910-17a7edb3f283",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "disconnected",
        "participants": [
          {
            "type": "agent",
            "state": "dispositionSubmitted",
            "dispositions": {
              "code": "Call completed",
              "custom_code_id": "callComplete",
              "note": "none"
            }
          }
        ]
      }
    }
  ]
}