Widget Service 协议

Knoveria 第一阶段使用服务端签发的短期 Widget Session，不在浏览器暴露 API Key。

Staging

text

API:    https://open4x-gateway-staging.29498587.workers.dev
Widget: https://open4x-widget-staging.pages.dev/widget.js
版本:   loader 1.1.0 / runtime 2.3.0

服务端签发：

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://open4x-widget-staging.pages.dev/widget.js"
  data-token="SERVER_ISSUED_SESSION_TOKEN"
  data-gateway-url="https://open4x-gateway-staging.29498587.workers.dev">
</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，空事件页不计入，但仍受每分钟限流保护。当前 staging Bridge Key 的事件额度为每日 10,000 个非空事件页，实际生产额度以签署的商业合同为准。

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

事件增量读取

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

响应签名头：

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

消息与重连

事件增量读取