客服接入指南

第一次接入的商户请先阅读从注册到第一次在线聊天，按步骤完成账号、专用 Key、网站 Session 接口、组件和接待验收。本文供开发人员查阅协议和扩展能力；下方 staging 示例不能与生产凭据混用。

适用于订单咨询、作者咨询和平台客服。新项目使用 Conversation Hub；旧 Bot Widget 接口继续作为兼容接入方式，不能混用权限、会话或签名密钥。

1. 快速接入

当前交付面向 staging POC，真实 Telegram、生产价格与 SLA 需要单独验收。以下是目标入口，不是实时可用性声明：

配置	Staging
API	`https://staging-api.open4x.com`
Console	`https://staging-console.open4x.com`
Widget 页面	`https://staging-widget.open4x.com`
Loader	`https://staging-widget.open4x.com/widget.js`

先确认上述域名解析及 HTTPS 正常，再通过服务端 GET /v1/conversations/credentials/status 检查 Key 状态、scope 和实际配额。域名未就绪时先处理 DNS/Pages 绑定，不将测试地址替换成生产地址。

最小闭环：服务端验证用户和订单权限 → 创建会话及参与者 → 签发 Session → 用户打开 Widget → 客服回复 → 用户查询历史和恢复连接。AI 默认关闭。

2. 用户端组件

浏览器只接收短期令牌。零构建页面可以使用托管 Loader：

html

<script
  src="https://staging-widget.open4x.com/widget.js"
  data-token="SERVER_ISSUED_SESSION_TOKEN"
  data-widget-url="https://staging-widget.open4x.com"
  data-gateway-url="https://staging-api.open4x.com">
</script>

令牌占位符必须由服务端安全填入。不要把 API Key 放入页面。Loader URL 可更新，不能仅凭文件名认为它是不可变版本；固定版本和校验值以客户交付包为准。

SDK 源码版本为 0.1.0。从冻结交付包取得 sdk/，保存版本和校验值，再安装到使用 TypeScript 构建工具的项目：

bash

npm install ./vendor/open4x-conversation-sdk

这里的路径指交付包的 SDK 目录，不代表公共 npm 包已经发布。包直接导出 TS/TSX，需要编译；普通 HTML 不能直接导入源码。React 组件要求 React 18 或以上。

tsx

import { Open4XSupportWidget } from '@open4x/conversation-sdk/react';

export function OrderSupport({ orderId }: { orderId: string }) {
  return <Open4XSupportWidget
    sessionUrl="/api/open4x/session"
    contextType="order"
    contextId={orderId}
    conversationType="order_support"
    scriptUrl="https://staging-widget.open4x.com/widget.js"
    widgetUrl="https://staging-widget.open4x.com"
    gatewayUrl="https://staging-api.open4x.com"
  />;
}

原生 JS 使用 mountOpen4XWidget，Vue/Svelte 可使用 <open4x-support-widget>，同样显式配置三个 staging 地址。它们封装现有 Widget，不是已经交付了所有角色专属工作台。

3. 作者端

作者身份和订单权限由客户服务端确定。Telegram 接入顺序：创建会话与作者参与者 → 创建一次性绑定 → 作者打开 Deep Link → 消费 telegram.identity.started → 使用事件返回的 Chat ID 绑定渠道及参与者 → 创建 Assignment。

作者不能自行传入其他作者的参与者 ID。解绑后必须停止业务投递。网页作者工作台可基于 API 开发；当前 React Widget 包装器不能直接视为完整作者工作台 SDK。

4. 客服工作台

托管工作台入口为 Console 的 /dashboard/conversations，支持会话列表、消息、状态和回复范围。也可以由客户后台经服务端调用 Inbox、消息和分配接口。独立可嵌入的完整客服工作台组件尚不能作为现有交付承诺。

托管 Console 的租户账号与客户自己的客服身份体系不是同一套授权。不要把租户管理 Key 交给作者或浏览器。内部备注使用 sender_role: internal_note 和 visibility: internal；客户自己的事件消费者也必须过滤内部消息。

5. 服务端鉴权

