Unified Widget Session

Scope and layout · Widget 2.3.7 / Loader 1.4.4 · 2026-09-21

Authorization follows merchant → group → customer → personal/order support conversations. Merchant administrators stay within their tenant; support staff and agents use authorized groups; customers access only their own authorized chats. Customer groups override obsolete order tags. Change groups with customer-groups; null means ungrouped, never public. Platform operators do not gain message access.

The unified server adapter accepts role: 'agent' for group-scoped staff, not administrator access. Its customer context creates separate general/order chats and returns an authorized initial-conversation hint. Never-opened authorized support chats also appear; opening can create a binding when exactly one active support recipient exists. Otherwise merchant configuration is required. Revoked bindings, private creator chats and disputes are not restored or broadened. Requires Open4X migration 0056; existing single-chat credentials remain restricted.

Initial Conversation and Layout

Keep authentication in the merchant backend. The same personal grant can show a list or a selected chat:

Open4XWidget.init(session_token, {
  showConversationList: true,
  conversationId: 'conv_authorized_order'
});
Open4XWidget.configure({ showConversationList: false });
Open4XWidget.configure({ conversationId: 'conv_another_authorized_order' });

Loader attributes: data-show-conversation-list, data-conversation-id. Custom-element attributes: show-conversation-list, conversation-id. React uses camelCase. The list defaults to visible; the session's initial conversation is used unless overridden. Without either target the list opens, or the most recent chat if the list is hidden. Unauthorized targets fail without selecting another chat. Native customer-session requests can supply conversation_id, which is checked against membership. This is the Open4X conversation ID, not a business order number. Hiding a list never restricts credentials; keep a single-chat credential for genuinely single-chat-only authorization.

Widget runtime 2.3.6 / Loader 1.4.3 · 2026-09-21

Agent and merchant administrator replies preselect the latest eligible public sender, excluding self, removed participants, system messages and internal notes. Eligible recipients remain active customers or creators in the current conversation. With no history, a sole eligible recipient is preselected; otherwise an explicit choice is required. This never enables automatic broadcast. A partial history page is not treated as the end of the conversation's history.

The recipient area pulses slowly three times after automatic selection; reduced-motion preferences use a static highlight. An untouched automatic selection follows the latest sender until text or an attachment is added. Incoming messages never override manual choices, existing reply drafts or relay targets. If the latest sender changes, the Widget shows both the latest sender and the actual recipients, then requires confirmation before sending. Another change while confirming requires renewed confirmation. Cancelling sends nothing. Internal notes remain private, and customer Widgets still have no recipient picker.

No merchant database, API Key or Session protocol changes are required. Reload the page for the new runtime. The unchanged Loader still logs 1.4.3; check https://widget.open4x.com/version.json for the runtime version. Historical release notes below retain their original behavior.

Console Inbox and SocialOps now consistently parse API timestamps: timezone-less D1 timestamps are UTC and then displayed in the browser's local timezone. Explicit Z and offsets retain their meaning, and Unix seconds and milliseconds are supported. This fixes the eight-hour error in UTC+8 without rewriting stored timestamps or adding a fixed eight-hour adjustment.

Troubleshooting an integration? Copy the customer, agent or merchant administrator checklist. Check the identity/credential contract before changing Session issuance, routing or UI behavior.

Loader 1.4.3 / Widget runtime 2.3.4 · 2026-09-18

Fixes false host-verification errors for agent/administrator Widgets loaded inside inherited-origin srcdoc previews with no referrer. The Loader uses the browser's security origin instead of the about:srcdoc URL origin. Customer theme and button controls also work in this configuration.

Trusted srcdoc hosts retaining an HTTP(S) origin are supported. Actually opaque sandboxes still cannot authorize agent sessions; source/origin checks remain mandatory and credentials are never sent using *. Do not remove sandbox restrictions from untrusted content. Custom iframe integrations must supply the actual origin, not the string null.

Hard-refresh sites using the hosted Loader. If a cached version persists, use https://widget.open4x.com/widget.js?v=1.4.3. Self-hosted installations must update the Loader. No business database, API Key or Session protocol changes are required.

Widget runtime 2.3.4 / Loader 1.4.2 · 2026-09-16

Fixes initialization crashing when a literal "null" parent origin was passed to postMessage. Authorization and UI control messages validate both the origin and source window; credentials are never sent using *. The legacy workbench.html compatibility entry now has the same render-error recovery and Reload action, still mounting the shared Widget.

