Embed and JavaScript API

Add the chat widget with one script tag, and control it from your page with QuantCX("identify"), "open", "close" and "logout", even before the script has loaded.

The snippet

Add this before </body> on every page that should show the chat. Copy it from the Chat Widget's install snippet in Studio: it already carries your brand's id, and uses your brand's chat domain when you have verified one.

<code><script src="https://app.quantcx.com/embed.js" data-agent-id="YOUR_AGENT_ID" defer></script></code>
AttributeRequiredMeaning
data-agent-idYesThe brand's agent id, a UUID. If it is missing or not a valid id, the script logs a console warning and does nothing.
data-languageNoForce the widget's language, as a two-letter code or a code with region (for example de or pt-br). Anything else is ignored.

The script adds the widget once per page; a second copy of the snippet is ignored.

How it loads

The widget runs in an iframe that is created lazily, so it does not slow your page down. On a top-level page the loader first draws the closed launcher itself (in a shadow root, so your CSS and ours never mix) and creates the iframe on the first of: the visitor pointing at, focusing or clicking the launcher, an open command, or the browser being idle after your page has loaded. Inside a frame, or where the launcher cannot be drawn exactly, the iframe is simply created in idle time.

  • The iframe is only as large as what it shows: the launcher while closed, the chat window while open, and the whole screen on phones (viewports up to 640px wide).
  • It sits at z-index: 2147483000, bottom right or bottom left depending on the widget's position setting.
  • It asks for clipboard-write and microphone (for dictation, when you turn it on).
  • The page only acts on messages that come from the widget's own origin and frame.

Commands

CommandWhat it does
QuantCX("identify", { name, email })Greets the visitor by name and labels their conversation in the inbox. name is cut to 80 characters, email to 254. Unsigned values are shown as Unverified, and are ignored entirely when the brand requires verified identity.
QuantCX("identify", { token })Signed identity: a JWT from your server (at most 4,096 characters). A valid token marks the contact Verified. See Signed identity.
QuantCX("open")Opens the chat window (and creates the iframe if it does not exist yet).
QuantCX("close")Closes the chat window.
QuantCX("logout")Forgets this browser's visitor. Call it when your user signs out, so the next person on the same browser does not see their conversations.

Calling commands before the script loads

The snippet is loaded with defer, so your own code may run first. Define this stub once, before any call, and commands are queued and replayed in order as soon as the script loads:

<code><script> window.QuantCX = window.QuantCX || function () { (window.QuantCX.q = window.QuantCX.q || []).push(arguments); }; QuantCX("identify", { name: "Jane Doe", email: "jane@example.com" }); </script> <script src="https://app.quantcx.com/embed.js" data-agent-id="YOUR_AGENT_ID" defer></script></code>

Commands sent before the widget is ready are held and delivered once it reports ready, so you never need to wait for an event.

Examples

<code>// Open the chat from your own "Contact support" button document.querySelector("#support").addEventListener("click", () => QuantCX("open")); // After your user signs in (token signed on your server) QuantCX("identify", { token: await fetch("/api/quantcx-token").then(r => r.text()) }); // When your user signs out QuantCX("logout");</code>