ClientSphereDocs
Guides

Floating launcher

Install the floating launcher, a support button with a quick-action menu that is separate from the Support Hub.

The floating launcher is a small button pinned to a corner of your site. Click it and a short menu opens — find answers, suggest an improvement, and whatever links you add. For a mobile app, the same launcher ships in the React Native SDK.

It is a different embed from the Support Hub, with its own script, its own settings and its own behaviour. They are easy to confuse because they look similar on the page and accept some of the same attributes.

Which one do you want

Support HubFloating launcher
Scriptchat-widget.jssupport-launcher.js
What it doesA conversation, with a hub landing if you enable oneA button and a short menu of actions
Live chatYesYes, when you turn it on
Creates contactsOn page load, before any interactionOn page load, before any interaction
Creates accountsYes, when a company is givenYes, when a company is given
Configured underCustomer Support → Support HubCustomer Support → Floating Launcher

If you want visitors to talk to you, you want the Support Hub. If you want a tidy entry point to your help content and a way to collect suggestions, without staffing a conversation, the launcher is the lighter option.

They can both be on the same page. They do not talk to each other — see using both.

Install

<script
  src="https://clientsphere.io/embed/support-launcher.js"
  data-company-id="your-workspace-id">
</script>

The launcher needs to know which workspace it belongs to. Either attribute works:

  • data-company-id — your workspace id
  • data-widget-id — a Support Hub widget id, which the server resolves back to the workspace

The second exists so you can reuse the id you already have in a Support Hub tag rather than finding another one. The same value in the two different script tags does two entirely different things, which is the single easiest mistake to make here.

Provide neither and the script logs an error naming both attributes, and stops.

What the menu contains

The pill opens a panel. Its home screen has a knowledge base search box at the top, then one row per configured item, then the most-read articles. Five items are configured by default:

ItemAction
Find answersOpens the knowledge base view: categories, popular articles, search
Send us a messageOpens a form that creates a ticket
Suggest an improvementOpens a feature-request form
Contact usOpens a URL you set
Support pageOpens a URL you set

Set the label, colour, corner and the items themselves under Customer Support → Floating Launcher. Each item does one of:

ActionWhat it does
kb_searchOpens the knowledge base view. Articles are read inside the panel; their HTML is reduced to plain formatting before it is injected into your page
ticketOpens the message form. The ticket is created on the support channel chosen in settings, with the visitor's data-user-* identity prefilled
feedbackOpens the feature-request form
linkOpens the item's url in a new tab. Nothing happens if the url is blank
chatWith Live chat on and no url, opens a conversation inside the panel. With a url it opens that link instead, which is what this action used to mean. See using both

Two of the defaults are link items with an empty url, so they do nothing until you fill them in. kb_search and ticket rows are hidden when the matching switch under Knowledge base and messages is off, or, for tickets, when no support channel exists.

Home, Messages and Help

When a workspace has both a way to write in (live chat or tickets) and a knowledge base, the panel gets a bar of three tabs at the bottom, the way Intercom lays it out.

  • Home keeps the greeting, the conversation card, a search box that jumps into Help, popular articles, and any rows you added yourself (feedback, links). Nothing on Home is a second way to write in.
  • Messages is every thread in one place, conversations and tickets alike, newest first, with Start a conversation (or Continue your conversation while one is open) and Send an email at the top. The unread count on this tab is the same one the pill shows.
  • Help is the knowledge base at full height: search, categories and popular articles, and articles open inside it.

Each tab keeps its own place, so opening an article in Help, switching to Messages and coming back lands on the article. Reopening the panel restores the last tab and screen, except that a reply which arrived while the panel was shut opens it straight onto Messages. A workspace with only one of the two sections keeps the single list it has today; there is no tab bar with one useful tab. The bar takes the launcher's colour from Appearance, like the rest of the panel.

Your tickets, and identity verification

Every launcher with tickets on gets a Your tickets row. What it shows depends on how much the launcher knows about the visitor.