No-referrer embeds remain supported: the Loader passes a valid parent_origin for customer, agent and administrator frames, as does the SDK. Custom iframe hosts must supply their actual HTTP(S) origin. File URLs, data URLs and opaque sandbox hosts cannot authorize an agent session and show a host-verification error. Do not replace null with *.

This release includes the 2.3.3 compact conversation list, customer/order details, unread badges and conversation-switch loading states. Console-issued administrator messages display “管理员”; audit records retain the actual actor. Refresh the Console to load the hosted runtime. Self-hosted installations must update both Loader and page assets. No key, Session protocol or database changes are required.

Widget runtime 2.3.2 · 2026-09-16

The Console and embedded Widget share the same behavior: the sole eligible recipient is preselected. When explicit selection is required, the recipient choices open immediately with a Required label instead of staying behind a collapsed control. They can be collapsed after selection and reopen when cleared. A conversation with no eligible recipients shows an explicit empty state and cannot send public replies.

Internal notes are labeled "Internal note (not sent externally)" and require no recipients. The creator role is labeled Creator, replacing the business-specific Trader label. Permissions and explicit delivery boundaries are unchanged; no automatic broadcast is added. Refresh the Console to load the update. The Loader stays at 1.4.1; the runtime is 2.3.2.

Widget 1.4.1 fixes · 2026-09-16

Agent and administrator replies preselect the only eligible recipient (an active customer or creator). Multiple recipients and relaying still require explicit selection; there is no automatic broadcast. Customer Widgets have no recipient picker: the merchant server defines their destinations in the Session. Internal notes remain separate from public replies.

Fixes cover restricted browser storage, restoring a minimized window without header controls, and null message bodies. Reinitialization reloads the correct Widget identity. Load timeouts offer Retry; rendering failures offer Reload, with no role escalation or alternate workbench fallback.

Hard-refresh sites using the hosted https://widget.open4x.com/widget.js once to clear any older entrypoint cache. Self-hosted installations must update both the Loader and Widget page assets to 1.4.1. No key, Session protocol or database changes are required. If only the outer header remains visible, provide the page URL and sanitized errors, never tokens or full iframe URLs.

Widget 1.4.0 unified interface (released · 2026-09-16)

Role-based redirection to the separate Conversation Hub workbench is removed. Customers, agents and merchant administrators use the same Widget entry, shared message bubbles, composer and conversation-list layout. Legacy workbench.html URLs only mount this same Widget for compatibility.

Administrator actions are in the conversation's top-right menu. Observe first, then join explicitly. Recipients, relaying and internal notes expand on demand. Theme, language, time zone and visibility settings use Open4XWidget.configure(). Embed only widget.js; no additional Conversation Hub or Workbench UI is required.

Server APIs, wbs_ credentials and authorization boundaries stay compatible. No database or key changes are needed. Merchants already using server SDK 2026-09-16-admin.1 do not need another server SDK update; self-hosted Loaders need version 1.4.0.

Customers Do Not Choose Recipients

Personal support and individual order conversations send directly in the current chat. Customers do not see recipient selection, internal notes or agent relaying actions. Multiple server-configured recipients do not require a customer selection and do not imply broadcasting to every participant.

For the unified Session adapter, the merchant server resolves the authenticated customer as role: 'customer'. A widget_customer_session opens the customer's conversation list; a conversation-specific widget_session opens an individual chat. The server determines recipients when issuing the Session. Browser messages do not select recipients, sender roles or visibility.

If a customer sees agent recipient controls, check whether the merchant Session endpoint issued an agent/administrator wbs_ credential by mistake. Do not merely hide the controls with CSS or grant staff permissions to a customer. URL display hints are not authorization. Missing or revoked recipients require a merchant-side configuration fix and a newly issued Session, not a choice by the customer.

Console conversation entry

After signing in, open Conversations. This page embeds the production Widget root directly. The separate Console Conversation Hub interface is removed; it does not redirect to workbench.html. The Widget follows the Console theme and shows the current merchant's conversations.

The server verifies the current account/team's conversation:read, conversation:write and conversation:supervise permissions before issuing a dedicated 15-minute Widget credential. The Console renews it automatically, never stores it or places it in a URL, and it cannot access Console, billing or API Key administration. No manual key setup is needed. Platform operations roles do not grant access to other merchants' data.

Membership, permissions and merchant ownership are checked on every Widget request. Workspace changes, logout or failed authorization clear the embedded session. Viewing does not join a conversation: join explicitly before replying. See the release notes above for recipient defaults; relaying requires an explicit destination. Notes, relaying, assignment and supervision use the same Widget.

