公开 API

Call Trace API 文档

从自有系统提交通话录音，立即获得 202 响应，并通过 webhook 获取最终转写与评估结果。

创建 API 密钥

打开「管理 > 集成」，创建带有 analysis:write 范围的密钥。

提交文件 URL

向 POST /api/v1/analyses 发送 HTTPS fileUrl。API 将返回 202 Accepted。

接收结果

订阅 analysis.completed 和 analysis.failed 以获取最终评估。

检查 secret

将 X-CallTrace-Secret 与创建 endpoint 时保存的 webhook secret 进行比较。

API 密钥

在管理面板中创建令牌

仅管理员可创建集成 API 密钥。密钥具有权限范围，可过期、可撤销，且与员工会话独立。

01
打开集成
以管理员身份登录，打开「管理 > 集成 > API Keys」。
02
命名密钥
使用能标识外部系统、环境和负责人的名称。
03
选择权限范围
仅选择该系统所需的权限。大多数上传集成需要 analysis:write 和 analysis:read。
04
设置有效期
为临时访问选择过期日期，或为长期服务集成设为永久有效。
05
立即复制
完整的 ct_live_ 令牌仅显示一次。关闭面板后，仅前缀仍可见。
ct_live_••••••••

令牌格式

ct_live_8Lk3...full-secret-value

将完整令牌存储在外部系统的密钥管理器中。Call Trace 仅存储哈希，创建后只显示前缀。

身份验证

使用带权限范围的集成密钥

集成 API 密钥与员工会话分离。在 Authorization 头中发送密钥，并仅授予系统所需的权限范围。

请求头

Authorization: Bearer ct_live_...
Content-Type: application/json

权限范围

analysis:write 创建分析。

analysis:read 读取状态与结果。

webhooks:write 管理 webhook 设置。

权限

各权限范围的作用

权限范围可叠加。从支持集成的最小集合开始，仅在特定端点需要时再添加。

范围

用途

说明

analysis:write

创建新分析

POST /api/v1/analyses 必需。允许外部系统提交 fileUrl 并将分析加入队列。

analysis:read

读取分析状态与结果

GET /api/v1/analyses 和 GET /api/v1/analyses/{analysisId} 必需。用于轮询与对账。

calls:read

读取通话级数据

允许访问通过集成安全端点暴露的通话元数据。若集成仅发送文件，请勿授予。

storage:write

写入源文件

保留给需要直接存储上传流程的集成。fileUrl 集成通常不需要。

webhooks:read

读取 webhook 配置与历史

允许列出 webhook 端点与投递尝试，用于支持或监控工具。

webhooks:write

管理 webhooks

允许创建或更新 webhook 端点。应保留在 admin/服务密钥上，而非普通分析提交密钥。

推荐最小配置

标准流程中，创建一个同时具有 analysis:write 和 analysis:read 的令牌。Webhook 由管理员在 UI 中配置，外部发送方通常不需要 webhooks:write。

令牌有效期

过期、永久访问与轮换

每个 API 密钥都有独立的生命周期。令牌可永久有效、自动过期或由管理员手动撤销。

永久令牌

expiresAt 为空。令牌保持有效直至管理员撤销。仅用于有轮换流程的可信后端间集成。

过期令牌

expiresAt 已设置。该日期之后 API 返回 401，不再接受新请求。适用于测试、外包或临时访问。

已撤销令牌

管理员撤销密钥时立即设置 revokedAt。撤销即时生效且不可恢复；请创建新密钥。

轮换

创建新密钥，部署到外部系统，确认 last used 已更新，然后撤销旧密钥。这可避免停机。

API 参考

创建分析

请求保存源文件并启动后台处理。客户端不应在此请求中等待转写或评估完成。

创建分析

返回 202 Accepted 并将处理加入队列。

POST/api/v1/analyses

请求

POST /api/v1/analyses
Authorization: Bearer ct_live_...
Content-Type: application/json

