# Quickstart

> Credentials, the install paths and a first check, in five minutes.

From zero to working chat widget in under 5 minutes.

---

## 1. Get your browser deployment credentials

1. Sign up at [help.ai](https://help.ai) 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](#path-a--static-html).
- **Async-loading site** (uses Google Tag Manager, Segment, etc.) → [path B](#path-b--async-loader).
- **React / Next.js / Remix** → the React kit in [path C](#path-c--npm).
- **Vue / Svelte / Nuxt** (any framework with a build step) → [path C](#path-c--npm).
- **Plain HTML but prefer a declarative tag** → [path D](#path-d--web-component).

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>`:

```html
<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:

```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"
  data-theme="dark"
  data-position="bottom-left"
  data-launcher-variant="pill"
  data-launcher-label="Ask AI"
  defer
></script>
```

Full list: [Installation § script data attributes](/sdk/installation#path-a--script-data--auto-boot).

---

## 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:

```html
<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:

```js
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…):

```bash
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:

```tsx
// 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](/sdk/frameworks).

---

## Path D — web component

Declarative tag that works in any framework or plain HTML:

```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](/sdk/troubleshooting).

---

## 4. Common next steps

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

---

## TypeScript users

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

```ts
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:

| Framework               | Env var prefix         |
| ----------------------- | ---------------------- |
| Next.js                 | `NEXT_PUBLIC_*`        |
| Vite / SvelteKit / Nuxt | `VITE_*` or `PUBLIC_*` |
| Remix                   | read from `window.ENV` |
| Create React App        | `REACT_APP_*`          |

Full security notes: [Security & privacy](/sdk/security-privacy).