ClientSphereDocs
Guides

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:

<script
  src="https://clientsphere.io/embed/chat-widget.js"
  data-widget-id="your-widget-id">
</script>

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:

ModeWhat a visitor sees
HubA landing grid of cards — search the help desk, get in touch, suggest an improvement — with chat one click away
Chat-onlyThe 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 actionWhat it does
chatOpens the conversation view
kb_searchOpens a knowledge base search overlay
email_usOpens a form that raises a ticket by email
feedbackOpens a form for a feature or improvement suggestion
linkOpens 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:

<script
  src="https://clientsphere.io/embed/chat-widget.js"
  data-widget-id="your-widget-id"
  data-user-email="jane@acme.com"
  data-user-name="Jane Doe"
  data-user-company="Acme Corp">
</script>

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:

<script
  src="https://clientsphere.io/embed/chat-widget.js"
  data-widget-id="your-widget-id"
  data-user-email="jane@acme.com"
  data-user-hash="3f1c…e9"
  data-user-name="Jane Doe">
</script>

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:

import { createHmac } from "node:crypto";
 
const userHash = createHmac("sha256", process.env.LAUNCHER_IDENTITY_SECRET)
  .update(user.email.trim().toLowerCase())
  .digest("hex");

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 sendVerifiedUnverified, switch off (the default)Unverified, switch on
data-user-emailA contact is found by email, or created with source of chat_widgetFound or created the same wayNo 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-nameSplit 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 nameUsed only on a contact created by this visit; an existing contact's name is never touchedShown as the visitor's display name only
data-user-companyAn account is found by name, or created with status of prospect, and linked to the contactIgnored: no account is found, created or linkedIgnored

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-company creates 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

AttributeRequiredWhat it does
data-widget-idYesWhich widget to load. Missing, and the script logs an error and stops
data-user-emailNoIdentifies the visitor. Creates or reuses a contact, subject to verification
data-user-hashNoHMAC-SHA256 of the email with the workspace's identity secret. Makes the identity verified
data-user-nameNoVisitor's display name, split into first and last
data-user-companyNoCreates or reuses an account and links the contact to it. Verified visitors only
data-user-idNoYour own id for the user, stored with the session
data-user-avatar-urlNoAvatar shown beside the visitor's messages
data-customer-idNoYour own id for the customer, stored with the session
data-customer-nameNoFallback display name. data-user-name wins when both are set
data-themeNoauto, 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:

<script>
  (function () {
    var s = document.createElement('script');
    s.src = 'https://clientsphere.io/embed/chat-widget.js';
    s.setAttribute('data-widget-id', 'your-widget-id');
    s.setAttribute('data-user-email', 'jane@acme.com');
    s.setAttribute('data-user-hash', userHashFromYourServer);
    s.async = true;
    document.head.appendChild(s);
  })();
</script>

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:

window.chatWidgetDestroy();

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.

On this page