Overview

The whole SDK on one page.

Last updated 27 Oct 2026

Help AI Elements is a library of embeddable AI agent elements for the browser — Web Components + a programmatic API that drop the agent into any website. Today the chat element ships in six layouts (floating launcher, inline block, modal, drawer, full-page, standalone) plus an iframe wrapper for strict isolation. This is the complete guide for developers integrating any of them on their own sites.

Version: the running build's version is on window.HelpAI.version (and the version export) — it tracks the published @helpai/elements package. · Primary package: @helpai/elements · CDN: https://cdn.help.ai/sdk/js/elements/latest/elements.js

30-second install#

Paste one line into your HTML <head>. Done.

html

<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" defer></script>

A floating chat bubble appears in the bottom-right corner. Visitors click it → the panel opens → they can chat.

Get the public key and deployment ID from help.ai (opens another site) → Dashboard → Deployments.

Continue with the quickstart →

Where to go next#

You want to…	Read
Install the widget end-to-end	Quickstart
See every install method (NPM, Web Component, React)	Installation
Customize every option	Configuration reference
Match my brand colors and typography	Theming & customization
Send chat events to my analytics	Events & hooks
Wire GA4 / Mixpanel / Segment / multi-provider	Analytics integration
Integrate with Next.js / Vue / Svelte / WordPress / Shopify	Framework integrations
Copy a working example	Recipes
Let the AI agent act on my page	Page tools
Diagnose "why isn't this working"	Troubleshooting
Quick answer to a common question	FAQ
Compact API reference for lookup	API reference
Understand what data the widget sees	Security & privacy
Check browser compatibility	Browser support

For your visitors — a conversational assistant for questions, support, product discovery, or guided workflows. Supports:

Text chat with streaming responses (answers appear token-by-token).
File uploads (images, PDFs, documents).
Voice input (browser-native transcription).
Multiple languages with a language picker.
Light, dark, or auto theme.
Chat history across conversations and devices.

For you, the developer — a drop-in component with:

Zero build step required. Works on any HTML page.
Framework integrations for Next.js, React, Vue, Svelte, and any Web Component-compatible stack.
Shadow DOM isolation — your site's CSS can't break the widget, and the widget's CSS can't leak out.
~107 KB gzipped with an enforced 108 KB ceiling. No render-blocking script.
Every UI option configurable at runtime from the Help AI dashboard, without redeploying the widget.
Full event stream for analytics integrations.

For your end users' experience — the widget opens in the corner, stays out of the way until clicked, remembers the user's chat thread across reloads, and respects prefers-color-scheme + prefers-reduced-motion.

Key concepts#

You'll run into these terms throughout the docs. One sentence each.

Term	What it means
public key	A browser-safe token (`agent_pk_...`) that authorizes access to your public widget surface.
Deployment	A named configuration in your dashboard — selected by its deployment UUID alongside the public key.
Widget instance	One running chat widget on a page. You can have multiple instances with different configs.
Widget ID	A name you pick for an instance (`"support"`, `"sales"`). Only needed when you run more than one widget on a page.
Mode	How the widget renders: `floating` (floating bubble — default), `inline` (fills a container in your layout), or `standalone` (full viewport).
Visitor	An anonymous identifier we mint per browser. Lets returning visitors resume their previous chat.

Installation paths at a glance#

Five ways to install. Pick whichever fits your site:

Path	Best for	Example
*`<script data->`**	Static HTML sites, WordPress, marketing pages — zero JS needed	`<script src="..." data-public-key="..." data-ai-agent-deployment-id="..." defer></script>`
Async loader snippet	Sites that already use tag managers or analytics queues	`HelpAI('init', { publicKey: '...', aiAgentDeploymentId: '...' })`
NPM package	Next.js, Vite, Nuxt, any framework with a build step	`import { init } from '@helpai/elements'`
Web Component	Any framework or plain HTML — declarative	`<web-ai-chat public-key="..." ai-agent-deployment-id="..."></web-ai-chat>`
ESM via CDN	Plain HTML, sandboxes, MDX — no build, no NPM install	`import { mount } from 'https://cdn.jsdelivr.net/npm/@helpai/elements@<version>/elements.esm.js'`

All five use the same underlying library. Same options, same events, same behavior. Full comparison: Installation.

A full-featured example#

The minimum install is one line. But you can customize a lot. Here's a fuller example showing the most common options in one place:

html

<script type="module">
  import { init } from 'https://cdn.help.ai/sdk/js/elements/latest/elements.esm.js';

  const chat = init({
    publicKey: 'agent_pk_abc123...',
    aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000',

    // Rendering + behavior
    presentation: {
      mode: 'floating', // default — floating bubble
      position: 'bottom-right', // or bottom-left / top-right / top-left
    },
    behavior: { startMinimized: true }, // default — panel starts closed
    theme: 'auto', // auto / light / dark

    // Branding (override the workspace palette)
    // theme: { accent: '#ff3e00', radius: '12px' },

    // Launcher chrome
    launcher: {
      variant: 'pill', // circle / pill / bar / minimal
      label: 'Ask us anything',
      icon: 'chat', // chat / spark / message / help / wand
      callout: { text: "Hi! I'm here to help 👋", delayMs: 2000 },
    },

    // Host-asserted context for the AI (optional, informational only)
    userContext: {
      id: 'user_42',
      email: 'jane@help.ai',
      name: 'Jane Doe',
    },
    pageContext: { area: 'support' },

    // Listen for events
    onMessage: (m) => console.log('New message:', m),
    onOpen: () => console.log('Widget opened'),
    onError: (err) => console.error('Widget error:', err),
  });

  // Programmatic control
  document.querySelector('#open-chat').onclick = () => chat.open();
</script>

Every option explained in Configuration. Every customization path in Theming.

Support#

Questions? FAQ — common answers first. support@help.ai for anything else.
Found a bug? File an issue at github.com/help-ai/elements (opens another site).
Need a feature? Same place — we read every request.
Status page: help.ai/status (opens another site).

Licensing#

The widget runtime is source-available and free to embed on any site you own or operate. Your API usage is billed under your Help AI plan — see help.ai/pricing (opens another site).

Still need help?

Ask the community