Support Hub
Install the ClientSphere Support Hub on your site, identify visitors, and understand what it writes to your CRM.
The Support Hub is a single <script> tag. For a mobile app, which has no
page to put a script tag on, use the React Native SDK
instead; it talks to the same widget.
The Support Hub is a single <script> tag. It has no dependencies, no build
step, and no npm package — it renders itself into the page and talks to your
workspace directly.
You configure all of it under Customer Support → Support Hub. It is not the same thing as the floating launcher, which is a separate embed with its own script — that page compares the two if you are not sure which you want.
The script is still named chat-widget.js, which predates the hub. It is the
same file whichever landing mode you choose.
Install
Paste this before </body> on any page you want the widget on:
That is the minimum. data-widget-id is the only required attribute — without
it the script logs an error and stops.
Find the widget id in your workspace under Customer Support → Support Hub, where the Install section also offers a ready-made snippet to copy.
The script must be loaded from your ClientSphere origin. The widget works out
which workspace to talk to from its own src, so pointing the tag at a copy
you host yourself will not work.
Two modes
The same embed renders one of two ways, decided by a workspace setting rather than by anything on the script tag:
| Mode | What a visitor sees |
|---|---|
| Hub | A landing grid of cards — search the help desk, get in touch, suggest an improvement — with chat one click away |
| Chat-only | The conversation directly, with no landing |
Hub is the recommended mode and chat-only is kept for workspaces that predate it. A workspace that has never configured the hub falls back to chat-only, so switching is a deliberate step.
Set it under Customer Support → Support Hub, along with the title, subtitle, banner colour, and the cards themselves. Each card has a title, description, icon and button label, and does one of:
| Card action | What it does |
|---|---|
chat | Opens the conversation view |
kb_search | Opens a knowledge base search overlay |
email_us | Opens a form that raises a ticket by email |
feedback | Opens a form for a feature or improvement suggestion |
link | Opens the card's target URL in a new tab |
With no cards configured, hub mode seeds three: help desk search, get in touch, and suggest an improvement.
Because the setting is workspace-level, it applies to every widget in the workspace at once — there is no per-widget mode and no embed attribute that overrides it. Everything else on this page works identically in both modes, identification included.
Identifying the visitor
If your site already knows who is signed in, tell the widget. Conversations then arrive attached to a real person instead of an anonymous visitor:
Identifying a visitor writes to your CRM on page load — before they open the widget, click anything, or send a message. Read what identification creates before you add these attributes to a high-traffic page.
There is no built-in form that asks a visitor for their email. Identification happens only through these attributes, so a visitor you do not identify stays anonymous for the whole conversation.
Proving the email is real
data-user-email is an attribute on a page, and anyone with the developer
tools open can change it. Sign it on your server and pass the signature as
data-user-hash, and the workspace knows the address came from your app:
The hash is HMAC-SHA256 of the lower-cased, trimmed email, hex encoded, keyed with the workspace's identity secret. Generate the secret under Customer Support → Floating Launcher → Verified visitor identity (it is one secret for the Support Hub, the floating launcher, tickets and identification), and on your server:
A visitor whose email carries a matching hash is verified. One whose email
is unsigned, or signed with the wrong secret, is unverified. Neither is an
error: the widget loads and the conversation works either way. The difference
is what the workspace does with the address, below. The hash covers only
data-user-email; it is not sent when a visitor types an address into the
widget's own email gate, so that address is always unverified.
Rotating the secret invalidates every hash your app has already produced, so every visitor is unverified until your app is redeployed with the new one.
What identification creates
The moment the widget loads with data-user-email, the workspace either finds
the matching contact or creates one. How far it goes depends on whether the
email is verified and on the workspace's Require verified identity switch,
which sits next to the secret:
| You send | Verified | Unverified, switch off (the default) | Unverified, switch on |
|---|---|---|---|
data-user-email | A contact is found by email, or created with source of chat_widget | Found or created the same way | No contact is looked up or created. The email stays on the conversation as a hint for agents, and the inbox marks it Unverified |
data-user-name | Split into first and last name and used to fill blanks on the contact. Without it, the part of the email before the @ becomes the first name | Used only on a contact created by this visit; an existing contact's name is never touched | Shown as the visitor's display name only |
data-user-company | An account is found by name, or created with status of prospect, and linked to the contact | Ignored: no account is found, created or linked | Ignored |
For a contact that already exists, only blank fields are filled in — an existing first name, last name or company is never overwritten by what the widget sends — and an unverified identity fills nothing at all. In short: a stranger typing someone else's address into a page can, at most, open a conversation that lands on that contact (switch off) or on no contact at all (switch on); they can never rename a contact or move it to another account.
Chat assignment follows the same rule. On a channel set to Account-Based, a web conversation is sent to the account owner only when the visitor is verified; an unverified visitor's chat goes to the fallback pool, even when the switch is off and a contact was linked.
Every conversation opened before signing existed reads as unverified.
Two consequences worth planning for:
- Every identified visitor becomes a contact, whether or not they ever chat. On a page many signed-in users load, that is a lot of contacts.
data-user-companycreates accounts from free text. Two spellings of the same company name produce two accounts, because the match is on the exact name.
If either is a problem, leave the attribute off. The widget works fine without identification, and you can attach the conversation to a person later.
If the CRM write fails, the widget still works — the session is created either way, and the failure is deliberately swallowed so a CRM problem cannot stop someone reaching you. Nothing surfaces in the page.
Test and live data
Which side of the test/live divide a conversation lands on is decided by the widget, not the embed. A widget created in sandbox writes sandbox contacts and conversations; a live widget writes production data. There is no attribute that overrides this.
So use a sandbox widget on staging and a live widget in production, and give
each environment its own data-widget-id.
Every attribute
| Attribute | Required | What it does |
|---|---|---|
data-widget-id | Yes | Which widget to load. Missing, and the script logs an error and stops |
data-user-email | No | Identifies the visitor. Creates or reuses a contact, subject to verification |
data-user-hash | No | HMAC-SHA256 of the email with the workspace's identity secret. Makes the identity verified |
data-user-name | No | Visitor's display name, split into first and last |
data-user-company | No | Creates or reuses an account and links the contact to it. Verified visitors only |
data-user-id | No | Your own id for the user, stored with the session |
data-user-avatar-url | No | Avatar shown beside the visitor's messages |
data-customer-id | No | Your own id for the customer, stored with the session |
data-customer-name | No | Fallback display name. data-user-name wins when both are set |
data-theme | No | auto, light or dark. Overrides the widget's configured theme |
Loading it yourself
If you inject the script rather than writing it into the HTML — a single-page app, or a tag manager — set the attributes on the element before you append it:
Only one widget loads per page. A second script tag is ignored, with a warning in the console, so a tag manager firing twice is harmless.
To remove the widget — on sign-out, say — call:
That tears down the widget and releases the guard, so a later script tag can load it again with different attributes. It is the supported way to switch from an anonymous visitor to an identified one without a page reload.
When the widget does not appear
- The widget is inactive. An inactive widget returns 404 for its configuration and the script stops. Nothing renders and no session is created, so no contact is created either.
- The id is wrong. Same outcome, same 404.
- The tag has no
data-widget-id. The script logs an error naming the missing attribute.
All three fail quietly on the page and report themselves in the browser console, so check there first.
Managing widgets over the API
Widgets can also be created and configured programmatically, rather than in the
workspace. The API exposes the usual set under /api/v1/widgets — list, fetch,
create, update and delete — taking the same appearance and behaviour settings
the workspace exposes, and returning the widget id you embed.
They are documented in the reference: List widgets, Get widget, Create widget, Update widget and Delete widget. They manage the widget record; everything on this page is about the embed itself, which is the part your site interacts with.
Note that two stored settings, requireEmail and collectVisitorInfo, are not
currently read by the embed. They can be set and returned over the API, but the
shipped widget does not act on them — identification happens only through the
attributes above.