聊天平台 API 整合指南

請參閱本指南，瞭解如何使用 Apps API 建構伺服器端即時通訊整合。完成整合後，您的應用程式將可執行下列操作：

  • 向 Apps API 驗證。

  • 建立或更新終端使用者。

  • 為該使用者發起即時通訊。

  • 接收並驗證 Contact Center AI 平台的 Webhook 事件。

  • 在即時通訊中傳送訊息。

  • 處理選用分支，例如匯入對話前轉錄稿、選取佇列、虛擬服務專員轉送、減少升級案件，以及附加媒體。

  • 對話完成後，請結束即時通訊。

本指南適用於開發人員，協助他們建構後端服務，將客戶擁有的即時通訊體驗連結至 CCAI 平台。本文假設您可以在 CCAI Platform 中建立 API 憑證、代管 HTTPS Webhook 端點、安全地儲存密鑰，以及從伺服器發出 HTTP 要求。

本指南是 Apps API Chat 端點的補充資料。請參閱 API 參考資料，瞭解完整的請求和回應結構定義，並參閱本指南，瞭解建議的端對端導入流程。

術語

本文件採用下列定義：

  • 客戶：在自家軟體中導入即時通訊整合功能的 CCAI 平台客戶。

  • 消費者：客戶擁有的伺服器端應用程式，會向 Apps API 發出要求，並接收 CCAI 平台 Webhook 事件。

  • 使用者：使用客戶軟體與服務專員或虛擬代理展開或繼續對話的人員。

  • 對話：Apps API 建立的 CCAI 平台對話資源。

  • Webhook 端點：消費者應用程式中的 HTTPS 端點，用於接收 CCAI Platform 的即時通訊事件。

事前準備

開始之前，請確認您具備以下項目：

  • 應用程式 API 憑證

    • 在 CCAI 平台中依序前往「設定」 >「開發人員設定」 >「API 憑證」，建立 API 憑證。

    • 請妥善儲存憑證密碼。請勿在瀏覽器或行動用戶端程式碼中公開。

  • 租戶網址詳細資料

    • 找出 CCAI 平台子網域和網域。

    • Apps API 基本網址為： https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1

  • Webhook 端點

    • 代管可接收 CCAI Platform POST 要求的公開 HTTPS 端點。

    • 在 CCAI 平台開發人員設定中設定端點。

    • 產生並儲存 Webhook 主要和次要密鑰。

  • 佇列或選單設定

    • 找出新即時通訊進入的佇列或選單。

    • 如果您使用佇列選取虛擬代理，請先設定該虛擬代理並指派給進入佇列，再透過 API 建立即時通訊。

  • 使用者身分

    • 決定系統要為每位使用者採用哪個穩定 ID。

    • 儲存 Apps API 傳回的 CCAI Platform 使用者 ID。

  • 頻率限制處理

    • CCAI 平台會限制 Apps API 的速率。在整合中建構重試和退避機制，並避免為單一房客傳送大量要求。

驗證和 Webhook 安全性

您的整合功能使用兩種驗證路徑：

  • 從伺服器向 CCAI 平台發出要求時，應用程式 API 驗證。

  • 驗證從 CCAI 平台傳送至伺服器的要求是否為 Webhook 簽章。

驗證 Apps API 要求

要求會使用 HTTP 基本驗證。在 CCAI Platform 中依序前往「設定」 >「開發人員設定」 >「API 憑證」，建立 API 權杖，然後在「password」欄位中傳遞權杖 (建議)。如果租戶使用舊版驗證路徑，您可以改為將公司金鑰當做使用者名稱，公司密碼當做密碼。如需完整的驗證設定，請參閱 Apps API 參考資料。以下範例說明如何使用基本驗證，驗證 Apps API 要求：

curl -X GET \
  https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1/chats/{chat_id} \
  -u "YOUR_SUBDOMAIN:YOUR_API_TOKEN" \
  -H "Accept: application/json"

將憑證儲存在伺服器端的密碼存放區，並根據安全政策輪替憑證，且絕不在瀏覽器或行動應用程式中傳送憑證。

驗證 Webhook 要求

CCAI 平台會將即時通訊事件傳送至 Webhook 端點。每個 Webhook 要求都包含：

  • X-Signature

  • X-Signature-Timestamp

