处置代码 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”：“”）	明确清除现有备注。会话元数据文件将不再包含该备注。CRM 历史记录会保留之前的记录。
已省略 （请求中缺少字段）	使现有备注保持不变。

请勿来电 (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"
  }
}

注意：name 字段由服务器根据指定的 id 和 full_path 值从处置树中解析。为了方便起见，它会在响应中返回。

会话元数据

使用此 API 更新处置时，会发生以下情况：

• 外部存储：系统会重新生成会话元数据文件，并 覆盖现有元数据文件。

• CRM：系统会创建新备注，保留审核跟踪记录。

错误处理

本部分介绍错误处理。

常见状态代码

状态	条件	示例消息
400 Bad Request	缺少必填字段（disposition_code 和 notes 均缺失），或格式无效。	“At least one of disposition_code or notes must be present.”（必须存在 disposition_code 或备注中的至少一个）。
401 Unauthorized	API 令牌无效或缺失。	“Unauthorized”（未经授权）
403 Forbidden	API 用户无权访问指定的会话或租户。	“Forbidden”（禁止）
404 Not Found	找不到会话或会话不存在。	“Session not found.”（找不到会话。）
422 Unprocessable Entity	各种验证失败。请参阅 422 Unprocessable entity scenarios 表。	请参阅 422 Unprocessable entity scenarios 表。

422 Unprocessable entity scenarios

场景	错误消息
通话或聊天会话仍处于活跃状态	“Session has not ended. Disposition can only be updated for completed sessions.”（会话尚未结束。只能为已完成的会话更新处置。）
在会话的树中找不到处置代码 ID	“Disposition code is invalid for this session's queue.”（处置代码对此会话的队列无效。）
提交了 DNC 处置，但该功能未启用	“Do Not Call disposition is not enabled for this tenant.”（此租户未启用请勿来电处置。）
无法解析任何客服人员参与者以进行归因	“Unable to determine agent for disposition attribution.”（无法确定处置归因的客服人员。）

响应示例

以下示例显示了错误响应：

{
  "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 记录会自动更新。

   • 发生错误时：显示错误消息，并根据需要重试或上报。

CRM 行为

使用此 API 提交处置时，会发生以下情况：

• 系统会在连接的 CRM（例如 Salesforce、ServiceNow、Zendesk、Dynamics 或 HubSpot）中创建新的 CRM 备注。原始备注不会被修改。

• 对于外部存储，会话元数据文件会被更新后的处置数据覆盖。

限制

HubSpot 通话互动包含一个标量 hs_call_disposition 属性，该属性会在每次处置更新时被覆盖（而不是附加）。虽然 HubSpot 备注中保留了完整历史记录，但互动属性仅反映最近的处置代码。