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. 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:

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:

<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.

What identification creates

The moment the widget loads with data-user-email, the workspace either finds the matching contact or creates one:

You send	What happens in the CRM
`data-user-email`	A contact is found by email, or created with `source` of `chat_widget`
`data-user-name`	Split into first and last name. Without it, the part of the email before the `@` becomes the first name
`data-user-company`	An account is found by name, or created with `status` of `prospect`, and linked to the contact

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.

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

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
`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
`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:

<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.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.

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.