X-Signature 標頭可包含主要簽章、次要簽章或兩者：

primary=<primary_signature> secondary=<secondary_signature>

每個簽章都是 Base64 編碼的 HMAC-SHA256 摘要。簽署值是時間戳記標頭與原始 JSON 要求主體的串連：

X-Signature-Timestamp + raw_request_body

在 webhook 處理常式中：

  1. 請參閱「X-Signature」和「X-Signature-Timestamp」。

  2. 如果缺少任一標頭，請拒絕要求。

  3. 拒絕過時的時間戳記，降低重播攻擊風險。

  4. 在剖析 JSON 之前，請先讀取原始要求主體。

  5. 使用每個有效的 Webhook 密鑰計算預期簽章。

  6. 使用恆定時間比較，比較收到的簽章和預期簽章。

  7. 如果任何有效密鑰相符，則接受要求。

以下 Ruby 實作範例說明如何驗證 UJET 網路鉤子簽章：

require "base64"
require "openssl"
require "active_support/security_utils"

def parse_ujet_signature(header)
  header.to_s.split(/\s+/).each_with_object({}) do |part, result|
    key, value = part.split("=", 2)
    result[key] = value if key && value
  end
end

def expected_signature(secret, timestamp, raw_body)
  Base64.strict_encode64(
    OpenSSL::HMAC.digest(
      OpenSSL::Digest.new("sha256"),
      secret,
      "#{timestamp}#{raw_body}"
    )
  )
end

def secure_match?(received, expected)
  return false if received.nil? || expected.nil?
  return false unless received.bytesize == expected.bytesize

  ActiveSupport::SecurityUtils.secure_compare(received, expected)
end

def verify_ujet_webhook!(request, primary_secret:, secondary_secret:)
  signature_header = request.headers["X-Signature"]
  timestamp = request.headers["X-Signature-Timestamp"]

  return false if signature_header.nil? || timestamp.nil?

  # Optional but recommended: reject stale requests.
  return false if (Time.now.utc - Time.at(timestamp.to_i).utc).abs > 5.minutes

  raw_body = request.body.read
  signatures = parse_ujet_signature(signature_header)

  expected = [
    expected_signature(primary_secret, timestamp, raw_body),
    expected_signature(secondary_secret, timestamp, raw_body)
  ].compact

  received = [
    signatures["primary"],
    signatures["secondary"]
  ].compact

  received.any? do |received_signature|
    expected.any? do |expected_signature_value|
      secure_match?(received_signature, expected_signature_value)
    end
  end
end

如果驗證成功，請快速傳回成功回應，並以等冪方式處理事件。Webhook 傳送和 API 回應的順序可能不同，因此請建構整合作業，允許重複接收相同的狀態變更，但不會建立重複記錄。

整合流程

以下流程會建立使用者、開始對話、接收 CCAI 平台事件、交換訊息，以及結束對話。

建立或更新使用者

目標：確保 CCAI Platform 在您建立對話前，已擁有使用者記錄。

端點

使用下列端點建立或更新使用者：

POST /apps/api/v1/end_users

要求範例

以下範例說明如何建立或更新使用者時的要求主體：

{
  "identifier": "customer-user-12345",
  "email": "customer.user@example.com",
  "name": "Customer User",
  "phone": "+15551234567"
}

可儲存的內容

將回應中的 CCAI Platform 使用者 ID 儲存在系統中。建立對話時請使用該 ID。

預期功用

  • 如果沒有該名使用者，CCAI Platform 會建立新記錄。

  • 如果已存在具有相同 ID 的使用者，CCAI Platform 會更新記錄，並傳回現有使用者的資訊。

建立對話

目標：為使用者啟動新的 CCAI 平台即時通訊。

端點

使用下列端點發起新對話：

POST /apps/api/v1/chats

要求範例

以下範例說明如何建立對話的要求主體：

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en"
  }
}

虛擬服務專員轉接的選用情境

如果佇列選取虛擬代理需要應用程式的內容，請在建立即時通訊時加入內容酬載，如下列範例所示：

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en",
    "context": {
      "value": {
        "customer_tier": "gold",
        "issue_type": "billing"
      }
    }
  }
}

