Install the Widget

How to add the Next Cap chat widget to your website — securely, on every major platform, without leaking your API keys.

About the Widget

The Next Cap widget is a single small JavaScript snippet that adds an AI-powered chat bubble to any website. Visitors can ask questions, browse trending topics, capture leads, escalate to a human agent, or open a support ticket — all without leaving your page. Everything about how the widget looks and behaves is controlled from your dashboard, so you only ever paste the snippet once and never need to touch your site code again to update colors, copy, or behavior.

Looking for advanced setups instead? See Custom Domain to serve the widget from your own subdomain (Enterprise), or External Data API if you want to pull leads and conversations into your own systems server-side.

Quick Start

Installation is one step. Copy your snippet from Dashboard → Settings → Install, paste it just before the closing </body> tag on every page where you want the widget, and you're done. The widget loads asynchronously and will not block your page.

Default install snippethtml

<script
  src="https://api.nextcap.ai/widget/loader.js"
  data-api-key="pk_live_your_publishable_key"
  defer
></script>

Replace pk_live_your_publishable_key with the value shown in your dashboard. Each agent you create gets its own publishable key, so installing a different agent on a different site is just a matter of pasting a different snippet.

Use the Right Key — This Matters

Next Cap issues several different kinds of keys. They look similar but they have very different security properties. Pasting the wrong one into your website can leak data from your entire organization. Read this section before you install.

Safe in HTML

pk_live_…— Publishable widget key

This is the only key that belongs in your website's HTML. It's designed to be public — the same way Stripe's publishable key works. It only authorizes the widget to load its own UI and start chats. It cannot read your leads, conversations, or settings.

Safe in HTML

pk_dev_…— Development widget key

Same shape as pk_live_, but scoped for staging and local testing. Use this on your localhost and preview environments so you don't pollute your production analytics or chat history.

Server only

sk_live_…— Secret data API key

Grants full read access to leads, conversations, tickets, visitors, and analytics for your entire organization. Never put this in HTML, JavaScript bundles, mobile apps, browser extensions, or anywhere a visitor can open DevTools and read it. Use it only from your own backend.

Server only

nextcap_ck_…— CRM integration key

Tied to a paid seat in your organization. Lets your CRM reply to tickets, join live chats, and act on behalf of that seat. Treat it like a password. Never ship it to a browser.

The most common mistake we see: a developer pastes their sk_live_ or nextcap_ck_ key into the widget snippet because both keys came from the same dashboard. Only pk_live_ and pk_dev_ keys are valid in the widget. If you accidentally exposed a secret key — anywhere a visitor could see it, even briefly — go to Settings → API Keys, revoke it, and generate a new one immediately. Anything in browser code is permanent: assume it's already been scraped.

Lock Down Your Publishable Key

Even though pk_live_ is publishable, you should still restrict it so a copy of your snippet pasted onto somebody else's site does nothing. Go to Dashboard → Settings → Widget → Allowed Domains and add every domain (and subdomain) where the widget should run.

Example allowlisttext

acme.com
www.acme.com
support.acme.com
help.acme.com
*.staging.acme.com

Once domains are set, the widget will refuse to initialize if it's loaded on any other origin — even if someone has your pk_live_ key. This is your safety net against scraped snippets and malicious clones. Leaving the list empty allows the widget to run on any site, which is fine for early integration but should be locked down before launch.

For local development, also add localhost to the allowlist (or use a pk_dev_ key, which has its own allowlist). Wildcards are supported for staging and preview deployments — e.g. *.vercel.app.

Don't Hardcode Keys in Source Control

Even publishable keys should not be checked into a public Git repository. Once a key is in your commit history it's effectively permanent and easily scraped by bots. Always read the key from an environment variable at build time so rotating it is a single dashboard change and not a hunt-and-replace through your codebase.

.env.local — gitignoredbash

# Production
NEXT_PUBLIC_NEXTCAP_KEY=pk_live_your_publishable_key

# Staging / preview / local
NEXT_PUBLIC_NEXTCAP_KEY=pk_dev_your_dev_key