This entry is for the Open4X merchant Console only. Third-party websites should keep using the server-side Session adapter below, not the Console-specific issuing endpoint.

Administrator observation and intervention

Released with server SDK version 2026-09-16-admin.1. Previous frozen packages remain unchanged and do not acquire supervision privileges automatically.

The updated server adapter issues scope: 'tenant', mode: 'agent', supervise: true when a trusted resolver returns role: 'admin'. These fields can also be supplied to POST /v1/conversations/workbench-sessions. The server Bridge Key needs conversation:read, conversation:write, and conversation:supervise. Never trust a browser-supplied role or expose the key.

The Widget shows the merchant conversation list, including personal, order and ungrouped conversations. Opening a conversation does not create a support participant. Join explicitly before replying or writing notes; revoked participants cannot rejoin themselves. Joined administrators can take and release control using revision-checked supervision. A conflict returns 409; refresh before retrying. Releasing control keeps the participant joined. manage: true separately enables status and assignment operations. Transferring control to an external account is not available in this Widget.

Inbox filters include exact external_user_id, group_tag, and ungrouped=true (the latter two are mutually exclusive), existing exact context_id, order/conversation search q, and status. All filters only narrow the issuing merchant's authorization; Open4X platform operators receive no cross-merchant chat access.

Use GET/POST /v1/conversations/{id}/supervision and GET /v1/conversations/{id}/audit. Workbench POST actions are observe, join, takeover, and release; takeover/release require the latest revision. Audit actors use external:<external_user_id>.

Existing tokens and older frozen SDK downloads do not gain supervision automatically. Update the server adapter and issue a fresh Session. The frontend Loader integration stays unchanged; no new database migration is required.

Released · 2026-09-16

Automatic Loader routing is deployed to the production Widget. Merchants must update their server SDK and Session endpoint; self-hosted Loaders must also be upgraded. No database migration is required.

Download the server-only source files into the same directory: Session adapter, API client, SHA-256 manifest. This source bundle also includes optional browser, React and custom-element adapters; it is not a public npm release. The agent role aliases group-scoped support staff, not administrators.

Keep the merchant frontend's existing Session URL and Open4XWidget.init(session_token) call. Implement that endpoint using createOpen4XUnifiedSessionHandler from the local server SDK. This is a merchant-side adapter, not a new Open4X HTTP endpoint.

The trusted resolve(request) callback verifies login, CSRF/origin policy, rate limits and order ownership, then returns one of:

{ role: 'customer', external_user_id: 'site:user-1', context: {
  order_id: 'ORDER-1', recipient_external_ids: ['site:support-1'], group_tag: 'sales'
} }
{ role: 'support_agent', external_user_id: 'site:support-1', group_tags: ['sales'] }
{ role: 'admin', external_user_id: 'site:admin-1', manage: true }

Never spread browser input into this result. Staff groups cannot be empty; no tenant-wide fallback occurs. Admin is limited to the API key's merchant tenant. manage defaults to false. Use read/write/supervise Bridge scopes for this adapter's routed conversation creation and staff queues; keep the key server-side. Set widgetOrigin to the iframe origin, default https://widget.open4x.com.

Resolve the authorized entry point as well as the logged-in account. An administrator using personal consultation still receives role: 'customer'; do not apply an account's highest role to every entry. Entry authorization is merchant-owned logic, not a browser-controlled role or an additional Open4X SDK method. The adapter's role field is not a generic HTTP Session parameter.

For customers, supplying context ensures one general conversation and, when order_id is present, one independent order conversation. Stable hashed tuple IDs prevent duplicates; the final credential is always a directory token. Omit context to list existing chats only. Orders are prepared on demand, not imported from the merchant database automatically. context.external_conversation_id can reuse an existing current-context mapping; legacy general-chat mappings require explicit migration or the existing preparation flow.

The Loader recognizes workbench tokens and opens the staff UI automatically, passing tokens only through origin-checked messaging. Personal and single-chat credentials remain compatible. Upgrading an old/self-hosted Loader is required even if the embedding code stays unchanged.

Staff TTL defaults to 900 seconds; customer TTL defaults to 1800 seconds. Keep the merchant's renewal flow. The Loader dispatches open4x-session-required when staff authentication expires; integrations without renewal may still need a small lifecycle change. Destroy and reinitialize on account switches. Never escalate roles on failures.

Verify order isolation, idempotent preparation, forged-role rejection, group/tenant boundaries, account-switch cleanup and no read acknowledgements while the staff window is closed. Existing platform endpoints and OpenAPI remain unchanged.