Installing the Widget

The NovixAgent AI widget is a single <script> tag. On each page that carries it, a chat bubble appears in the corner, and visitors can talk to your AI agent — no build step, no dependencies, no code to write beyond pasting one line.

Installing it is a three-step loop: copy the snippet from your dashboard, paste it into your site's HTML, and verify the bubble appears. This guide covers the three steps, plus optional tweaks, platform-specific instructions, and troubleshooting.

Before you start

The embed snippet unlocks once your website has an active plan. Until then, the code block in your dashboard shows a locked panel — activate a plan to reveal it. See Billing & plans.

You'll also want your knowledge base to be indexing or ready before you go live, so the agent has something to answer with — but you don't have to wait. The widget works the moment it's installed, and gets smarter as your content finishes indexing (see Adding Content).

Step 1 — Get your snippet

Find your snippet in Dashboard → Workspaces → (your website) → Website Integration Code. Click Copy Code to put it on your clipboard. It looks like this:

<script
  id="novixagent-ai-script"
  src="https://api.novixagent.ai/novixagent-ai.js"
  data-user-id="YOUR-WEBSITE-ID"
  defer
></script>

Copy it as shown and leave data-user-id unchanged. Each website you add has its own ID, and it's what ties the widget to your configuration, knowledge base, and plan. The defer attribute makes the script run after your page has been parsed, so it does not hold up rendering.

Appearance, greeting, voice and position are configured in the dashboard, so the tag needs no more than this (see Customization below). A few optional attributes can override settings for one embed — see Optional attributes.

Step 2 — Paste it into your site

Add the snippet once, just before the closing </body> tag, on the pages where you want the bubble to appear. A site-wide footer, layout template or header/footer injector adds it to your pages in one step.

WordPress

Use a header/footer plugin (e.g. Insert Headers and Footers or WPCode) and paste into the footer area. Or paste into your active theme's footer.php before </body>.

Shopify

Admin → Online Store → Themes → Edit code → theme.liquid. Paste before </body>. Save.

Webflow

Project settings → Custom code → Footer code. Paste, save, republish.

Wix / Squarespace / GoDaddy / etc.

Each has a "Custom HTML", "Embed code", or "Code injection" block. Paste the snippet there. Refer to your platform's docs for "embed third-party scripts."

Static HTML / custom site

Just paste before </body>. That's it.

Step 3 — Verify it works