Per browser, with nothing to set up. The launcher gives each browser a long random visitor id and stores it on every ticket raised from there. So a visitor sees the tickets they raised from this browser: the reference, the subject, a status and their own messages. A ticket raised on their phone, or by email, is not there, and the list says so.

Per person, once you vouch for them. An email in a script tag proves nothing, so to show a person's tickets across every device your server signs their email with a secret shared with the workspace, and the page passes the signature:

<script
  src="https://clientsphere.io/embed/support-launcher.js"
  data-company-id="…"
  data-user-email="jide@example.com"
  data-user-hash="3f1c…e9">
</script>

Generate the secret under Customer Support → Floating Launcher → Verified visitor identity. It is shown once. Then, on your server, for each signed-in user:

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

Lower-case and trim the email before signing; contacts are matched the same way. This is the same scheme as Intercom's identity verification, so an existing integration of that carries over with a different secret.

The same signature now covers every write the launcher makes, not only ticket reads: the live chat session, the identify call on page load, the ticket the message form creates, and the suggestion the feature-request form submits. The launcher sends it on each of those as userHash (and on ticket reads as the x-user-hash header). The ticket form attaches it only while the email in the form is still the one you signed; a visitor who edits the address sends no signature for it. It is the same secret and the same hash the Support Hub uses, so one value serves both tags on a page.

A visitor whose email arrives with a matching signature is verified; an unsigned or wrongly signed email is unverified. A missing or wrong signature is never an error. What changes:

  • Verified: today's behaviour. The contact is found or created, blanks on it are filled from data-user-name and data-customer-name, an account is found or created from the company name and linked, and tickets show across every device.
  • Unverified, switch off (the default): the email may still match or create a contact, but it never fills in an existing contact's name or company, never creates an account from the typed company name, and never links the contact to one. Tickets show per browser. Account-Based chat assignment sends the chat to the fallback pool rather than the account owner.
  • Unverified, with Require verified identity on: no contact is looked up or created at all. The chat opens anonymously, the ticket and the suggestion are saved with no contact attached, and the email is kept on the record only as a hint for agents.

Require verified identity is a workspace switch beside the secret, under the same card. It persists across secret rotations. Turn it on only once your app sends the hash, because from that moment every unsigned visitor is anonymous.

Rotating the secret invalidates every signature your app has already produced, so visitors are unverified until your app is redeployed with the new one.

Replying. A customer can reply on a ticket from the panel. The reply lands in your inbox exactly as an emailed reply would, from the same contact, on the same thread, restarting the SLA clock if it was idle and reopening a resolved ticket. Your agents reply the way they always have, by email from the inbox, and that reply appears in the panel the next time the customer opens the ticket.

Replies reach the panel first. When an agent answers a ticket that was raised from the launcher, the reply is pushed to the panel straight away: an open ticket updates in place, and otherwise the pill shows a count, Your tickets shows a badge and the ticket says New reply. The email is sent only if the customer has not looked at the reply within five minutes, and if several replies are waiting by then they go as one email rather than one each. A customer who opens the ticket, or answers from the panel, gets no email for those replies at all. Tickets that arrived by email are not affected: every reply on those is emailed at once, as before.

The panel listens for replies only once the browser has raised a ticket, or the page passes a signed identity, so a visitor who never asks for support opens no socket. A short chime and a flashing tab title announce a reply, and a chat message, that arrives while the panel is shut or the tab is in the background. Add data-notify="off" to the script tag to turn both off.

Screenshots. The message form has Add a screenshot or file, and the ticket composer has a paperclip. A screenshot can also be pasted straight into either message box. Images and PDFs only, 5 MB each, up to five per message. The files arrive in your inbox on the message exactly as emailed attachments do, and the customer sees them on the ticket, images inline. The links the customer holds do not expire; they last as long as the ticket does.

A customer sees three states for a ticket, whatever it is called internally: In progress, Waiting on you (when the ticket is pending their reply), and Resolved. They never see the assignee, the priority, the SLA or internal notes.

Live chat in the panel

