即時通訊平台 API 指南

本頁說明如何使用即時通訊平台 API 端點中所述的即時通訊端點。

術語

為求清楚，以下列出一些定義，使用本文件時請務必留意。

客戶：在軟體中導入即時通訊平台 API 的 Contact Center AI 平台 (CCAI 平台) 客戶。
消費者：向即時通訊平台 API 發出要求的軟體。
使用者：客戶軟體的使用者，嘗試與服務專員進行即時通訊。

Webhook 驗證

聊天平台 API 會將聊天期間發生的事件傳送至消費者的伺服器，藉此通知消費者。Webhook 酬載和類型定義於 API 規格中。每個 webhook 要求都包含兩個標頭：X-Signature 和 X-Signature-Timestamp。

X-Signature 包含 Webhook 簽名，格式如下： primary=<primary_signature> secondary=<secondary_signature>

主要和次要簽章分別是主要或次要 Webhook 密鑰的 Base64 編碼 sha256 摘要，以及 X-Signature-Timestamp 標頭和要求 JSON 酬載的串連字串。

以下是在 Ruby on Rails 範例應用程式中，為 Webhook 請求授權的實作範例：

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

總覽

一般來說，聊天平台 API 對話的基本流程如下。重點會編號，並提供附註，方便您瞭解其他背景資訊。請注意，客戶只需負責實作圖表中的「客戶」端，Contact Center AI 平台則會處理圖表中的系統和服務專員端。圖表中納入這些項目，只是為了讓讀者瞭解整個即時通訊流程。

顯示即時通訊平台 API 對話流程。

建立終端使用者

建立即時通訊時，必須提供有效的終端使用者 ID，也就是說，必須先在 Contact Center AI Platform 系統中建立終端使用者，才能建立即時通訊。
系統會根據使用者的 identifier 屬性 (消費者提供的字串值) 識別使用者。如果使用者已使用網頁或行動 SDK，系統中可能已有該使用者。POST /end_users 端點會實作等冪的 upsert，因此如果使用者已存在，再次嘗試建立使用者會更新任何變更的資料，並傳回使用者的資訊。

建立即時通訊

如要使用即時通訊平台 API 建立對話，請按照下列步驟操作：

處理新的即時通訊酬載：即時通訊初始化程序會與 POST /chats 要求非同步進行。因此，系統可能會在 POST /chats 建立端點傳回 API 回應之前或之後，收到 chat_created 事件。建議以等冪方式處理 chat_created 事件和即時通訊建立 API 回應，避免消費者端發生任何錯誤。
建立附有轉錄稿的即時通訊：即時通訊平台 API 支援建立附有現有對話轉錄稿的即時通訊，適用於在客戶平台 (例如聊天機器人) 內進行即時通訊，然後再傳送至 Contact Center AI 平台的情況。這項功能可為接聽對話的服務專員提供對話工作階段的額外資訊，避免使用者重複說明問題。如要瞭解轉錄稿酬載格式，請參閱 chat_platform_openapi.yaml。

佇列選擇虛擬服務專員

為簡化 API 消費者的選單選擇，聊天平台 API 的設計是與 Dialogflow 虛擬代理程式搭配使用，協助新對話排隊。

如要設定虛擬服務專員，請按照下列步驟操作：

為此目的建立專屬虛擬代理程式，並指派給佇列。透過即時通訊平台 API 建立的所有新對話，都應在這個佇列中建立。本文件不包含建立及設定新虛擬代理的內容。
使用 POST 或 chats 端點建立新即時通訊時，請加入自訂內容酬載，其中包含虛擬服務專員可用來判斷即時通訊應轉送至哪個佇列的即時通訊內容。內容酬載可包含客戶定義的任何自訂資料，但必須採用下列格式，虛擬服務專員才能存取佇列指派的資料。
- 舉例來說，"context": {"value": {"foo": "bar" } } 可讓虛擬代理程式讀取 $session.params.context.foo，值為 bar。
虛擬服務專員會使用內容欄位中的資料，根據顧客的設定方式，將即時通訊轉送至所選佇列。如果目標佇列中沒有可用的服務專員 (例如佇列已過服務時間或超出容量)，系統會將升級要求轉移，並向消費者傳送網路鉤子，說明轉移原因和可用的轉移選項。