{
  "fileUrl": "https://example.com/calls/call-123.mp3",
  "agentId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "queueId": "7a7bf5cc-5e34-4f4g-b98f-96g3g9433ed2",
  "externalId": "crm-call-123",
  "idempotencyKey": "crm-call-123",
  "metadata": {
    "customerId": "cust_42",
    "source": "crm"
  }
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "status": "queued",
  "externalId": "crm-call-123"
}

字段

类型

是否必填

说明

fileUrl

string

必填

待分析音频文件的 HTTPS URL。最大 20 MB。

fileName

string

可选

Call Trace 中显示的名称。省略时使用 fileUrl 路径的最后一段。

agentId

uuid

必填

关联的坐席。必须存在于您的公司中。

queueId

uuid

必填

用于评估的脚本队列。必须有激活的脚本版本。

language

string

可选

转写语言。省略时默认为 auto。

externalId

string

可选

您的 CRM、工单或电话系统标识符。

idempotencyKey

string

可选

对系统重试进行去重。

metadata

object

可选

在状态与 webhook payload 中返回的小型 JSON 对象。

文件 URL 要求

fileUrl 必须使用 HTTPS。私有、localhost 及内网 IP 段会被拒绝，包括重定向到私有网络的情况。文件最大 20 MB。处理前会经超时与 content-type 检查后下载。

API 参考

读取状态与结果

当系统需要对账状态或在错过 webhook 投递后恢复时，使用此端点。

获取分析

返回最新任务状态及可用结果字段。

GET/api/v1/analyses/{analysisId}

{
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "status": "completed",
  "externalId": "crm-call-123",
  "call": {
    "durationSeconds": 184,
    "agentId": "agent-uuid",
    "queueId": "queue-uuid"
  },
  "evaluation": {
    "score": 82,
    "summary": "The agent followed the script and resolved the main request.",
    "emotion": {
      "label": "neutral",
      "score": 55,
      "comment": "The caller stayed calm throughout the conversation."
    },
    "criteria": [
      { "name": "Greeting", "score": 10, "maxScore": 10 },
      { "name": "Need discovery", "score": 18, "maxScore": 20 }
    ]
  },
  "transcript": {
    "language": "en",
    "segments": [
      { "speaker": "agent", "text": "Good afternoon, how can I help?" }
    ]
  },
  "metadata": {
    "customerId": "cust_42"
  },
  "error": null
}

queued

请求已接受，等待处理。

processing

文件正在下载、转写并评估。

completed

评估、转写与通话摘要已可用。

failed

重试后处理失败。详情在 error 中返回。

API 参考

列出分析

按 status、externalId、agent、queue 或日期范围搜索。用于后台对账与支持工具。

列出分析

返回集成公司的分页分析列表。

GET/api/v1/analyses

GET /api/v1/analyses?status=completed&externalId=crm-call-123
Authorization: Bearer ct_live_...

Webhooks

Webhook payload

在「管理 > 集成」中配置 webhook 端点。Payload 包含在自有系统中存储评估结果所需的信息。

analysis.createdanalysis.completedanalysis.failed

{
  "deliveryId": "whd_01jz8n0f8ck2bk0smq7h2x1t0r",
  "event": "analysis.completed",
  "occurredAt": "2026-06-19T12:00:00.000Z",
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "externalId": "crm-call-123",
  "call": {
    "status": "completed",
    "durationSeconds": 184,
    "recordingUrl": "https://storage.example.com/audio/call-123.mp3"
  },
  "evaluation": {
    "score": 82,
    "summary": "The agent followed the script and resolved the main request.",
    "emotion": {
      "label": "neutral",
      "score": 55,
      "comment": "The caller stayed calm throughout the conversation."
    },
    "criteria": [
      { "name": "Greeting", "score": 10, "maxScore": 10 }
    ]
  },
  "transcript": {
    "language": "en",
    "segments": [
      { "speaker": "agent", "text": "Good afternoon, how can I help?" }
    ]
  },
  "metadata": {
    "customerId": "cust_42"
  },
  "error": null
}

