Skip to content
open·agent

Guide · Install

Install the OpenAgent widget

The embed is one script tag. The whole install is two steps: allowlist your domain in the dashboard, then paste the snippet. This page covers both, plus platform-specific notes and the three failure modes we see in support.

Sujith Sasidharan· CTO & Technical Architect6 min read

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>
  );
}

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 27 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).

Try it on your own LLM keys from $3/mo.

$36 per site per year billed annually, or $5 per site per month billed monthly. No card on file, just paste your model key and your widget is live.

Get startedSee pricing