1. Open your site in a fresh browser tab (an incognito window is best — it dodges your browser's cache).
2. Look for the chat bubble (bottom-right corner by default).
3. Click it, type a question, hit Enter.

If you don't see the bubble:

• Check the browser DevTools Console for errors.
• Confirm the snippet is actually on the page: View Source (or DevTools → Elements) and search for novixagent.
• Check that your data-user-id is the one the dashboard shows. An empty or missing ID logs data-user-id is required in the console; a wrong one logs no message of its own; in both cases no bubble appears.
• Confirm your website has an active plan. The bubble only shows for a valid, active website.
• If your site has a strict Content Security Policy (CSP), see the troubleshooting section below — you'll need to allow our domains.

Optional attributes (advanced)

You rarely need these — the defaults are set in your dashboard, where changes go live without re-pasting the snippet. But the loader reads a few data-* attributes off the script tag if you want to override behaviour per embed:

Attribute	What it does
data-user-id	Required. Your website ID — copy it from the dashboard.
data-position	bottom-right (default) or bottom-left. Overrides the dashboard position for this embed only.
data-allow-microphone="false"	Opt out of the microphone permission on this site, even if your site has voice input or voice calls. Useful for a privacy-sensitive deployment. There is no "true" value — see Voice and the microphone below.
data-proactive="false"	Opt out of proactive chat invitations on this site. The launcher is unchanged and an auto-open you set in the dashboard still happens; no proactive invitation is shown, and the two browser-storage entries that cap invitation frequency are not written on your domain. There is no "true" value — you enable proactive rules in the dashboard, not in the tag.
data-launcher-text	Custom text label on the launcher bubble.
data-bubble-size	Override the launcher bubble size.
data-launcher-aria-label	Accessible name for the launcher button (e.g. for a localized site). Defaults to "Open AI chat".
data-device-signal	Declares what we may use a device signal for on your site. Two values are recognised: "audience-measurement" and "off". Leave it off and you get the default. See Visitor counting and data-device-signal below — this one has a real effect on your analytics.

If you're not sure, leave them off and use the dashboard settings instead. The one exception is data-device-signal: read the next section before deciding, because its default quietly flattens two of your analytics numbers.

Visitor counting and data-device-signal

The widget is part of your site, so telling your visitors apart is a disclosure your privacy policy has to carry, not ours. We therefore don't assert it on your behalf — you declare it.

By default (attribute absent) we recognise a returning browser only to enforce rate limits, which is the narrow, strictly-necessary basis that doesn't need consent. Measurement is not covered by it, so it is denied unless you say otherwise. The cost is concrete and worth knowing before you look at your dashboard:

• Unique visitors will equal your session count, and
• returning visitors will read zero —

because without a durable identifier a visit is not matched to an earlier one. This is expected: the numbers reflect only what we're allowed to know.

If you have a basis for counting visitors — normally the same basis your existing consent tool already manages — declare it:

<script
  id="novixagent-ai-script"
  src="https://api.novixagent.ai/novixagent-ai.js"
  data-user-id="YOUR-WEBSITE-ID"
  data-device-signal="audience-measurement"
  defer
></script>

At the other end, data-device-signal="off" switches device recognition off entirely. That costs you the per-browser rate-limit windows — the per-address and per-site limits still apply — so the capacity you're spending is your own.

Only those two values are recognised, spelled exactly as shown. Any other value, such as a typo or a truncation, leaves the default in place, so a misspelling neither switches off the per-browser rate limits nor declares a measurement basis you did not give. Two things also override your declaration:

• A visitor whose browser broadcasts Global Privacy Control is never counted for measurement, whatever the tag says.
• Browser privacy settings that block the signal outright fall back to address-level and site-level checks.

Voice and the microphone

Voice needs no change to the snippet. If your site has voice input (speech-to-text) switched on, or takes voice calls, the chat is allowed to use the microphone and the visitor's browser asks for permission when they start speaking or calling — this follows your plan and settings, not a tag attribute. Without either, the chat is not given the microphone, so visitors are not prompted for a feature that isn't there.

If your site does have voice but you want to disable the microphone on a specific site, add data-allow-microphone="false" to the script tag. There is no "true" value: the tag can take the microphone away, but it does not grant it. See Voice Features.

Customization

Apart from the optional attributes above, visual and behavioural settings live in the dashboard, not in the snippet — so you tune the widget without ever touching the code you pasted:

• Appearance (bubble colour, logo, avatar, background, accent colour — per light/dark theme) → Dashboard → Chat Configuration
• Welcome message and suggested questions → Dashboard → Chat Configuration
• Bubble position, default theme, and auto-open behaviour → Dashboard → Chat Configuration
• Voice input / output → Dashboard → Chat Configuration (see Voice Features)

The full walkthrough is in Customizing the chat widget. Saved changes reach your site on its next page load — no need to re-paste the snippet.

Troubleshooting — Content Security Policy (CSP)

You can skip this section unless your site sets a custom CSP header. Most WordPress, Shopify, Webflow, Wix, and Squarespace sites don't — the widget just works out of the box.

If your site does set a CSP and the widget doesn't appear, you'll need to allow two of our origins. Add (or merge into) these three CSP directives:

script-src  https://api.novixagent.ai;
frame-src   https://widget.novixagent.ai;
connect-src https://api.novixagent.ai;

What each line allows:

• script-src — loading our embed script (novixagent-ai.js).
• frame-src — rendering the chat iframe inside the bubble.
• connect-src — the embed script fetching your widget config and sending the open-chat engagement event.

One addition: if you set a Bubble Icon (URL) in Chat Configuration, your page loads that image from the address you entered, so allow its host under img-src. The chat itself, voice, file uploads, AI traffic and telemetry run inside our iframe, where your page's CSP does not apply. A policy that blocks inline styles does not stop the widget; the launcher only loses its pulse and hover animations.

Quick CSP check

Open your site → DevTools → Console tab. If you see a red error mentioning Refused to load, Refused to frame, or Refused to connect and one of our hostnames, that's a CSP block — apply the three lines above.

If you see no console errors but still no bubble, it's not CSP — re-check data-user-id, that the script is on the page, and that your plan is active (see Step 3 — Verify it works above).

Removing the widget

Delete the <script> tag from your site. The bubble disappears on next page load. Your website, configuration, and data stay intact in the dashboard — removing the tag only stops the bubble from rendering.

---

Stuck? Email support@novixagent.ai with your website URL and we'll take a look.