Then reference the env var from your install snippet (see the Next.js, React, and Vue / Nuxt examples below). For static HTML sites or CMS-managed pages where there's no build step, paste the key directly — but commit your source carefully and rotate immediately if the file is ever public.

Variable name prefixes matter. In Next.js, only env vars prefixed with NEXT_PUBLIC_ are exposed to the browser; in Vite, it's VITE_; in Nuxt, NUXT_PUBLIC_. Use one of these for the publishable widget key only. Never give a secret key one of these prefixes — it would ship to every visitor.

Install on Your Platform

Pick the tab that matches your stack. The snippet is the same in every case — what changes is where you paste it.

<!-- Place this just before </body> on every page -->
<script
  src="https://api.nextcap.ai/widget/loader.js"
  data-api-key="pk_live_your_publishable_key"
  defer
></script>

Webflow

Site Settings → Custom Code → Footer Code. Paste the HTML snippet and republish. The widget loads on every page automatically.

Squarespace

Settings → Advanced → Code Injection → Footer. Paste the HTML snippet and save. Available on Business plans and above.

Wix

Settings → Custom Code → Add Custom Code → Body — end. Paste the HTML snippet and apply to all pages.

Framer

Site Settings → General → Custom Code → End of <body> tag. Paste the HTML snippet and publish.

Updating Colors, Copy, and Behavior

You never need to redeploy your website to change how the widget looks or what it says. Open Dashboard → Agents → [your agent] and adjust:

Branding — primary color, avatar, position, welcome message
Behavior — auto-open delay, suggested questions, language picker
Lead capture — fields, custom fields, validation, post-chat or pre-chat
Trending topics — promoted questions and articles
Human handoff — escalation rules, business hours, departments
Allowed domains — the security allowlist described above

Changes take effect on the next page load — no rebuild, no redeploy, no snippet change.

Verify Your Install

Open your site in a fresh browser tab and look for the chat bubble in the corner you configured.
Open DevTools → Network and reload. Confirm loader.js returns 200 OK.
Open the bubble and send a test message. You should see a streamed reply within a few seconds.
Check Dashboard → Conversations — your test conversation should appear there in real time.

Troubleshooting

The widget doesn't appear at all

Open DevTools → Console. Look for a Next Cap message. The most common cause is that your current domain is not in the allowed-domains list — the widget refuses to initialize and logs a warning. Add the domain in Settings → Widget → Allowed Domains and reload.

Console says "invalid api key"

You're passing a key with the wrong prefix. The widget only accepts pk_live_ and pk_dev_ keys. If your key starts with sk_live_ or nextcap_ck_, you grabbed the wrong one — and you should rotate it now, since you almost certainly pasted it somewhere a visitor could see.

Widget loads but messages never arrive

Check that your site's Content Security Policy allows connections to api.nextcap.ai over both HTTPS and WSS. The widget uses WebSocket for real-time streaming and live chat. See the CSP example below.

Widget is visible but blocked by an ad blocker

Some aggressive ad-blocker lists flag third-party chat scripts. The fix is to serve the widget from your own subdomain — see Custom Domain (Enterprise plan).

Multiple widgets on the same page

Only one Next Cap widget is supported per page. If you embed two snippets with different keys, the second one is ignored. To run different agents on different sections, split them across separate routes or subdomains.

Content Security Policy

If your site enforces a CSP, add the following directives so the widget can load and connect:

CSP additionstext

script-src  https://api.nextcap.ai;
connect-src https://api.nextcap.ai wss://api.nextcap.ai;
img-src     https://api.nextcap.ai data:;
font-src    https://api.nextcap.ai;
style-src   'unsafe-inline';

If you've set up a custom domain, replace api.nextcap.ai with your subdomain. The widget injects its styles via a Shadow DOM, which is why style-src 'unsafe-inline' is needed.

Next Steps

Identity Verification →

Verify logged-in users with HMAC-SHA256 so your widget knows exactly who's chatting — across devices and sessions.

Custom Domain →

Serve the widget from your own subdomain to bypass ad-blockers and meet regional compliance requirements.

External Data API →

Pull leads, conversations, and analytics into your own systems server-side — using sk_live_ keys, never from the browser.