# Help AI Elements

> Help AI's AI chat widget for any website: an AI agent that answers visitors from the customer's own help content, can hand the chat to a person, and shows Help articles and News. Install it with one script tag, the `<web-ai-chat>` element, the npm API or the React kit. These docs match @helpai/elements@1.15.2.

What a coding agent needs to install it right the first time:

- Two values come from the deployment's Install page in the Help AI dashboard: the public key (`agent_pk_…`) and the AI agent deployment id (a UUID). Both belong in browser code. The deployment's secret key never does.
- Plain HTML, WordPress or any CMS: `<script src="https://cdn.help.ai/sdk/js/elements/1.15.2/elements.js" data-public-key="agent_pk_…" data-ai-agent-deployment-id="…" defer></script>`.
- React, Next.js, Remix: install `@helpai/elements` and render `<HelpAI publicKey="…" aiAgentDeploymentId="…" />` from `@helpai/elements/react` once, in the root layout. `useHelpAI()` in any component returns `{ state, ask, open, close, reset }`. It is server-render safe; import everything from `@helpai/elements/react`.
- Vue, Svelte, Angular and other bundlers: `import '@helpai/elements/web-component'`, then `<web-ai-chat public-key="…" ai-agent-deployment-id="…"></web-ai-chat>`. JSX typings: `@helpai/elements/jsx/react`, `/jsx/vue`, `/jsx/svelte`.
- Site buttons need no JavaScript: `data-helpai-ask="Which plan fits a team of 10?"` puts the question in the chat, `data-helpai-open="help"` opens a tab (`home`, `chats`, `help`, `news`). In code, `ask(text)` fills the composer and sends only with `{ send: true }`.
- Logged-in users: your server signs a JWT with the deployment's secret key (HS256; `sub` = your user id, `exp`; optional `name`, `email`), and the widget gets a function that fetches it: `userToken` at init, `login(fn)` after sign-in, `reset()` at sign-out. Their chats then follow them to any device. Never sign tokens in the browser.
- Your page's own events: `chat.track('plan_viewed', { plan: 'pro' })` sends an analytics hit and lets the agent see the visitor's last 10 events with their next message.
- Page tools: `chat.registerTool({ name, description, inputSchema?, annotations?: { consequentialHint }, execute })` (WebMCP shape; `HelpAI('registerTool', tool)` from the script tag, `useHelpAITool(tool)` in React, or a `<form toolname tooldescription>`) lets the agent act on the page (open a form, read the cart). `execute(input, { signal })` runs once in the browser and returns JSON for the agent; abort the registration's `signal` when a route leaves.
- `theme: 'host'` (`theme="host"`) follows the site's own light/dark switch.
- Pin the exact version in production, as above; `latest` changes under you.
- It works when the launcher shows in the bottom corner and `HelpAI.ready()` (or `chat.ready`) resolves.

## Docs

- [Quickstart](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/quickstart.md): credentials, the install paths and a first check, in five minutes
- [Installation](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/installation.md): every install path in depth: script tag, async loader, npm, web component, CDN URLs and version pinning
- [Frameworks](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/frameworks.md): the React kit (`<HelpAI />`, `useHelpAI()`), Next.js, Remix, Vue, Nuxt, Svelte, Astro, Angular, WordPress, Shopify, Webflow
- [Configuration](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/configuration.md): every option by group, with examples
- [Option reference](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/options.md): the table of every option, generated from the schemas; authoritative
- [API reference](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/api-reference.md): exports, instance methods (`ask`, `open`, `state`, `ready`, `reset`, …), the global API, no-script triggers, deep links, JSX typings
- [Events and hooks](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/events-and-hooks.md): every event and its payload, `on()` and `hook()`
- [Page tools](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/page-tools.md): WebMCP-shaped tools the AI agent calls on your page (`registerTool`, `tools`, `useHelpAITool`, `<form toolname>`), run once in the browser
- [Theming](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/theming.md): colors, shapes, fonts, launcher styles, `theme: "host"` and `::part()` styling
- [Recipes](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/recipes.md): copy-paste solutions for common integrations
- [Analytics](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/analytics.md): sending widget activity to Google Analytics, Segment, PostHog and other trackers
- [Security and privacy](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/security-privacy.md): isolation, CSP, what the widget stores and sends
- [Browser support](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/browser-support.md): supported browsers and fallbacks
- [Troubleshooting](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/troubleshooting.md): an install that does not show, connect or answer
- [FAQ](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/faq.md): short answers to common questions
- [Overview](https://cdn.help.ai/sdk/js/elements/1.15.2/docs/README.md): the whole SDK on one page

## Optional

- [Every doc in one file](https://cdn.help.ai/sdk/js/elements/1.15.2/llms-full.txt): the docs above, concatenated