虛擬代理可根據該脈絡中的值，決定要將即時通訊轉送至哪個佇列。

預期功用

  • Apps API 會傳回即時通訊資源。

  • CCAI Platform 會將 chat_created Webhook 事件傳送至您設定的 Webhook 端點。

  • API 回應和 Webhook 事件的抵達順序不一定。將兩者視為同一筆聊天記錄的更新，並以聊天 ID 做為鍵。

處理即時通訊 Webhook 事件

目標：讓消費者應用程式與 CCAI 平台即時通訊狀態保持同步。

Webhook 端點會處理 CCAI 平台的即時通訊生命週期和訊息事件。至少儲存：

  • 即時通訊 ID。

  • 事件類型。

  • 事件時間戳記。

  • 如果事件包含訊息，則為訊息傳送者、訊息類型和訊息內容。

  • 事件說明路徑行為時，任何升級或轉移資料。

建議行為

  • 處理事件前，請先驗證每個 Webhook 簽章。

  • 儲存已處理的事件 ID 或確定性事件鍵，避免重試時建立重複項目。

  • 接受事件後，傳回 2xx 回應。

  • 盡可能非同步處理下游副作用。

預期功用

當 CCAI 平台傳送聊天建立、傳入訊息、專員訊息、轉接變更和聊天完成等事件時，應用程式會更新聊天狀態。

傳送簡訊

目標：將使用者訊息從消費者應用程式傳送至 CCAI 平台聊天室。

端點

使用下列端點將簡訊傳送至對話：

POST /apps/api/v1/chats/{chat_id}/message

要求範例

以下範例顯示傳送簡訊的要求主體：

{
  "from_user_id": 456,
  "message": {
    "type": "text",
    "content": "Hello, I need help with my order."
  }
}

預期功用

  • CCAI 平台接受訊息。

  • 訊息會顯示在服務專員或虛擬服務專員的對話中。

  • Webhook 端點會收到訊息的訊息事件，包括您自己的應用程式透過 Apps API 傳送的訊息。

接收及顯示 CCAI 平台傳送的訊息

目標：在客戶擁有的即時通訊體驗中，顯示服務專員或虛擬服務專員的訊息。

Webhook 端點收到訊息事件時：

  1. 驗證 Webhook 簽章。

  2. 確認活動是否為新活動。

  3. 透過即時通訊 ID 識別即時通訊。

  4. 識別寄件者和訊息類型。

  5. 在顧客擁有的即時通訊 UI 中顯示訊息。

  6. 保留事件，以免重新整理或重試時遺失對話記錄。

預期功用

客戶擁有的即時通訊 UI 會依正確順序顯示服務專員、虛擬服務專員和使用者傳送的訊息。如果事件順序有誤，請使用事件時間戳記和您自己的持續性層，調整顯示順序。

從虛擬代理轉接給真人服務專員

目標：當使用者需要服務專員協助時，將對話從虛擬代理轉移至真人服務專員佇列。

如果整合功能使用佇列選取虛擬代理人，請將虛擬代理人設為將即時通訊轉送至目標佇列。如果伺服器直接啟動升級程序，請使用 Apps API 升級端點。

端點

使用下列端點，將虛擬代理的即時通訊提報給真人服務專員：

POST /apps/api/v1/chats/{chat_id}/escalations

要求範例

以下範例顯示提報即時通訊的要求主體：

{
  "reason": "by_end_user_ask",
  "force_escalate": false
}

預期功用

  • 如果目標佇列有空，系統會將即時通訊轉交給服務專員處理。

  • 如果因非上班時間或超出容量限制而無法使用佇列，CCAI Platform 可以透過即時通訊流程傳回或傳送轉移選項。

  • 整合功能會向使用者顯示可用的解決方案。

記錄提報案件的選擇

目標：告知 CCAI 平台使用者選取的轉移選項。

當 CCAI Platform 提供升級迴避選項時，請使用升級更新端點記錄使用者的選擇。

端點

使用下列端點，以解決方案選項更新待處理案件記錄：

PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}

支援的 deflection_channel 值：

  • email：使用者選擇電子郵件轉移選項。

  • virtual_agent：使用者選擇繼續與虛擬服務專員對話。

  • human_agent：使用者選擇繼續等待真人服務專員。這項值僅適用於容量過剩的轉向。