Turn on Live chat under Customer Support → Floating Launcher and pick which Support Hub widget the conversation runs on. The panel then leads with a conversation card instead of the message form, answered by your team and, if the widget has it, the AI assistant.

Three things change when it is on, and nothing changes while it is off:

  • A conversation row is added at the top if you never listed one, and the message-form row is renamed to Email us so two rows do not both read "Send us a message". A label you chose yourself is left alone.
  • Socket.IO is fetched only at the moment a visitor opens the conversation, so a page that nobody asks for support on still loads nothing extra.
  • A count appears on the pill when a reply arrives and the panel is shut. There is no push on the web either, so this only works while the tab is open.
  • Past conversations sit behind the icon in the conversation header, closed ones included, and a closed conversation offers a way to start a fresh one. A new conversation can only be started when nothing is still open.

This is the same conversation the Support Hub shows, on the same widget, so history, escalation and the AI assistant behave identically. A visitor who chatted on the hub sees that history here.

Chat adds the Support Hub's own public endpoints under /api/public/support/* to the list below, and a Socket.IO connection. Tickets add GET /tickets, GET /tickets/:id, POST /tickets/:id/replies, POST /tickets/:id/seen and POST /tickets/uploads, scoped by the x-visitor-id, x-user-email and x-user-hash headers, plus a Socket.IO connection for pushed replies once the browser has a ticket.

The panel's data comes from four public endpoints under /api/public/launcher/:companyId: GET /kb (categories and popular articles), GET /kb/categories/:id, GET /kb/articles/:id, and POST /tickets (10 per hour per IP). They return only published, public articles, and a ticket requires a valid email.

Configuration is cached for a minute at the edge, so a change can take up to that long to reach a visitor already on your site.

Identifying the submitter

You can pass who the visitor is:

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

They are recorded on any feature request the visitor submits, and they create CRM records — exactly as the Support Hub does with the same details. Add data-user-hash (see identity verification) to prove the email came from your app; without it the identity is unverified and creates less.

The Send us a message form also uses them: when data-user-email is present the email field is not shown, and when data-user-name is present as well the name field is not shown either. The form says which address the reply will go to instead. Leave the attributes off and the form asks.

What identification creates

When the launcher loads with a verified email address (one that carries a valid data-user-hash):

  • finds the matching contact, or creates one with a source of support_launcher
  • finds or creates an account when a company was given, and links the two. A contact already attached to an account stays on it, whatever company name the form carries this time; otherwise the name is matched ignoring case and surrounding spaces, and the oldest match wins
  • saves the suggestion as a feature request pointing at that contact

With an unverified email the first step still happens unless Require verified identity is on, the second never does, and the suggestion points at whatever contact the first step found. See identity verification.

The address is matched case-insensitively, so Ada@Example.com and ada@example.com are one person rather than two contacts.

This happens on page load, the moment the launcher knows who the visitor is — exactly as the Support Hub does. A visitor your site identifies becomes a contact whether or not they ever open the launcher, so every identified visitor is in your CRM.

Submitting a suggestion resolves the same person again, which by then is a lookup rather than a new record, and is what attaches the suggestion to their contact. Without an email address the suggestion is still saved — it simply has no contact attached.

Using both

Nothing stops you running the launcher and the Support Hub on the same page, and it is a reasonable setup: the launcher for self-service, the widget for conversations.

They are independent, though, and one gap follows from that. A launcher item with the chat action cannot open the Support Hub. It falls back to opening the item's url in a new tab, and does nothing at all when that is blank. To send someone from the launcher into a conversation, point a link item at a page where the Support Hub is embedded.

Appearance

SettingDefault
LabelSupport
Colour#1f2937
Positionbottom-right
Themeauto

data-theme on the script tag takes auto, light or dark and overrides the workspace theme, the same way it does for the Support Hub.

When the launcher does not appear

  • Neither id attribute is set. The script logs an error naming both and stops.
  • The workspace id is wrong. The configuration request returns 404 and nothing renders.

Both fail quietly on the page and report themselves in the browser console.

On this page