传递客户上下文

简述

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

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

适用场景

您的网站或 App 已嵌入 OpenDesk Web SDK，希望访客点击咨询时，客服工作台自动看到：

• 客户昵称、手机、邮箱等资料
• 业务侧预填的 会话摘要（咨询意图、订单号、产品型号等）

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

接入前准备

接口前缀：

{OpenDesk地址}/api/v1/open

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

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

技术特性：

• 租户由 API Key 哈希解析，无需 在请求体中传 tenantId。
• Key 被禁用、删除或轮换后，旧 Key 立即 无法签发 Token。
• 成功调用会更新该 Key 的 最近使用时间。
• 当前 Key 无 scope 细分，启用 Key 亦可调用《知识库 API》等同套 Open API。

整体流程

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

要点：

• contextToken 由 您的服务器 调用 API 生成；PC 嵌入 SDK 场景经 SDK 初始化或 updateContext 传递，不应 硬编码在前端 bundle 中。
• Token 为 JWT，绑定 tenant_id、channel_key、签发所用 api_key_id 与 key_version；渠道或 Key 不匹配时校验失败。
• 默认有效期 1800 秒（30 分钟），可设 300～1800 秒（最短 5 分钟）。

如何使用

第一步：创建并保管 API Key

仅 超级管理员 可操作；普通管理员、客服账号 看不到 此菜单。

1. 登录 管理后台 → 全局设置 → API Key。
2. 点击 新建 API Key，填写名称（如「官网后端」）。
3. 创建成功后 仅展示一次 完整 Key（sk-odk-...），请立即复制到密钥管理系统。
4. 关闭窗口后 无法再次查看 完整 Key；遗失须 轮换 或新建。

日常维护：

列表可查看脱敏 Key、状态、创建时间、最近使用时间。

第二步：获取 Web 渠道 Key

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

第三步：配置后台字段（可选但推荐）

传递自定义内容前，请先在管理后台完成字段定义：

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

接口： 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

方式 A：PC 嵌入 SDK（推荐）

在网页初始化 SDK 时传入 contextToken：

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

Token 由您的 后端下发给前端（如页面渲染时注入、或前端请求自家 BFF 获取），不要 将 API Key 放在前端。

方式 B：H5 / 独立 URL

适用于直接打开聊天页链接的场景。将 Token 拼接到 URL：

{OpenDesk地址}/chat/{channelKey}?contextToken=从接口返回的contextToken

• 访客打开后，系统读取 contextToken 并完成同步，随后 自动从地址栏移除 该参数，降低泄露风险。
• 移动端通过 SDK 打开独立 URL 时，也会按同样方式传递该参数。

会话中更新

若客户信息在会话进行中发生变化：

1. 后端重新调用 POST /open/context-token 获取新 Token；
2. 前端调用 SDK updateContext({ contextToken: '...' }) 更新（详见 Web SDK 接入文档）。

效果： 客服在工作台 客户资料 与 会话纪要 区域看到传入内容。

接口说明

请求参数

customer 系统字段：

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

除系统字段外，可传入已在 用户字段 中配置并 启用 的自定义字段：

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

sessionSummary.fields：

• 字段标识须与 会话纪要 中已配置字段一致。
• 最多 50 个字段。
• customer 与 sessionSummary 各自 JSON 序列化后不超过 16KB。

错误与排查

context-token 专项：

• channelKey 须与当前租户下 Web SDK 渠道一致。
• Token 消费阶段：过期、渠道不匹配、签发 Key 已禁用或轮换 → 须重新签发。

Token 消费阶段（SDK / 服务端）： 完整错误语义以 {OpenDesk地址}/docs 为准。

安全与限制

1. API Key 只保存在服务器；生产与测试使用 不同 Key。
2. 定期 轮换 Key；关注 最近使用时间，异常立即禁用。
3. 所有调用须走 HTTPS。
4. PC 嵌入 场景勿将 Token 长期暴露在可分享的 URL 中；独立 URL 场景系统会在读取后移除地址栏参数，但仍应由后端按需签发短期 Token。

暂不支持通过本接口实现

以下须使用 员工登录态 在管理后台或工作台操作，不能 用 API Key 代替：

• 创建 / 删除 API Key 本身
• 修改渠道、路由、角色、员工等系统配置
• 客服接单、发消息、处理工单等日常作业
• 呼叫中心、报表、监控类能力

与其他功能的关系

• API Key（管理后台）：本接口鉴权凭证；详见《API Key》。
• 渠道管理：提供 channelKey。
• 用户字段 / 会话纪要：customer.fields 与 sessionSummary.fields 的数据来源。
• Web SDK 接入文档：init、updateContext、嵌入与独立 URL 模式。
• 知识库 API：同属 Open API，复用同一套 Key。

需要更多帮助

• 在线接口文档： {OpenDesk地址}/docs — 完整 Schema 与在线试调。
• 字段配置： 传递自定义字段前，请先在管理后台完成 用户字段、会话纪要 配置。
• 后续新增接口以 {OpenDesk地址}/docs 公布为准。

对接示例

电商订单页咨询（PC 嵌入）

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

系统配置： 创建 API Key；配置 Web SDK 渠道；在 用户字段 启用 vip_level，在 会话纪要 启用 order_no、customer_intent。

对接步骤：

1. 用户登录后，后端组装 customer 与 sessionSummary。
2. 调用 POST /open/context-token 获取 contextToken。
3. 页面 OpenDesk.init({ contextToken }) 加载 SDK。
4. 坐席在工作台查看同步结果。

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

H5 会员中心跳转聊天（独立 URL）

角色与目标： App 内 H5 打开独立聊天链接，并带入会员 ID 与等级。

对接步骤：

1. App 服务端调用 POST /open/context-token 签发 Token。
2. 拼接链接：{OpenDesk地址}/chat/{channelKey}?contextToken=... 并在 WebView 中打开。
3. 页面加载后 Token 被消费并从地址栏移除；坐席侧看到会员资料。

接口速查