Widget Service Protocol

This page documents legacy Bot Widget endpoints. New Conversation Hub integrations should start with the Support Integration Guide. Its dedicated Webhook secret is distinct from this page's polling signature key.

The first-stage integration uses a short-lived server-issued Widget Session. Never expose an Open4X API key in browser code.

Staging

API:    https://staging-api.open4x.com
Widget: https://staging-widget.open4x.com/widget.js
Version: use the loader/runtime identifiers and checksums in your frozen delivery package

Create a session server-side with bot:session:create:

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 is 900–3600 seconds, defaulting to 1800. Pass only the returned session_token to the browser.

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

Messages and reconnect

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

Send a stable client_message_id for idempotency. A replay returns the original message_id. Text is limited to 8,000 Unicode characters, the Widget HTTP route defaults to 15 requests/minute (other /v1/apps/* routes are typically 60 requests/minute), and each chat allows four active WebSocket connections. Reconnects must backfill through /messages or /events. Revoked or expired sessions close with code 4001 and must not reconnect forever.

The server-side bridge should use the tenant-wide aggregate feed GET /v1/apps/bot/widget/events?limit=100&cursor=... instead of polling each chat_id. Non-empty pages consume the independent event_daily_quota; empty pages do not, while the per-minute rate limit still applies. The event allowance is specific to each issued key. Verify its actual policy through the delivery package and Console; production limits require a frozen agreement.

Incremental events

The event feed requires bot:events:read and returns stable event_id, conversation_id, chat_id, message_id, client_message_id, direction, visibility, creation time, and an opaque cursor. Save the cursor only after the event is committed to the the customer inbox. Replaying a cursor is safe.

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

The staging v1 signing input is <timestamp>.<raw_response_body> using HMAC-SHA256 and the current API key as the signing key. Production must switch to a dedicated event secret before the commercial contract is frozen.

The repository file docs/commercial/WIDGET_SERVICE.md is the full contract for retry, CSP/CORS, self-hosting, and boundary details.