客户集成总览

新客服项目请先阅读客服接入指南。下文 Bot Widget 示例属于旧接口兼容路径，不代表 Conversation Hub SDK 的权限或签名协议。

Open4X 已从单一 API 网关扩展为一组可以组合使用的 AI、实时客服、消息推送、社交中控和第三方连接能力。本页面向准备接入 Open4X 的客户工程团队，说明新增能力、接入边界和当前可验证状态。

当前状态：staging 可用于技术联调；生产正式启用仍需通过支付、Provider、告警、观察期、SLA、DPA、价格和安全条款验收。staging 的额度和价格不是生产承诺。

新增能力

能力	当前状态	客户可以使用什么	主要接入方式
AI Model Gateway	MVP / staging 可测	OpenAI-compatible Models、Chat、Streaming、Embeddings、模型别名、预算和用量	服务端 API + ai:invoke
Widget 实时客服	staging POC 可测	固定版本 Loader、短期 Session、WebSocket、历史消息、断线补拉、消息幂等	服务端签发 Session + 浏览器 Widget
聚合事件读取	staging POC 可测	按租户读取所有 Widget 会话增量事件、稳定游标、HMAC、空查询不消耗事件额度	Bridge 服务端轮询 /widget/events
Webhook Push	Beta / staging 可测	一次请求推送到多个启用目标、Telegram 和 Generic Webhook、逐目标结果	push:send + target 配置
SocialOps	MVP	统一 Inbox、thread、状态、优先级、负责人、内部备注和回复队列	REST API + Console
Connected Accounts	Beta preparation	加密保存 API Key、Bot Token 和 OAuth 连接，服务复用凭据	Console Connections + OAuth
统一 API Key 与账务	Beta preparation	Scope、alias、来源 IP、每日额度、速率、并发、过期、轮换、撤销和审计	Console + API
异步 Job	MVP / 分服务可用	pending、running、succeeded、failed 等统一状态和回调约定	/v1/jobs + HMAC Callback
TRON 能量租赁	MVP / sandbox	报价、幂等下单、服务商履约、链上验证、退款状态机	/v1/apps/tron

推荐架构

Open4X 负责通信、渠道、模型调用和服务级计费；客户自己的系统继续作为用户、订单、权限、支付和工单的业务主系统。

客户前端 / App
    │
    ├── 客户服务端签发短期 Widget Session
    ├── 客户服务端保存 Open4X API Keys
    └── 客户服务端维护 ticket、outbox 和业务权限
             │
             ├── Widget + WebSocket
             ├── Bot / SocialOps / Webhook Push
             └── AI Model Gateway（可选）
                         │
                  Open4X Gateway
                         │
             Connected Accounts / Provider

Open4X 不应成为客户登录、支付、私密内容权限或资金操作的单点依赖。AI 默认只作为可选能力；关闭 AI 后，Widget 和人工客服流程仍应正常工作。

为了让接入尽量简单，可以直接使用仓库 sdk/ 包，只在客户服务端提供一个 /api/open4x/session 接口。该接口验证当前用户和可选的订单权限，调用 createWidgetSessionForContext，再把短期 Session 返回给前端。不需要把 Open4X API Key 放进浏览器，也不强制客户数据库增加 Open4X 专用表。订单、内容、争议和 普通客服都可以通过 context_type、context_id 关联。

前端可以按技术栈选择：零构建页面使用托管脚本；自定义 JavaScript 使用 mountOpen4XWidget；普通 HTML、Vue、Svelte 使用 <open4x-support-widget>；React 使用 Open4XSupportWidget。它们共用同一套 Session 协议，因此更换前端技术栈不会改变会话、订单关联或渠道路由。

多方场景中，客户自己的业务 ID 放在 external_participant_id，Open4X 返回的 参与者 ID 只作为渠道和消息路由标识。audience_mode: direct 可以实现 A/B、C/B 定向沟通，all 保持最简单的广播方式。以后增加 Telegram、Discord、LINE、Teams 或 WhatsApp 时，不需要改变客户的会话和工单模型。

五步接入流程

1. 创建服务实例

在 Console 创建所需服务，并为每个环境使用不同 alias：

ai-model:qwen122
bot
webhook-push:ops
socialops:support

alias 是客户侧配置的一部分，建议保存到环境变量或服务配置，不要硬编码在多个客户端。

2. 签发最小权限 Key

生产或 staging 都建议按职责拆分 Key：