要求範例

以下範例顯示記錄解決方案選擇的要求主體：

{
  "deflection_channel": "email"
}

請只將支援的 deflection_channel 值傳送至這個端點。external_link 不是提升更新端點的有效值；當使用者點選外部轉移連結時，系統會結束對話。

預期功用

CCAI Platform 會更新轉交記錄，並根據所選選項轉移對話。

結束對話

目標：在對話完成後關閉即時通訊。

端點

如要結束進行中的即時通訊，請使用下列端點：

PATCH /apps/api/v1/chats/{chat_id}/end

要求範例

以下範例顯示結束對話的要求主體：

{
  "ended_by_user_id": 456
}

預期功用

  • CCAI Platform 結束即時通訊。

  • Webhook 端點會收到最終的聊天狀態事件。

  • 應用程式會將對話標示為完成，並停止接受該對話的新使用者訊息。

進階流程

以下分支版本為選用項目。只導入適用於整合的流程。

匯入即時通訊前轉錄稿

如果終端使用者在您建立 CCAI Platform 對話前，已在系統中進行對話 (例如與聊天機器人對話)，請使用這個流程。

建立對話時，請新增轉錄稿酬載。通話記錄可為服務專員提供背景資訊，因此使用者不必重複提供資訊。

Apps API 參考資料包含確切的轉錄稿結構定義。

透過佇列選擇虛擬代理將即時通訊轉送給服務專員

如果應用程式會將所有新對話傳送至進入佇列，並讓虛擬服務專員決定最終目標佇列，請使用這個流程。

  1. 建立虛擬代理，用於選取佇列。

  2. 將虛擬代理指派給進入佇列。

  3. 建立對話時加入脈絡。

  4. 設定虛擬代理，檢查對話內容並將對話提報至正確佇列。

  5. 如果目標佇列無法使用，請處理轉移選項。

傳送相片或影片附件

如果使用者透過客戶擁有的即時通訊 UI 傳送媒體，請使用這個流程。

媒體流程分為四個階段。

第 1 階段：要求預先簽署的上傳網址

使用下列端點要求上傳相片或影片的預先簽署網址：

POST /apps/api/v1/chats/{chat_id}/photos/upload
POST /apps/api/v1/chats/{chat_id}/videos/upload

階段 2：將檔案上傳至傳回的儲存空間網址

請一併加入檔案和 CCAI Platform 在預先簽署上傳回應中傳回的任何欄位。

階段 3：將上傳的檔案新增至對話

使用下列端點將上傳的相片或影片新增至對話：

POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos

儲存 CCAI 平台傳回的 media_id。即時通訊訊息酬載會透過媒體 ID 參照媒體。

階段 4：將媒體做為訊息傳送

使用下列端點將媒體訊息傳送至對話：

POST /apps/api/v1/chats/{chat_id}/message

要求範例

以下範例顯示傳送相片附件的要求主體：

{
  "from_user_id": 456,
  "message": {
    "type": "photo",
    "content": {
      "media_id": 789
    }
  }
}

針對影片訊息使用 video 訊息類型和影片 media_id。

在即時通訊期間傳送自訂資料

如果整合服務需要將客戶定義的背景資訊附加至進行中的即時通訊，請使用下列端點：

POST /apps/api/v1/chats/{chat_id}/custom_data

Apps API 參考資料會定義確切的酬載形狀和保留鍵行為。

在對話期間更新使用者身分

如果聊天開始後，使用者的身分有所變更或已確認，請使用下列端點：

POST /apps/api/v1/chats/{chat_id}/end_user

舉例來說，如果匿名使用者在進行中的即時通訊期間登入，而您的整合服務需要 CCAI Platform 將即時通訊與更新後的使用者身分建立關聯，請使用這個端點。

收集 CSAT 或評分資料

如果您的整合服務擁有通訊後評分體驗，請使用下列即時通訊 CSAT 和評分端點：

GET /apps/api/v1/chats/{chat_id}/csat
GET /apps/api/v1/chats/{chat_id}/rating
PATCH /apps/api/v1/chats/{chat_id}/rating

如需確切的資格規則和評分酬載，請參閱 Apps API 參考資料。