# Overview

> The whole SDK on one page.

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](https://help.ai) →
**Dashboard → Deployments**.

[**Continue with the quickstart →**](/sdk/quickstart)

---

## Where to go next

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

---

## What the widget does

**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](/sdk/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](/sdk/configuration). Every
customization path in [Theming](/sdk/theming).

---

## Support

- **Questions?** [FAQ](/sdk/faq) — common answers first. [support@help.ai](mailto:support@help.ai) for anything else.
- **Found a bug?** File an issue at [github.com/help-ai/elements](https://github.com/help-ai/elements/issues).
- **Need a feature?** Same place — we read every request.
- **Status page:** [help.ai/status](https://help.ai/status).

---

## 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](https://help.ai/pricing).