Install the OpenAgent widget

Step 1: allowlist your domain first

Before you paste anything, open Dashboard → Sites and add the hostname of the site you're installing on (for example www.yoursite.com). The widget's session endpoint rejects requests from origins that aren't on this list, so a snippet on a non-allowlisted domain will not boot.

The symptom is easy to miss: the page loads normally and the chat button simply never appears. There is no visible error. If you open the browser console you'll find a warning naming your origin and pointing you back to Dashboard → Sites. Add the hostname, reload the page, and the button shows up.

Step 2: paste the snippet

The embed is a single script tag loading https://app.openagent.in/openagent.js. It needs three values: your workspace's tenantSlug (shown under Settings → Install widget), the API URL and the WebSocket URL. You can pass them either way.

Option A: a config object on window. Place both tags right before </body>:

<script>
  window.OPENAGENT_CONFIG = {
    tenantSlug: "your-workspace",
    apiUrl: "https://app.openagent.in",
    wsUrl: "wss://app.openagent.in"
  };
</script>
<script async src="https://app.openagent.in/openagent.js"></script>

Option B: data attributes on the script tag itself. One tag, no inline script, which some CMS plugins and CSP setups prefer:

<script
  async
  src="https://app.openagent.in/openagent.js"
  data-tenant="your-workspace"
  data-api-url="https://app.openagent.in"
  data-ws-url="wss://app.openagent.in"
></script>

Both forms are equivalent. If you use both at once, values on window.OPENAGENT_CONFIG win over the data attributes.

Platform notes

Plain HTML: paste the snippet right before the closing </body> tag of every page you want the widget on (or in a shared footer include).

WordPress: use the official plugin, no theme edits: download openagent-chat-wordpress.zip, upload it under Plugins → Add New → Upload Plugin, activate, then enter your workspace slug in Settings → OpenAgent Chat. The plugin prints the same script tag in the footer and survives theme updates. Prefer not to install a plugin? Paste the snippet into a header/footer tool (WPCode, "Insert Headers and Footers") or your theme's footer.php.

Shopify: add it as a theme snippet so it survives theme edits. In Online Store → Themes → Edit code, create a snippet named openagent-chat, paste in this file and set your workspace slug at the top, then add {% render 'openagent-chat' %} to theme.liquid just before </body>. The snippet also passes the logged-in customer id to the widget so conversations link to the right shopper. Quick alternative: paste the plain script snippet directly into theme.liquid.

Webflow: go to Project Settings → Custom Code and paste the snippet into the "Footer Code" box. Publish the site; custom code does not run in the Webflow designer preview.

Next.js / React: use next/script with strategy="afterInteractive" and the data-attribute form, typically in your root layout:

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://app.openagent.in/openagent.js"
          strategy="afterInteractive"
          data-tenant="your-workspace"
          data-api-url="https://app.openagent.in"
          data-ws-url="wss://app.openagent.in"
        />
      </body>
    </html>
  );
}

Chat as your signed-in users

If your product has its own logins (and maybe a mobile app on the OpenAgent API), the widget can chat as the signed-in user instead of an anonymous visitor. The user then sees one thread with their history on the web and in your app, and your team sees who they are. Your backend asks OpenAgent for a short-lived user token with your API key; the page passes the widget a function that fetches it:

<script src="https://app.openagent.in/openagent.js"></script>
<script>
  OpenAgent.init({
    apiUrl: "https://app.openagent.in",
    getToken: () =>
      fetch("/my-backend/openagent-token")
        .then((r) => r.json())
        .then((r) => r.token),
  });
</script>

• Giving getToken (or token) is what switches the widget to this mode. No tenantSlug: the workspace comes from the token.
• The widget calls getToken again before the token expires and whenever OpenAgent refuses it, so keep that endpoint behind your own login. Your API key never reaches the browser.
• The domain allowlist from step 1 applies to anonymous chat only; a user token works on any page of yours.
• Call OpenAgent.shutdown() when the user signs out of your app, then OpenAgent.init() again for the next user.

The token endpoint, renewal and error details are in the public API documentation that comes with your API key.

How the widget behaves on your page

• No CSS collisions. The widget renders inside a Shadow DOM, so its styles cannot leak into your site and your site's styles cannot break the widget.
• Lazy by design. The script loads asynchronously and the widget boots after your page's first paint. It never blocks your content.
• Small. The loader is about 31 KB gzipped.

Troubleshooting

The widget never appears. Two usual causes. First, the origin isn't allowlisted: check Dashboard → Sites for the exact hostname the page is served from (with or without www matters). Second, a wrong tenantSlug: compare the value in your snippet against Settings → Install widget. In both cases the browser console has a warning explaining which one it is.

Mixed content. The widget is served over HTTPS, so the page embedding it must be HTTPS too. Browsers block the script on plain-HTTP pages.

Content Security Policy. If your site sets a CSP, allow the widget's host in two directives: script-src needs app.openagent.in, and connect-src needs both https://app.openagent.in and wss://app.openagent.in (the second one is the live WebSocket connection).