Widget Service 协议

本页介绍旧 Bot Widget 兼容接口。新项目请从客服接入指南开始；Conversation Webhook 的独立 Secret 与本页轮询签名密钥不同。所有方式均使用服务端签发的短期 Session，不在浏览器暴露 API Key。

Staging

text

API:    https://staging-api.open4x.com
Widget: https://staging-widget.open4x.com/widget.js
版本:   以冻结交付包的 Loader/Runtime 版本和校验值为准

服务端签发：

bash

curl -X POST "$OPEN4X_BASE/v1/apps/bot/widget/auth" \
  -H "X-API-Key: $OPEN4X_BRIDGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"external_user_id":"knv-anon-001","user_name":"Alice","ttl_seconds":1800}'

ttl_seconds 允许 900–3600 秒，默认 1800 秒。API Key 只能放 Header；浏览器只接收响应里的 session_token。

html

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

消息与重连

text

GET  /v1/apps/bot/widget/messages
POST /v1/apps/bot/widget/send
GET  /v1/apps/bot/widget/ws?token=<session_token>
GET  /v1/apps/bot/widget/events?cursor=<cursor>&limit=100

发送时携带稳定的 client_message_id；重复请求返回原 message_id，不会重复写入。单条文本最多 8,000 字符，Widget HTTP 路由默认限流为 15 次/分钟（其他 /v1/apps/* 路由通常为 60 次/分钟），同一 chat 最多 4 个 WebSocket 连接。

服务端 Bridge 应使用租户级聚合事件接口 GET /v1/apps/bot/widget/events?limit=100&cursor=...，无需按 chat_id 轮询。Bridge Key 的事件读取额度独立于通用 API daily quota；非空事件页计入 event_daily_quota，空事件页不计入，但仍受每分钟限流保护。事件额度以实际签发 Key 的配置和客户交付包为准，不是所有租户固定享有同一额度；生产限额需单独冻结。

WebSocket 断线后必须通过 /messages 或 /events 补齐历史。会话撤销或到期时以关闭码 4001 关闭，客户端不得无限重连。

事件增量读取

事件接口要求 bot:events:read，返回 event_id、conversation_id、chat_id、message_id、client_message_id、direction、visibility、created_at 和不透明 next_cursor。处理成功并写入客户事件 inbox 后再保存游标；重复读取游标是安全的。

响应签名头：

text

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

签名原文为 <timestamp>.<raw_response_body>，算法为 HMAC-SHA256。staging v1 暂以当前 API Key 作为签名密钥；生产冻结前切换到专用事件密钥。

更多字段、重试、CSP/CORS 和责任边界以仓库中的 docs/commercial/WIDGET_SERVICE.md 为准。

Widget Service 协议 ​

Staging ​

消息与重连 ​

事件增量读取 ​

Widget Service 协议

Staging

消息与重连

事件增量读取