默认不包含脚本文本。使用 deliveryId 去重，存储状态转换时使用 analysisId 与 event。

Webhooks

投递与重试

Call Trace 记录每次投递尝试，并对失败投递重试，避免超时或客户临时故障导致结果丢失。

成功

任何 2xx 响应均标记投递为已完成。

重试策略

首次尝试加 3 次退避重试，例如 10 秒、1 分钟和 5 分钟。

历史

每次尝试记录状态、响应码、错误信息、时间戳及 payload 快照。

Webhooks

Webhook secret

每个 webhook endpoint 都有一个 secret。Call Trace 在每次投递中发送它，以便您拒绝来自未知来源的请求。

为什么要检查 secret

Webhook URL 可从公网访问。将 X-CallTrace-Secret 请求头与创建 endpoint 时保存的 secret 进行比较。若不匹配，返回 401 并忽略 payload。

每次投递包含什么

POST /your/webhook-handler

X-CallTrace-Secret: whsec_8Lk3...your-endpoint-secret

X-CallTrace-Delivery: whd_01jz8n0f8ck2bk0smq7h2x1t0r

X-CallTrace-Event: analysis.completed

X-CallTrace-Timestamp: 2026-06-19T12:00:00.000Z

{ "event": "analysis.completed", "analysisId": "6f6af4bb-..." }

X-CallTrace-Secret

Endpoint secret。在服务器上与 CALL_TRACE_WEBHOOK_SECRET 进行比较。

X-CallTrace-Delivery

唯一投递 ID。用于忽略同一事件的重复 retry。

X-CallTrace-Event

事件类型，例如 analysis.completed。

X-CallTrace-Timestamp

Call Trace 发送请求的时间。便于日志与支持。

如何验证

从请求头读取 X-CallTrace-Secret，并与创建 webhook 时在「管理 > 集成」中一次性显示的 secret 比较。将 secret 保存在环境变量中，不匹配时在处理 JSON 前拒绝请求。

Node.js 示例

const secret = request.headers.get("x-calltrace-secret");

if (secret !== process.env.CALL_TRACE_WEBHOOK_SECRET) {
  return new Response("Unauthorized", { status: 401 });
}

const payload = await request.json();

示例

用您的语言创建分析

所有示例使用同一稳定端点，并期望 API 密钥位于 CALL_TRACE_API_KEY。

const response = await fetch("https://your-domain.com/api/v1/analyses", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CALL_TRACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    fileUrl: "https://example.com/calls/call-123.mp3",
    fileName: "call-123.mp3",
    language: "auto",
    externalId: "crm-call-123",
    idempotencyKey: "crm-call-123"
  })
});

const analysis = await response.json();
console.log(analysis.analysisId);

错误

错误处理

使用 idempotency key 进行安全重试。验证错误同步返回。处理错误通过状态端点及 analysis.failed webhook 返回。

400

JSON 无效、缺少 fileUrl、不支持的 content type 或 metadata 无效。

401

API 密钥缺失、已过期、已撤销或格式错误。

403

API 密钥不包含所需权限范围。

409

同一 idempotency key 已用于其他 payload。

422

文件 URL 被阻止、为私有、非 HTTPS、过大或不可达。

500

临时服务器错误。请使用相同 idempotency key 重试。

Call Trace API 文档

创建 API 密钥

提交文件 URL

接收结果

检查 secret

在管理面板中创建令牌

打开集成

命名密钥

选择权限范围

设置有效期

立即复制

令牌格式

使用带权限范围的集成密钥

请求头

权限范围

各权限范围的作用

过期、永久访问与轮换

永久令牌

过期令牌

已撤销令牌

轮换

创建分析

创建分析

读取状态与结果

获取分析

列出分析

列出分析

Webhook payload

投递与重试

成功

重试策略

历史

Webhook secret

为什么要检查 secret

用您的语言创建分析

错误处理