Chat widget

The chat widget is a prebuilt browser widget you embed with a <script> tag. You configure it in Studio at Chat → Chat widget and paste the generated snippet on your site; no front-end code required for the basic setup. If you want to identify logged-in customers to the agent or control the widget from your page, the same snippet extends to cover those cases.

Prerequisites

• The agent you want to embed must have the chat channel enabled. See Enable chat on the agent.
• The Chat section must be available in your Studio sidebar. If you don't see it, ask your Stellar contact to enable the chat feature for your tenant.

Configuring the widget

Navigate to Chat → Chat widget. The page has a configurator on the left and a live preview on the right that updates as you change fields. The configurator's first four fields decide how the widget behaves; the rest are visual customizations. Pick what you like and the preview shows the result.

Agent

The agent the widget should talk to. Agents that have the chat channel enabled show a green Chat chip in the dropdown.

Environment

Choose Development, Staging, or Production. Each environment has its own public token, and switching here updates the token embedded in the snippet. Test with Development first, then regenerate the snippet for Production when you're ready to ship.

Language

The widget's built-in UI strings. Two languages are available today: English and Dutch.

Selecting a language applies the preset welcome message, subtitle, and input placeholder for that language. You can still override any of these strings using the appearance fields below.

Entry point

Where to route the visitor when the widget opens. Two options:

• AI (default) — visitors talk to the AI agent. Underlying value: AI.
• Human — visitors are placed straight into your live-chat queue, bypassing the AI. Underlying value: HUMAN.

The underlying value is what ends up in the embed snippet's entryPoint field and matches the SDK's entryPoint option.

Appearance and copy

Primary color — the accent color used for the launcher button, the header bar, and outgoing message bubbles. Accepts any CSS color value; the configurator uses a hex picker.

Widget title — the text shown in the header of the open widget (for example, "Chat with us"). Leaving it blank falls back to the language preset.

Welcome message — the greeting shown on the welcome screen before the first message. Leaving it blank falls back to the language preset for the selected entry point.

Subtitle — a short line shown under the title in the header while the conversation is connected (for example, "Typically replies in a minute"). Leaving it blank hides the subtitle.

Input placeholder — the hint text inside the empty message input (for example, "Type your message…"). Falls back to the language preset when left blank.

Position — which corner the launcher button sits in on the page: bottom-left or bottom-right.

Hide "Powered by Stellar" — switches off the small "Powered by Stellar" credit shown in the widget footer.

Embedding the snippet

Below the configurator, the Embed snippet block shows the generated <script> tag. Two buttons accompany it:

• Test opens a preview tab using the current settings against the real agent. Useful for confirming wiring before touching your site.
• Copy copies the snippet to your clipboard.

Paste the snippet just before the closing </body> of any page where you want the widget to appear:

<script src="https://platform.stellarcs.ai/v1/chat/widget/chat-widget.js"></script>
<script>
  new StellarChat({
    agentId: "agt_abc123",
    token: "ptk_live_xxxxxxxx",
    entryPoint: "AI",
    language: "en",
    primaryColor: "#606BDF",
    title: "Chat with us",
    position: "bottom-right"
  });
</script>

The widget loads asynchronously and mounts itself on the page when ready.

Authenticating users

The widget often runs on pages where you already know who the visitor is, either because they're signed in to your product or because they can identify themselves to you in some other way. You can pass that identity to the agent through widget variables.

Variables are submitted from the visitor's browser, so a determined visitor can change them. The three patterns below describe how to use widget variables for authentication without relying on the values being tamper-proof. Pick the one that matches your setup.

Your visitor is signed in to your app

If your app has already authenticated the visitor (they have a session cookie, an OAuth access token, or an API token your backend issued), pass that token to the widget as a variable, marked sensitive.

<script src="https://platform.stellarcs.ai/v1/chat/widget/chat-widget.js"></script>
<script>
  new StellarChat({
    agentId: "agt_abc123",
    token: "ptk_live_xxxxxxxx",
    variables: {
      auth_token: { value: "<your-user-token>", sensitive: true },
    },
  });
</script>

Marking the token sensitive: true is what makes this pattern safe: the AI never sees the value (it's omitted from the model's context), it's redacted as **REDACTED** in logs and transcripts, and API-call actions can still reference it in templates, where Stellar substitutes the real value at request time, typically as the Authorization header.

Your backend then validates the token the same way it validates any other request from your frontend.

Your visitor isn't signed in — identify them by what they tell you

When the visitor isn't logged in but can provide enough information to identify themselves (account number, last name, date of birth, a one-time code, or whatever your support flow uses), the agent can authenticate them in the conversation: collect the details, then verify them server-side.

Pass any user information your page already has as widget variables:

<script src="https://platform.stellarcs.ai/v1/chat/widget/chat-widget.js"></script>
<script>
  new StellarChat({
    agentId: "agt_abc123",
    token: "ptk_live_xxxxxxxx",
    variables: {
      order_number: { value: "ORD-12345", sensitive: true },
    },
  });
</script>

For details the agent needs to ask for in the conversation (date of birth, postal code, and the like), collect them through a dialogue step and run an API-call action against your backend. If your backend verifies the details, the conversation continues in an authenticated branch of the dialogue.

Signed tokens

If you need a token the agent can verify without calling your backend first (for example, a tamper-proof identifier you generate server-side), Stellar can configure an HMAC-signed variable scheme for your tenant.

