處置代碼 API

透過結案代碼 API，整合服務可以執行下列操作：

• 取得執行個體、佇列或工作階段的處置代碼清單。

• 更新先前完成的通話或即時通訊會話的處置代碼或附註 (或兩者)。

驗證和基本網址

本文中的所有端點都使用標準 API 權杖驗證，也就是 API 使用者權杖 (不記名權杖)。

基準網址：https://SUBDOMAIN.REGION_CODE.ccaiplatform.com

取得處置代碼清單

取得可用的處置代碼。您可以查詢執行個體、佇列和工作階段層級。

依執行個體

傳回例項的完整處置代碼樹狀結構，包括所有多層處置代碼。

要求範例

下列要求會取得處置代碼的完整清單：

GET /api/v1/disposition_codes
Authorization: Bearer {token}
Content-Type: application/json

回應範例

以下範例回應顯示完整的處置代碼清單：

{
  "disposition_codes": [
    {
      "id": 1,
      "name": "Issue Resolved",
      "full_path": "/Support/Issue Resolved",
      "children": []
    },
    {
      "id": 2,
      "name": "Escalated",
      "full_path": "/Support/Escalated",
      "children": [
        {
          "id": 3,
          "name": "Tier 2",
          "full_path": "/Support/Escalated/Tier 2",
          "children": []
        }
      ]
    }
  ]
}

依佇列

傳回指派給佇列的處置代碼。如果未設定佇列專屬清單，則會傳回全域 (例項層級) 清單。

要求範例

下列要求會取得佇列的處置代碼：

GET /api/v1/disposition_codes?queue_id=QUEUE_ID
Authorization: Bearer TOKEN
Content-Type: application/json

查詢參數

參數	類型	必填	說明
queue_id	整數	是	要取得處置代碼的佇列 ID。

依工作階段

根據工作階段最後轉送的佇列，傳回指定工作階段 ID 適用的處置代碼。

要求範例

下列要求會取得工作階段的處置代碼：

GET /api/v1/disposition_codes?session_id=SESSION_ID
Authorization: Bearer TOKEN
Content-Type: application/json

查詢參數

參數	類型	必填	說明
session_id	整數	是	工作階段 ID。

更新處置代碼和附註

為先前完成的通話或即時通訊工作階段提交更新的處置代碼或附註 (或兩者)。系統會建立新的處置記錄和 CRM 記事。這項功能不會編輯原始 CRM 記錄。

要求範例

以下要求會更新工作階段的處置代碼或附註：

POST /api/v1/sessions/SESSION_ID/disposition
Authorization: Bearer TOKEN
Content-Type: application/json

路徑參數

參數	類型	必填	說明
session_id	整數	是	要更新的通話或即時通訊工作階段 ID。

要求主體範例

以下範例顯示要求主體：

{
  "disposition_code": {
    "id": 5,
    "full_path": "/Support/Verification/Pending Documents"
  },
  "notes": "Customer must upload documents via portal."
}

要求主體參數

參數	類型	必填	說明
disposition_code	物件	條件式	更新後的處置代碼。至少須提供 disposition_code 或 notes 任一項。
disposition_code.id	整數	是 (如果指定 disposition_code)	處置代碼 ID。
disposition_code.full_path	字串	是 (如果指定 disposition_code)	處置代碼的完整階層路徑，例如 /Support/Verification/Pending Documents。用於根據工作階段的處置樹狀結構進行驗證。
notes	字串	否	更新後的服務專員備註。請參閱「附註行為」表格。

附註行為

值	行為
以文字呈現，例如： "notes": "Updated notes"	以新文字取代現有附註。
以空字串表示 (「notes」:「」)	明確清除現有附註。工作階段中繼資料檔案將不再包含附註。客戶關係管理系統記錄會保留先前的記錄。
省略 (要求中沒有這個欄位)	現有附註不會變更。

請勿來電 (DNC) 處置

如要提交「請勿撥打」處置，請使用 disposition_code.id: -1。 只有在執行個體啟用「請勿來電」功能並設定 DNC 處置時，系統才會接受這項要求。否則，API 會傳回 422 Unprocessable Entity，並顯示「Do Not Call disposition is not enabled for this tenant」(這個租戶未啟用「請勿打擾」處置)。

代理歸因

