外部会话事件

借助外部会话事件功能，您可以使用 Webhook 将来自 CCAI 平台的实时数据流式传输到外部系统。这样一来，您就可以立即了解会话生命周期，以便生成自定义报告、更新 CRM 记录或自动执行互动后工作流程。

外部会话事件提供了一种基于推送的机制，可在聊天或语音通话状态发生变化时通知您的服务器。通过提供 API 端点，CCAI 平台会在发生转换时（例如，通话已连接、客服人员已分配、会话已断开连接）将 JSON 格式的事件数据 POST 到您的基础架构。

配置外部会话事件

如需配置外部会话事件，请按以下步骤操作：

  1. 在 CCAI 平台门户中，依次点击设置 > 开发者设置。 如果您没有看到设置菜单，请点击 菜单。

  2. 在会话数据导出窗格中，点击管理数据导出设置。 系统随即会显示会话数据导出页面。

  3. 前往外部会话事件窗格，然后点击开关将其切换到开启位置。

  4. 执行以下一项或两项操作：

    • 如需配置外部通话会话事件，请执行以下操作：

      1. 选中通话事件 - 发送通话会话事件复选框。

      2. 在 API 端点字段中，输入目标 API 的完整 HTTPS 网址。

      3. 输入用户名和密码。平台使用这些信息进行基本身份验证。

    • 如需配置外部聊天会话事件，请执行以下操作：

      1. 选中聊天事件 - 发送聊天会话事件复选框。

      2. 在 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：生成事件时的纪元时间（以毫秒为单位）。
  • connected_at 和 ends_at：会话时长的 ISO 8601 时间戳。
  • initiator：标识处理状态更改的实体，例如 virtual_agent_15 或 agent_1。
  • dispositions：一个嵌套对象，包含 code、custom_code_id 和任何代理 note。

安全

所有请求都会随附一个标准 Authorization 标头： Authorization: Basic <base64_encoded_credentials>

交付要求

  • 方法： POST
  • Content-Type： application/json
  • 超时：您的服务器应在 5 秒内做出响应。
  • 确认：您的端点必须返回 200 OK 状态代码。 如果收到非 200 代码，平台可能会使用指数退避算法重试。

载荷示例

以下是网络钩子在事件消息中收到的载荷示例。

正在进行的对话（已连接媒体）

{
  "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"
            }
          }
        ]
      }
    }
  ]
}