What the SupportHub widget is
A button in the corner of your site that opens a panel with the chat and, when you have content for them, knowledge base articles and news.
The widget is a single external JavaScript file that you add to your site. Once loaded, it adds the button and the tabbed panel to the page by itself and connects to our API. No iframes, and no backend on your side.
What the widget is made of
Button and panel
A button in the bottom right corner, with a chat icon and a label by default. The panel is 400×640 on a computer and full screen on a phone (up to 640 px); there, the floating button is hidden while the panel is open, and the panel is closed with the X in its header. You can set the color, the button text and icon, and the logo and its shape.
Tabs
Home · Messages · Help · News · App. Help and News are visible only if they’re on in the builder and have content: published public articles and announcements for customers. App is your page from the Mini App section: visible when the tab is on and its address is set.
WebSocket
Connects once the visitor has a conversation. It delivers operator replies, notices about conversation events (taken, transferred, snoozed, closed: the same ones that stay in the history) and the “read” mark.
Visitor ID
The visitor ID (vs_*) is stored in five places: a cookie, localStorage, sessionStorage, IndexedDB and an older shared localStorage key. If the browser clears some of them, the visitor still gets back to their conversation.
How it’s configured
All settings live in a single config, cfg, which you edit in SettingsWidget Builder (/settings/widget-builder). On a wide screen, the list of sections is on the left, the settings in the middle and a live preview on the right; on a narrow screen, the Preview button opens the preview.
The sections: Brand, Welcome, Tabs, Forms & Topics, Conversation, Hours & Avail., System Messages, Email Bridge, Advanced (custom CSS, notification sound, cookie domain), Pinned Banner, Reply Keyboards, Mini App, Away/Greeting, Icon Pack, Emoji Pack, Privacy.
Sections with a hammer icon are marked as in development: they have no settings yet. Some fields in the working sections don’t have any effect yet either; the pages for those sections say which.
Changes are saved to a draft automatically. To make them visible to visitors, press Publish in the top bar; Discard resets the draft to the published version.
Where it runs
Supported browsers
The bundle is built with esbuild for target: es2018, so it needs a modern browser; IE11 isn’t supported.
Loading and caching
The bundle (/widget-bundle) loads asynchronously and doesn’t block page rendering; the response is gzipped. The server usually puts the published config right at the start of the bundle, so there’s no separate request for /config; if that fails, the widget requests the config itself.
The browser caches the bundle together with the config for 5 minutes (Cache-Control: public, max-age=300, stale-while-revalidate=86400). So published changes and widget updates don’t reach visitors instantly: usually within a few minutes, sometimes only on the page load after that.
Cross-domain
The widget works on any domain: the project ID is passed in the ?ws= parameter of the script URL, and the backend’s CORS allows any origin (*). To accept messages only from your own sites, list the domains in the allowed-domains field of the Privacy section in the Widget Builder and publish. After that, sending messages, replies, files and visitor data from other domains is rejected with 403. An empty list allows any domain.
Cross-subdomain
If your site spans several subdomains (example.com + app.example.com) and you want a visitor to keep one conversation, set the cookie domain with a leading dot (.example.com) in Widget BuilderAdvancedCookie domain (optional) or with the data-cookie-domain=".example.com" attribute right on the tag; the attribute takes precedence over the config. Without it, the cookie is tied to a single host, and the visitor gets a different ID on each subdomain. The browser won’t accept too broad a domain (.com, .co.uk). More in the developer reference.