Your backend signs a short payload with a shared secret Stellar holds. The widget passes the signed value as a sensitive variable, and the action layer validates the signature before using the data. Contact Stellar to set up the shared secret for your tenant.

Pushing context to the conversation

Once you've picked an authentication pattern, you still need to decide when to push the variables. That depends on when your page actually has the values.

At page load

If your server renders the page knowing who the visitor is, add a data-variables attribute to the snippet you copied from the configurator. Values are JSON-encoded.

<script
  src="https://platform.stellarcs.ai/v1/chat/widget/chat-widget.js"
  data-agent-id="agt_abc123"
  data-token="ptk_live_xxxxxxxx"
  data-variables='{"customer_name":"Alex","plan":"pro"}'
></script>

The widget reads the attributes on load and starts the conversation with those values already set.

After sign-in

If the visitor signs in (or otherwise becomes identifiable) after the page has loaded, take the snippet from the configurator and assign the result of new StellarChat({...}) to a variable so you can call updateVariables on it later. Everything else in the snippet stays the same.

<script src="https://platform.stellarcs.ai/v1/chat/widget/chat-widget.js"></script>
<script>
  const widget = new StellarChat({
    agentId: "agt_abc123",
    token: "ptk_live_xxxxxxxx",
    entryPoint: "AI",
    language: "en",
    primaryColor: "#606BDF",
    position: "bottom-right"
  });

  // Wire this up to your own auth flow.
  onUserSignedIn((user) => {
    widget.updateVariables({
      customer_name: user.name,
      auth_token: { value: user.token, sensitive: true },
    });
  });
</script>

updateVariables works mid-conversation. If the agent has already greeted the visitor by the time sign-in completes, the new variables apply from the next turn onward.

On sign-out

Call reset() on logout. This ends the current conversation, clears the saved conversation ID from localStorage, and starts a fresh one, so the next visitor on the same browser doesn't pick up where the previous one left off.

// Wire this up to your own auth flow.
onUserSignedOut(() => {
  widget.reset();
});

Conversation resumption

The widget stores the active conversationId in localStorage keyed by agent and visitor. When the page reloads, it reconnects to that conversation if it's still active, restoring the message history. If the previous conversation has ended, a new one is created automatically.

When the widget resumes a conversation, any variables you passed in the config are re-pushed via updateVariables so the agent sees the latest values. This means it's safe to update the values on every page load; the agent will pick up the new values without losing the conversation.

Mounting into your own container

By default the widget appends its own container to <body>. To mount it inside a specific element instead, pass container (a CSS selector or HTMLElement):

<script src="https://platform.stellarcs.ai/v1/chat/widget/chat-widget.js"></script>
<script>
  new StellarChat({
    agentId: "agt_abc123",
    token: "ptk_live_xxxxxxxx",
    container: "#chat-mount-point"
  });
</script>

container is programmatic-only; it can't be set via a data attribute.

Methods

Show methods on the StellarChat instance

open()

Open the chat panel programmatically.

widget.open();

close()

Close the chat panel without ending the conversation. The launcher stays on the page.

widget.close();

updateVariables(vars)

Push new or changed variables to the active conversation. Use this when context becomes available after the widget has connected, most commonly after sign-in. Throws if called before the widget has connected.

await widget.updateVariables({
  customer_name: "Alex",
  plan: "pro",
});

reset()

End the current conversation, clear the stored conversationId from localStorage, and start a fresh conversation. Use on logout or to guarantee a clean next session.

await widget.reset();

destroy()

Disconnect and remove the widget from the DOM. The auto-created container element (if any) is also removed.

await widget.destroy();

Configuration

Show the full WidgetConfig reference

Every WidgetConfig field below works both as a field passed to new StellarChat({...}) and as a data-* attribute on the script tag (e.g. primaryColor → data-primary-color). Object- and string-typed values (variables, metadata, strings) are JSON-encoded in the attribute form, e.g. data-variables='{"plan":"pro"}'. The exception is container, which is constructor-only.

Field	Type	Required	Default	Description
agentId	string	Yes	—	The agent the widget connects to.
token	string	Yes	—	Public access token for the agent.
primaryColor	string	No	#606BDF	Accent color for the launcher and header. Any CSS color.
title	string	No	Localized default	Header title shown above the chat.
position	"bottom-right" | "bottom-left"	No	bottom-right	Corner the launcher is anchored to.
language	"en" | "nl"	No	en	Language for built-in UI copy.
hidePoweredBy	boolean	No	false	Hide the "Powered by Stellar" footer.
strings	Partial<WidgetStrings>	No	—	Override individual UI strings (placeholders, status messages, etc.).
entryPoint	"AI" | "HUMAN"	No	AI	Route the conversation to the AI agent or directly into the human queue.
variables	Variables	No	—	Visitor context passed to the agent at conversation start.
metadata	Record<string, string>	No	—	Free-form key/value pairs attached to the conversation record (e.g. page URL, referrer).
container	string | HTMLElement	No	new <div> on <body>	Constructor-only. CSS selector or element to mount the widget into.

When to use the SDK instead

The widget covers most embed scenarios. Use the Text chat SDK when you need to render chat inside your own UI or embed it in a native mobile app. The widget and the SDK are alternative front ends for the same agent.

Next steps

• Enable chat on the agent — turn the channel on before configuring the widget
• Text chat SDK — for custom integrations