Key	Scope	用途
Conversation Bridge Key	conversation:read, conversation:write	新会话 SDK、Session 和消息
Conversation 事件管理 Key	conversation:events:write	Webhook 注册/撤销、事件重放
旧 Bot Bridge Key	bot:session:create, bot:events:read, bot:send	兼容 Widget Session、事件同步、人工回复
AI Key	ai:invoke	模型列表、Chat、Streaming、Embeddings
Webhook Key	push:send	Webhook Push fan-out
SocialOps Key	socialops:read, socialops:write	Inbox 读取、事件写入和回复队列

API Key 只能保存在客户服务端或 Worker Secret。浏览器只能拿短期 Widget Session Token，不能拿平台 API Key。

3. 配置来源与额度

每把 Key 可以限制：

• service_aliases：只能调用指定服务；
• allowed_ips：限制固定出口 IP 或 CIDR；
• daily_quota：UTC 日额度；
• rate_limit_per_minute：每分钟请求数；
• concurrency_limit：并发请求数；
• expires_at：自动过期时间。

Key 创建、轮换、撤销、过期和策略拒绝都会写入审计元数据。明文只在创建或轮换时展示一次。

4. 先在 staging 验证

当前 staging 入口：

API:     https://staging-api.open4x.com
Console: https://staging-console.open4x.com
Widget:  https://staging-widget.open4x.com/widget.js

面向客户的 staging 接入必须使用以上正式的 open4x.com 域名。底层的 workers.dev 和 pages.dev 部署地址只作为内部回退地址，不属于对外接入合同。

staging 默认关闭真实 AI、Telegram、Webhook、支付和其他高风险外部副作用。客户可以验证鉴权、请求格式、状态码、幂等、游标、HMAC、账务元数据和故障回退，但不能把 dry-run 当作真实 Provider 投递。

5. 通过生产门禁后再启用 Provider

生产启用需要真实 Provider 账户、Secret、回调、allowlist、支付配置、备份恢复、告警验证、连续观察期和业务/法务签字。没有正式证据清单时，生产发布门禁会阻断。

Widget 实时客服接入

Session

客户服务端使用 Bridge Key 签发短期 Session：

POST /v1/apps/bot/widget/auth
X-API-Key: <bridge-key>
Content-Type: application/json

{
  "external_user_id": "customer-anon-001",
  "user_name": "Alice",
  "ttl_seconds": 1800
}

ttl_seconds 支持 900–3600 秒。external_user_id 应使用客户生成的稳定映射 ID，不要直接放邮箱、钱包地址或其他敏感数据。

浏览器只接收 session_token：

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

实时消息与可靠同步

Widget 支持：

• WebSocket ping/pong 和 connected / new_message 事件；
• 历史消息分页；
• client_message_id 幂等，避免网络重试产生重复消息；
• Session refresh、revoke 和过期关闭码 4001；
• 断线后通过消息接口或事件接口补拉。

服务端 Bridge 不需要为每个会话单独轮询，可以使用租户级聚合接口：

GET /v1/apps/bot/widget/events?cursor=<opaque_cursor>&limit=100
X-API-Key: <bridge-key>

不传 chat_id 时返回该租户所有 Widget 会话的增量事件。事件使用稳定的 (created_at, message_id) 游标，包含 event_id、conversation_id、chat_id、message_id、client_message_id、direction、visibility 和 created_at。

处理顺序应为：

读取事件 → 验证 HMAC → 按 event_id 去重 → 持久化到客户事件 inbox → 保存 next_cursor

staging 事件响应使用：

X-Open4X-Event-Timestamp: <unix_seconds>
X-Open4X-Event-Signature: sha256=<hex>

签名原文是 <timestamp>.<raw_response_body>，算法为 HMAC-SHA256。生产切换前应使用独立事件签名密钥。租户聚合事件额度独立于通用 API 日额度；空 data=[] 不消耗事件日额度，但仍受速率和并发限制。

AI 接入与客服辅助

AI 与基础客服解耦，客户可以选择：

模式	行为
关闭 AI	只使用 Widget、Inbox、人工客服和客户工单
客服辅助	AI 生成分类、摘要和回复建议，仅客服可见
AI 接待	AI 生成公开回复，复杂问题转人工

AI Gateway 支持 OpenAI-compatible 路径：

GET  /v1/apps/ai/qwen122/v1/models
POST /v1/apps/ai/qwen122/v1/chat/completions
POST /v1/apps/ai/qwen122/v1/embeddings

AI 请求建议携带 Idempotency-Key 和 X-Request-ID。响应可以包含预估成本、最终成本和 token 用量，客户可以按租户、用户、服务和请求 ID 做成本归因。

