Quickstart

From zero to working chat widget in under 5 minutes.

1. Get your browser deployment credentials#

1. Sign up at help.ai (opens another site) if you haven't.
2. Go to Dashboard → Deployments.
3. Click New deployment — give it a name (e.g. "Marketing site").
4. Copy the public key (agent_pk_abc123...) and deployment UUID from the generated install snippet.

The dashboard generates a copy-paste snippet for you — feel free to use that directly. The rest of this guide assumes you want to know what each piece does.

2. Pick your install path#

The widget works four ways. Pick whichever matches your site:

• Static HTML (marketing site, WordPress, landing page) → path A.
• Async-loading site (uses Google Tag Manager, Segment, etc.) → path B.
• React / Next.js / Remix → the React kit in path C.
• Vue / Svelte / Nuxt (any framework with a build step) → path C.
• Plain HTML but prefer a declarative tag → path D.

All four paths land on the same widget with the same behavior. Mix and match as needed.

Path A — static HTML#

Paste this into your <head>:

<script src="https://cdn.help.ai/sdk/js/elements/latest/elements.js" data-public-key="agent_pk_abc123..." data-ai-agent-deployment-id="01900000-0000-7000-8000-000000000000" defer></script>

That's it. Reload your page and look at the bottom-right corner.

What defer does — the script downloads in the background and runs after the HTML parses. Zero impact on first contentful paint. Always use defer.

Available attributes — every config option is available as a kebab-case data-* attribute. Common ones:

<script
  src="https://cdn.help.ai/sdk/js/elements/latest/elements.js"
  data-public-key="agent_pk_..."
  data-ai-agent-deployment-id="01900000-0000-7000-8000-000000000000"
  data-theme="dark"
  data-position="bottom-left"
  data-launcher-variant="pill"
  data-launcher-label="Ask AI"
  defer
></script>

Full list: Installation § script data attributes.

Path B — async loader#

If your site already uses a tag-manager-style loader pattern (Google Analytics, Segment, Intercom, etc.), you'll recognize this shape:

<script>
  (function (w, d) {
    w.HelpAI =
      w.HelpAI ||
      function () {
        (w.HelpAI.q = w.HelpAI.q || []).push(arguments);
      };
    var s = d.createElement('script');
    s.async = 1;
    s.src = 'https://cdn.help.ai/sdk/js/elements/latest/elements.js';
    d.head.appendChild(s);
  })(window, document);

  HelpAI('init', { publicKey: 'agent_pk_abc123...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000' });
</script>

What this does:

1. Defines window.HelpAI as a queue until the real bundle loads.
2. Kicks off the async script download.
3. Queues an init call — it'll run as soon as the bundle is ready.

You can stack more queued calls:

HelpAI('init', { publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000' });
HelpAI('open'); // auto-opens the panel once init finishes

Same behavior as path A, just split into two script tags so you can load asynchronously.

Path C — NPM#

For sites with a build step (Next.js, Vite, Remix, Nuxt, SvelteKit, Astro…):

npm install @helpai/elements
# or: yarn add @helpai/elements
# or: pnpm add @helpai/elements
# or: bun add @helpai/elements

React, Next.js, Remix#

The React kit renders on the server safely and is already 'use client'; put it in the root layout:

// app/layout.tsx
import { HelpAI } from '@helpai/elements/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang='en'>
      <body>
        {children}
        <HelpAI publicKey={process.env.NEXT_PUBLIC_HELPAI_KEY!} aiAgentDeploymentId={process.env.NEXT_PUBLIC_HELPAI_DEPLOYMENT_ID!} />
      </body>
    </html>
  );
}

useHelpAI() in any component returns { state, ask, open, close, reset }.

Vue / Svelte / Angular / any bundler#

Call init(...) once on mount and destroy() on unmount, or use the <web-ai-chat> element (path D). Full framework-by-framework walkthrough: Framework integrations.

Path D — web component#

Declarative tag that works in any framework or plain HTML:

<!-- Load once, anywhere in the page -->
<script src="https://cdn.help.ai/sdk/js/elements/latest/elements.js" defer></script>

<!-- Use the element anywhere -->
<web-ai-chat public-key="agent_pk_abc123..." ai-agent-deployment-id="01900000-0000-7000-8000-000000000000" mode="inline" theme="auto"></web-ai-chat>

Attributes mirror the options. Changing an attribute at runtime re-renders the widget with the new value.

Web components shine for:

• In-app help centers (mode="inline" inside a sidebar).
• CMS-built pages where you can paste HTML but not run JS.
• Declarative "just put the widget here" integrations.

3. Verify it's working#

Open your page and look at the bottom-right. You should see a small round chat bubble with an accent color.

• Click it → a panel opens with a greeting from the assistant.
• Type a message → the assistant replies token-by-token.
• Close the panel → the bubble returns.
• Reload the page → your chat history stays intact.

Something not showing up? → Troubleshooting.

4. Common next steps#

• Match your brand — Theming has every color, radius, and font knob.
• Change the launcher label / icon — launcher options.
• Know who the visitor is — pass userContext: { id, email, name } (and pageContext: { area }) for personalization.
• Forward chat events to analytics — Events & hooks.
• Add a second widget (one for sales, one for support) — Recipes § Multiple widgets.

TypeScript users#

Types ship with the NPM package — no separate @types install needed:

import { init, mount, destroy, hook, type ChatWidgetOptions, type ChatWidgetInstance, type EventMap, type EventName } from '@helpai/elements';

Every option is autocomplete-friendly. Hover a field in your IDE to see its doc.

Environment variables#

For server-rendered apps, expose the public key and deployment ID through the framework's public environment variables. The values are designed for browser installation; the backend accepts the authenticated pair only when both match the same deployment:

Full security notes: Security & privacy.