Install the chat widget

Before you start

1. In the web app, open Agents, then Domains. Add each host that will load the widget, such as help.example.com. Use *.example.com to allow its subdomains. That pattern doesn’t include example.com itself, so add both if you need both.
2. Open Agents, then Install. Choose how visitors are identified, then create an installation to get your App ID and embed code.

The widget only loads on allowed domains. To test on your machine, add localhost. The port is ignored.

Add the script

Paste this before the closing </body> tag on every page that should show the widget. Replace YOUR_APP_ID with the App ID from the Install page.

<!-- Add before </body> -->
<script>
  window.askneutron = window.askneutron || {};
  window.askneutron.chatAgentSettings = {
    appId: "YOUR_APP_ID",
  };
</script>
<script src="https://chat.askneutron.com/widget.js" defer></script>

You can also set options as data- attributes on the script tag. The loader reads the attributes only when chatAgentSettings has no appId.

<script
  src="https://chat.askneutron.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-position="bottom-left"
  defer
></script>

React apps

No npm package is needed. This component sets the same settings and loads the hosted script once. Render it once near your app root.

import { useEffect } from "react";

export function AskNeutronChatWidget() {
  useEffect(() => {
    // No npm package required. Configure globals + load the hosted widget script.
    window.askneutron = window.askneutron || {};
    window.askneutron.chatAgentSettings = {
      appId: "YOUR_APP_ID",
    };

    const scriptId = "askneutron-chat-widget";
    if (!document.getElementById(scriptId)) {
      const script = document.createElement("script");
      script.id = scriptId;
      script.src = "https://chat.askneutron.com/widget.js";
      script.defer = true;
      document.head.appendChild(script);
    }
  }, []);

  return null;
}

// Render <AskNeutronChatWidget /> once near your app root.

Signed-in users

With the default setup, Neutron verifies each visitor by sending a one-time code to their email. What a person can read follows their verified identity.

If your app already knows who is signed in, pass their details to the widget. Call identify() again whenever the user changes, for example after they log in, log out, or switch accounts.

// Call whenever your app knows the logged-in user (e.g., after login)
window.askneutron?.chatAgent?.identify({
  user: {
    id: "USER_ID",
    email: "user@company.com",
    displayName: "Asha Rao",
  },
});

The user object accepts id, email, displayName, and orgRoles. These details come from the page, so the widget treats them as a hint, for example to show a name. They never decide what someone can read.

Options

Set these in chatAgentSettings, or as attributes on the script tag.

Appearance

Change the rest of the widget’s look in the web app, under Agents, then Playground, and preview it as you go:

• Accent color
• Greeting, such as “What can I help with today?”
• Input placeholder, such as “Ask me anything”
• Theme: Match site, Light, or Dark. Match site turns the widget dark on dark pages and follows a site that switches theme.

JavaScript controls

After the script loads, window.askneutron.chatAgent controls the widget from your page.

const chat = window.askneutron?.chatAgent;

chat?.show();
chat?.hide();
chat?.toggle();
chat?.applyTheme("#6633ff");

If a chat session ends and cannot be renewed, the widget tells your page with a window message:

window.addEventListener("message", (event) => {
  if (event.data?.type === "ask-widget:session-ended") {
    // The chat session cannot continue. Reload to start a new one.
    console.info(event.data.code, event.data.reason);
  }
});

Verify the install

Publish the page, then open the widget from an allowed domain. The Verify installation step on the Install page shows when the widget was first seen. Select Refresh status if it hasn’t updated yet.