传递客户上下文

简述

传递客户上下文 面向 技术对接人员：由您的业务后端携带租户 API Key，调用 OpenDesk Open API 签发短期 contextToken，再交给网页端 Web SDK 使用。OpenDesk 会在访客发起咨询后，将客户资料、自定义用户字段与会话纪要字段同步到客服工作台，无需坐席手工录入。

调用边界： API Key 仅用于 服务端（业务后端、BFF、定时任务等），禁止写入浏览器前端、移动 App 或公开仓库。

适用场景

典型用途： 电商订单页咨询、会员中心售后、SaaS 控制台内嵌客服。

接入前准备

接口前缀：

{OpenDesk地址}/api/v1/open

鉴权 Header（每次请求必填）：

Authorization: Bearer sk-odk-您的密钥
Content-Type: application/json

技术特性：

• 租户由 API Key 哈希解析，无需 在请求体中传 tenantId。
• Key 被禁用、删除或轮换后，旧 Key 立即无法签发 Token。
• 成功调用会更新该 Key 的 最近使用时间，便于在管理后台排查调用方。

整体流程

您的业务后端                         OpenDesk                         网页 Web SDK
     │                                  │                                  │
     │  ① POST /open/context-token       │                                  │
     │     Authorization: Bearer Key     │                                  │
     │ ───────────────────────────────> │                                  │
     │  ② 返回 contextToken + expiresIn  │                                  │
     │ <─────────────────────────────── │                                  │
     │                                  │                                  │
     │  ③ 将 contextToken 交给前端/SDK  │                                  │
     │ ─────────────────────────────────────────────────────────────────> │
     │                                  │  ④ SDK 建连时携带 Token           │
     │                                  │ <─────────────────────────────── │
     │                                  │  ⑤ 校验 Token 并同步客户/纪要     │
     │                                  │     至客服工作台                   │

要点：

• contextToken 由 您的服务器 生成，经 SDK 后台通道 传给 OpenDesk，不会 出现在 URL 查询参数中。
• Token 为 JWT，绑定 tenant_id、channel_key、签发所用 api_key_id 与 key_version；渠道或 Key 不匹配时校验失败。
• 默认有效期 1800 秒（30 分钟），可自定义 300～1800 秒。

如何使用

第一步：创建 API Key

1. 使用 超级管理员 账号登录管理后台。
2. 进入 全局设置 → API Key。
3. 点击 新建 API Key，填写名称（如「官网后端」「会员中心 BFF」）。
4. 创建成功后 仅展示一次 完整 Key（sk-odk-...），请立即复制到密钥管理系统。
5. 关闭弹窗后无法再次查看完整 Key，遗失需 轮换 或新建。

第二步：获取 Web 渠道 Key

1. 进入 管理后台 → 在线客服 → 渠道管理。
2. 打开目标 Web SDK 渠道详情。
3. 复制 渠道 Key（即请求体中的 channelKey）。
4. 确认该渠道已 启用，且允许公开接入（与 Web SDK 嵌入配置一致）。

第三步：后端调用签发接口

接口： POST {OpenDesk地址}/api/v1/open/context-token

请求示例：

curl -X POST "{OpenDesk地址}/api/v1/open/context-token" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "channelKey": "您的Web渠道Key",
    "customer": {
      "externalUserId": "user-10001",
      "nickname": "张三",
      "email": "zhangsan@example.com",
      "phone": "13800138000",
      "fields": {
        "vip_level": "gold"
      }
    },
    "sessionSummary": {
      "fields": {
        "customer_intent": "售后咨询",
        "order_no": "ORD-2026-001"
      }
    },
    "expiresSeconds": 600
  }'

成功响应（HTTP 200）：

{
  "contextToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 600
}

响应字段采用 camelCase（contextToken、expiresIn），与 Web SDK 参数名一致。

第四步：将 Token 交给 Web SDK

在网页初始化 SDK 时传入上一步返回的 contextToken：

OpenDesk.init({
  channelKey: '您的Web渠道Key',
  contextToken: '从上一步接口返回的 contextToken',
  // ... 其他 SDK 配置
});

会话进行中若客户信息变化，可：

1. 后端重新调用 POST /open/context-token 获取新 Token；
2. 前端调用 SDK 的 updateContext({ contextToken: '...' })

接口说明

请求参数

customer 系统字段：

自定义用户字段（customer.fields）

使用前须在 管理后台 → 用户与组织 → 用户字段 中创建并 启用 目标字段，记下 字段标识（如 vip_level）。

"customer": {
  "externalUserId": "user-10001",
  "nickname": "张三",
  "fields": {
    "vip_level": "gold",
    "member_no": "M20260001"
  }
}

sessionSummary.fields：

• 字段标识须与 管理后台 → 在线客服 → 会话纪要 中已配置字段一致。
• 最多 50 个字段。
• customer 与 sessionSummary 各自序列化后不超过 16KB。

错误与排查

Token 消费阶段（SDK / 服务端）：

• Token 过期、渠道不匹配、签发 Key 已被禁用或轮换 → 校验失败，需重新签发。
• 完整错误语义以 {OpenDesk地址}/docs 为准。

安全与限制

1. API Key 只保存在服务器，禁止写入前端 bundle、移动端或 Git 仓库。
2. 生产与测试环境使用 不同 Key；定期 轮换，轮换后旧 Key 立即失效。
3. 所有调用须走 HTTPS。
4. 在管理后台关注 Key 的 最近使用时间，异常立即禁用。
5. 当前 API Key 无细粒度 scope，同一租户下任一启用 Key 均可调用本接口及知识库 Open API。

与其他功能的关系

• API Key（管理后台）：本接口的鉴权凭证，仅超管可创建与管理。
• 渠道管理：提供 channelKey；渠道须与 SDK 嵌入配置一致。
• 用户字段：customer.fields 依赖后台字段定义。
• 会话纪要：sessionSummary.fields 依赖后台纪要字段配置。
• Web SDK 接入文档：描述 init、updateContext 等前端 API。
• 知识库 API：同属 Open API，复用同一套 API Key，见《知识库 API》。

对接示例

电商订单页咨询

角色与目标： 用户在订单详情页点击「联系客服」，坐席需立即看到订单号与会员等级。

系统配置：

1. 管理后台创建 API Key，配置 Web SDK 渠道。
2. 在 用户字段 中启用 vip_level；在 会话纪要 中启用 order_no、customer_intent。

对接步骤：

1. 用户登录后，您的后端根据 userId 组装 customer 与 sessionSummary。
2. 调用 POST /open/context-token 获取 contextToken。
3. 页面加载 Web SDK 时传入 contextToken。
4. 坐席接听后，在工作台 客户资料 与 会话纪要 区域查看同步结果。

场景效果： 访客无需重复报订单号；坐席打开会话即可看到业务上下文。