AI 不应直接读取或执行私密内容授权、退款、提现、钱包签名、封禁、结算或其他高风险动作。工具调用和 RAG 权限过滤需要由客户业务系统或后续产品模块负责。

Webhook Push 与 SocialOps

Webhook Push 适合把一条消息 fan-out 到多个已配置目标：

POST /v1/apps/webhook-push/ops/send
X-API-Key: <webhook-key>

每个 target 可以独立启用。全部成功返回 200，部分成功返回 207，全部失败返回 502。Telegram target 需要启用 Telegram Bot Connected Account 并配置 chat ID。

SocialOps 适合需要持续处理消息的客服、运营和开发协作场景：

• 统一 thread、Inbox、状态、优先级和负责人；
• generic webhook、Telegram 和 GitHub 事件归一化；
• 公开回复和内部备注分离；
• 回复先进入 action 队列，再由 provider adapter 投递；
• provider 失败保留审计错误，不静默丢失。

Slack、Discord、Teams、X/Twitter、Meta、Instagram、WhatsApp 和 LINE 需要逐个完成 provider 应用、OAuth、回调验证和出站能力配置，目前不能因为控制台有 provider 选项就视为已生产可用。

租户 Telegram 配置

每个租户需要配置自己的 Telegram Connected Account 和渠道映射。是否已经开通应查询该租户配置和 Provider 验收记录；存在适配器不代表该客户已具备真实收发能力。

Open4X 的 Telegram + SocialOps 代码路径已经支持以下流程，但需要为 客户系统 单独完成 Provider 开通：

1. 在 Telegram 的 BotFather 创建 Bot，并通过安全渠道提供 Bot Token；

2. 在 Console > Connections 创建 active 的 telegram-bot Connected Account；

3. 创建并启用 socialops:support，绑定 Telegram channel、connected_account_id 和目标 chat_id；

4. 创建或更新 Bot Service 后，由 Open4X 自动设置 webhook。staging 的 webhook 地址为：

   https://staging-api.open4x.com/v1/apps/bot/webhook/platform

5. 用户先向 Bot 发起会话，或将 Bot 加入目标群组并授予必要权限；入站消息随后进入 SocialOps thread 和 Inbox。

完成上述配置并开启真实 Provider 后，客户系统 运维可以在 Console > SocialOps 中回复客户，也可以调用：

POST /v1/apps/socialops/support/threads/{thread_id}/replies
X-API-Key: <socialops-key>
Content-Type: application/json

回复先进入 action 队列，投递成功后记录 Telegram message_id；失败会保留审计错误。Bridge Key、AI Key 和 Webhook Push Key 不能替代 Telegram Bot Token，Bot Token 只能保存在加密的 Connected Account 中。

当前 staging 仍默认关闭 Telegram 的真实外部投递，所以配置完成后只能先做 dry-run，不能据此证明客户已经能收到真实 Telegram 回复。要进行真实联调，需要单独配置 客户系统 的 staging Bot、channel、来源和 provider 开关，并完成入站、回复、失败和重试验证。Telegram Bot 也不能主动联系从未启动过 Bot 的任意用户。

第三方授权

Connected Accounts 支持一次配置、多个服务复用：

1. 客户在 Console 的 Connections 中选择 provider；
2. 使用 API Key、Bot Token 或 OAuth 完成授权；
3. Open4X 加密保存凭据，只返回脱敏状态；
4. 服务实例通过 connected_account_id 引用连接；
5. 撤销或停用连接后，后续请求立即停止使用该凭据。

OAuth provider 必须在目标环境配置 Client ID、Client Secret、回调 URL、来源和加密密钥。以 Discord 为例，未配置 DISCORD_CLIENT_ID 时，页面显示“OAuth 未配置”是配置缺失，不是用户重复授权可以解决的问题。

数据、安全与运营边界

• API Key、Bot Token、Provider Key 不进入浏览器、日志、文档或 Git；
• 默认日志保存 request ID、服务、模型、token、状态、延迟和成本，不保存完整 prompt/response；
• 外部 URL 需要 HTTPS 和 SSRF 校验；
• 客户业务系统负责用户权限、订单、支付、工单和私密内容授权；
• 失败调用、超时和 Provider 不可用应由客户 outbox 或工单系统重试和回退；
• 生产前需要确定数据保留、删除、DPA、数据区域、状态页、SLA、维护通知和补偿规则。

相关文档

• API 集成
• AI 大模型网关
• Widget 服务协议
• Webhook Push
• SocialOps 社交中控
• 第三方连接账户
• 企业技术准备度
• 安全和运维
• 计费和账务