轉接次數減少：如果已在 Contact Center AI 平台入口網站中設定，聊天平台 API 支援的聊天轉接次數減少選項如下：

電子郵件：請使用者傳送電子郵件給支援團隊，並結束即時通訊。當使用者選取這個選項後，系統會傳送電子郵件。客戶必須使用 PATCH /chats/:id 端點，並在要求主體中加入下列參數："status": "finished" , "escalation_id": <id of escalation> , 和 "deflection_channel": "email"，將對話標示為已轉移並結束。
繼續使用虛擬服務專員：從技術上來說，這是有效的轉移選項，但如果使用佇列選取虛擬服務專員，虛擬服務專員只會嘗試再次轉移對話，因此不合理。
繼續等待專員：這個選項僅適用於原因為 over_capacity 的案件。如果使用者選擇這個選項，請使用 PATCH chats/:id/escalations/:id with deflection_channel=human_agent 更新升級迴避
- 外部轉移連結：警告使用者，選取轉移連結會結束對話。如果選取連結，請結束對話並使用 external_link 做為 deflection_channel 參數

收發訊息

如要傳送或接收訊息，請按照下列步驟操作：

文字內容：如要傳送訊息，請使用 API 文件中定義的 POST /chats/:id/message 端點。如要接收訊息，請監聽 message_received Webhook 事件。請注意，API 消費者會收到透過 API 傳送的所有訊息 (包括使用者傳送的訊息) 的 message_received 事件。
相片和影片內容：系統會先從 Contact Center AI Platform 擷取已設定的 Cloud Storage 服務預先簽署上傳網址，然後上傳至儲存服務，最後將儲存網址傳送至 Contact Center AI Platform 的訊息酬載中。
1. 擷取預先簽署的網址：使用 POST /v1/chats/:chat_id/photos/upload 或 POST /v1/chats/:chat_id/videos/upload endpoints 從 Contact Center AI 平台擷取預先簽署的網址。這個端點會傳回預先簽署的網址，以及上傳檔案時要轉送至儲存空間服務的一組欄位。預先簽署上傳作業有下列限制：
  - 相片的 Content-Type 為 image/jpeg，影片則為 video/mp4。
  - 相片大小上限為 2 MB。影片大小上限為 20 MB。
  - 有效時間為 5 分鐘。
  - 客戶必須先調整相片大小和方向，才能上傳。
  - 每個預先簽署的網址僅適用於單一相片或影片。如要傳送多個附件，必須為每個附件要求預先簽署的網址。
2. 上傳媒體檔案：如要上傳媒體檔案，請對步驟 2a 中擷取的預先簽署網址提出 POST 要求，並在要求主體中加入下列內容：
  - "file"：要上傳的檔案
  - 預先簽署的網址要求中，欄位物件內傳回的所有欄位。
3. 將媒體檔案新增至對話：如要將媒體檔案新增至對話，請使用 POST /chats/:id/photos 或 POST /chats/:id/videos 端點。請注意，相片端點支援傳送相片陣列，而影片端點一次只支援一部影片。
  - s3_path 要求主體參數應與預先簽署的網址回應的 key 欄位值相同。
  - 要求成功後，系統會傳回兩個欄位。建議在 API 消費者中儲存或快取 media_id 對應至網址的對應項，因為即時通訊訊息中的所有媒體都會僅由 media_id 參照。
    - url：檔案所在的唯讀 S3 或 Cloud Storage 網址。
    - media_id：Contact Center AI 平台中的媒體檔案 ID。這是媒體在即時通訊酬載中參照的 ID。
4. 以即時通訊訊息形式傳送媒體檔案：如要以即時通訊訊息形式傳送媒體檔案，請將下列酬載傳送至 POST /chats/:id/message endpoint：
```
{
  "from_user_id": <id of end user>,
  "message":
    "type": <"photo" or "video">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}
```

預期 API 回應中會出現無法辨識的 JSON 金鑰

所有 API 更新都具備回溯相容性。我們保留隨時在現有 API 回應中導入新 JSON 鍵的權利。建議您採取防禦性做法處理回應，忽略任何無法辨識的鍵，以維持功能運作。

即時通訊平台 API 指南 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

術語