API 不會攜帶代理程式身分。系統會依優先順序，將處置結果歸因於下列項目：

1. 最初為這個工作階段提交結案處置的服務專員。

2. 如果沒有原始結案處置，則為通話或即時通訊中最近的服務專員參與者。

如果兩者都不存在，API 會傳回 422 Unprocessable Entity。

驗證

以下列出驗證規則：

• 工作階段的通話或即時通訊必須已結束。嘗試更新有效工作階段的處置方式會傳回 422 Unprocessable Entity。

• 系統會根據工作階段的處置樹狀結構 (以工作階段上次的轉送佇列為準)，驗證 disposition_code.id 和 disposition_code.full_path 參數。

• allow_disposition_edit 管理員設定僅供使用者介面控制。無論這項設定為何，公用 API 一律可以更新處置資料。

回應範例

以下範例顯示成功要求的回應：

{
  "session_id": 12345,
  "disposition": {
    "id": 5,
    "name": "Verification Pending",
    "full_path": "/Support/Verification/Pending Documents",
    "notes": "Customer must upload documents via portal.",
    "submitted_at": "2026-03-13T10:15:01Z"
  }
}

注意：伺服器會根據指定的 id 和 full_path 值，從處置樹狀結構解析 name 欄位。為方便起見，系統會在回應中傳回這個值。

工作階段中繼資料

使用這個 API 更新處置狀態時，會發生下列情況：

• 外部儲存空間：系統會重新生成工作階段中繼資料檔案，並覆寫現有的中繼資料檔案。

• CRM：系統會建立新記事，並保留稽核記錄。

處理錯誤

本節說明錯誤處理。

常見狀態碼

狀態	條件	範例訊息
400 Bad Request	缺少必填欄位 (disposition_code 和 notes 皆未填寫)，或格式無效。	「必須提供至少一個處置代碼或附註。」
401 Unauthorized	API 權杖無效或遺漏。	「未經授權」
403 Forbidden	API 使用者無法存取指定的工作階段或租戶。	「Forbidden」
404 Not Found	找不到工作階段或工作階段不存在。	「找不到工作階段。」
422 Unprocessable Entity	各種驗證失敗。請參閱「422 無法處理的實體情境」表格。	請參閱「422 無法處理的實體情境」表格。

422 無法處理的實體情境

情境	錯誤訊息
通話或即時通訊工作階段仍在進行中	「工作階段尚未結束。只能更新已完成工作階段的處置方式。"
工作階段樹狀結構中找不到處置代碼 ID	「Disposition code is invalid for this session's queue.」(這個工作階段的佇列處置代碼無效)。
已提交 DNC 處置，但未啟用這項功能	「這個租戶未啟用『請勿來電』處置。」
無法解析歸因的代理參與者	「無法判斷結案歸因的服務專員。」

回應範例

以下範例顯示錯誤回應：

{
  "error": {
    "code": "session_not_ended",
    "message": "Session has not ended. Disposition can only be updated for completed sessions.",
    "details": {
      "session_id": 12345
    }
  }
}

一般整合流程

以下是典型的整合流程：

1. 取得相關佇列或工作階段的處置代碼：

   • GET /api/v1/disposition_codes?session_id=SESSION_ID

2. 向使用者或自動化系統顯示處置樹狀結構，供對方選取。

3. 提交更新後的處置方式：

   • POST /api/v1/sessions/SESSION_ID/disposition

   • 包含選取的 disposition_code，以及 id 和 full_path，以及任何附註。

4. 處理回應：

   • 200 OK：處置方式已更新。系統會自動更新 CRM 記錄。

   • 發生錯誤時：顯示錯誤訊息，並視情況重試或提報。

客戶關係管理系統行為

使用這個 API 提交處置時，會發生下列情況：

• 系統會在已連結的客戶關係管理系統 (例如 Salesforce、ServiceNow、Zendesk、Dynamics 或 HubSpot) 中建立新的客戶關係管理系統附註。原始記事不會修改。

• 如果是外部儲存空間，系統會以更新後的處置資料覆寫工作階段中繼資料檔案。

限制

HubSpot 通話參與度包含純量 hs_call_disposition 屬性，每次更新處置時都會覆寫 (而非附加) 該屬性。HubSpot 附註會保留完整記錄，但參與度屬性只會反映最新的處置代碼。