用途	最小 Scope
Conversation 查询、事件读取、凭据状态	`conversation:read`
Conversation、参与者、Session、消息写入	`conversation:write`
注册/撤销 Webhook、事件重放	`conversation:events:write`
旧 Bot Widget Session / 事件 / 回复	`bot:session:create` / `bot:events:read` / `bot:send`
可选 AI	独立 Key：`ai:invoke`

服务端使用 Authorization: Bearer 传递 Bridge Key。浏览器提交的订单 ID 只是请求参数，必须再次验证所有权和访问权限；发送者身份、接收人和角色不能直接信任前端输入。自有 Session 接口还要遵循客户应用的跨站请求防护策略。

Session TTL 为 900–3600 秒。最小接入不要求新增 Open4X 专用数据库表，仍需要一个受保护的服务端 Session 接口。需要工单同步、事件去重和故障补偿时，必须有持久化存储，可复用现有数据库或队列。

6. 多方订单会话

外部订单 ID 放入 context_id，稳定业务会话 ID 放入 external_conversation_id。A 为用户、B 为客服、C 为作者；默认 all 是广播，不等于 A/B 和 C/B 隔离。

私聊必须执行：

创建或查询参与者，按外部用户 ID、角色和 active 状态匹配。
找不到任一必要参与者时返回错误，不继续签发令牌。
给 A 签发 Session 时，明确传入 A 的 participant_id 和 B 的 recipient_participant_ids。
服务端回复使用 audience_mode: direct 和目标参与者 ID；客服转述使用 relay、目标 ID 和 relay_from_message_id。

createWidgetSessionForContext 只组合请求，不会自动解析参与者或构造私聊权限。私聊应先创建会话并验证参与者，再调用 createWidgetSession。完整示例见交付包 sdk/README.md。

7. Webhook 与故障恢复

协议	签名密钥	原文
Conversation 出站 Webhook	注册时的独立 Secret	时间戳 + `.` + 原始请求体
旧 Widget 事件轮询	当前 Bridge API Key（staging 协议）	时间戳 + `.` + 原始响应体

两者都使用 HMAC-SHA256，但不能交换密钥。Conversation 使用 X-Open4X-Event-Timestamp 和 X-Open4X-Event-Signature: sha256=<hex>；SDK 默认时间窗口 300 秒。先验签，再解析并按 event_id 去重。

接收端应在同一事务中记录事件去重标记和业务处理结果，或可靠入队后再返回 2xx。向 Open4X 发出的业务操作使用本地 outbox；接收到的事件使用 inbox/去重记录。仅在持久化成功后推进增量游标。重复事件成功确认，不重复新增消息。

单次回调超时 10 秒，总共最多 8 次尝试（首次加 7 次重试）。重试最短等待为 30、60、120、240、480、960、1920 秒，定时扫描可能延后。失败进入 dead_letter；重放保持原事件 ID。详细接口见会话协议。

Open4X 不可用时保留普通工单入口；补发保持稳定 client_message_id，同键不同内容的 409 应人工排查而非无限重试。额度读取实际 Key 配置，不默认所有客户都有相同免费额度。

8. 上线验收

API、Console、Widget 自定义域名和 HTTPS 可用，前端连接同一环境。
真实用户鉴权、Session 到期/撤销、断线补拉均通过。
A/B、C/B 隔离，错误作者拒绝访问，内部备注不出现在用户端。
重复消息、重复事件、失败补偿及故障工单回退通过。
AI 关闭时完整人工闭环正常。
真实 Telegram 按租户开通，实际发送/回复/解绑通过；dry_run 不能算送达。
附件双向传递、生产价格、限额、保留政策、DPA 和 SLA 各自完成验收。

以上清单是验收要求，不是已经通过的声明。生产参数以该客户冻结交付包和合同为准。接口 Schema 见 OpenAPI。

客服接入指南 ​

1. 快速接入 ​

2. 用户端组件 ​

3. 作者端 ​

4. 客服工作台 ​

5. 服务端鉴权 ​

6. 多方订单会话 ​

7. Webhook 与故障恢复 ​

8. 上线验收 ​