Widget Display Options

Released: Loader 1.2.0

Loader 1.2.0 and the matching Widget were deployed to widget.open4x.com on 2026-09-14. Upgrade self-hosted Loaders and SDK source packages together; the SDK is not a public npm release. This version fixes the automatic-init savedToken is not defined error without restoring persisted credentials. Attachment storage and scanning require separate provisioning; showing an upload button does not enable that service.

Use preset: 'floating' for the default launcher, or embedded/modal to hide headers, close buttons and layout controls. Actual inline mounting requires an existing target selector with an explicit height. Modal containers remain owned by the merchant. The Loader is still a single instance per page.

Theme, language and timezone (1.3.0)

The additional theme: 'mint' palette uses a pale gray canvas, white support bubbles, mint-green customer bubbles, rounded message shapes and a white header. Bubble avatars are hidden, while sender labels and timestamps remain. It stays light even on dark systems. Configure it through theme="mint" on the custom element/React component, data-theme="mint" on the script, or Open4XWidget.configure({theme:'mint'}). The default remains auto. No mock banners, sample messages or automatic replies are introduced by the theme.

All three default to auto: theme follows system light/dark mode, locale follows the browser (en, zh-CN, zh-TW; unsupported languages fall back to English), and timeZone follows the browser timezone. Invalid timezones fall back to the browser zone, then UTC. Explicit values override defaults. IANA zones handle daylight saving automatically.

Use custom-element attributes theme="dark" locale="zh-TW" time-zone="Asia/Shanghai", or script attributes data-theme, data-locale, data-time-zone. Script attributes are read at load time; custom-element attributes are reactive.

Open4XWidget.configure({theme: 'dark', locale: 'zh-TW', timeZone: 'America/New_York'});
Open4XWidget.configure({theme: 'auto', locale: 'auto', timeZone: 'auto'});

Runtime configuration keeps the session and messages intact. React exposes the same properties and a ref configure method. Released on 2026-09-16; upgrade self-hosted Loader, Widget and SDK sources together. Relative age is timezone-independent; message tooltips and directory timestamps use the selected timezone. No new date-grouping feature is added. Message content, merchant names and arbitrary provider error strings are not translated.

Reconnection and request budgets

Transient disconnects retry with exponential backoff and jitter, capped at approximately 31 seconds, without a ten-attempt cutoff. Network restoration or returning to the page triggers recovery. Handshake timeouts and missing heartbeat responses also trigger reconnection. Successful reconnection refreshes recent history and merges by message ID; older messages remain available through pagination. Expired/revoked sessions stop reconnecting and require a valid merchant-issued session. Uncertain sends are not automatically resent.

Verified Widget identities receive separate per-minute read/read-receipt (120) and write (30) budgets. Token refresh does not reset the same identity's budget. Unverified requests, including server API keys at the Widget entrypoint, retain a shared IP budget of 30/minute. OPTIONS does not consume this budget. Respect Retry-After on 429; independent API Key quotas still apply.

<div id="order-chat" style="height:560px"></div>
<script src="https://widget.open4x.com/widget.js"
  data-lazy="true" data-preset="embedded" data-target="#order-chat"
  data-show-close="false" data-show-emoji="false"></script>

Call Open4XWidget.init(sessionToken) after obtaining a short-lived token from the authenticated merchant backend. Never place a server Key in browser markup.

Open4XWidget.init(sessionToken, {preset:'embedded',target:'#order-chat',showClose:false});
Open4XWidget.configure({showHeader:true,showUpload:false,showLayoutControls:false});

Flags: showHeader, showClose, showLayoutControls, showUpload, showEmoji, showMessageActions. Script attributes use data-show-header, etc. Script attributes are read only at load time; call configure afterwards. Changes do not reissue sessions or refresh history. Unspecified flags remain unchanged; setting a preset clears previous overrides before applying new ones. target: '' moves the container back to the floating host.

The registered SDK custom element supports corresponding live attributes such as show-close="false", preset="embedded", target="#order-chat". Empty boolean attributes mean true. It also exposes element.configure(options). React supports the camelCase properties and a ref configure method. Use the confirmed SDK delivery, not an assumed public npm package.

Hiding close buttons does not disable the merchant's close() method. Upload progress/errors remain visible. Customer directories retain a back control even with hidden headers. Use an order-specific chat token, not a directory token, when switching conversations should not be offered. These are presentation controls, not backend permissions or new messaging capabilities.