# @volae/widget

The [Volae](https://volae.net) chat widget. Add one script tag and visitors get a chat button: your AI assistant answers from your help content, and hands the conversation to you when it can't (or when the visitor asks). You reply from the Volae inbox; the visitor sees it live. About 19 KB gzipped, no dependencies, styles isolated in Shadow DOM.

## Add it to your site

```html
<script src="https://api.volae.net/widget.js" data-key="wk_…" async></script>
```

| Attribute | |
|---|---|
| `data-key` | Your widget key from Volae settings (required) |
| `data-api` | API base URL. Default `https://api.volae.net` |
| `data-locale` | `en` or `zh` to force the visitor-facing language. Default: the browser's preferred language (Chinese or English) |

### Signed-in users

Let the assistant answer account questions (plan, payments) for signed-in users. On your server, sign the user id with the widget's identity secret:

```js
// Node
import { createHmac } from "node:crypto";
const hash = createHmac("sha256", process.env.VOLAE_WIDGET_IDENTITY_SECRET).update(user.id).digest("hex");
```

Then put the user on the page:

```html
<script>
  window.volaeWidget = { user: { id: "user_123", email: "ana@uni.edu", name: "Ana Lee", hash: "…" } };
</script>
```

If the hash doesn't match, the widget logs one warning and continues as a signed-out visitor. Never put the identity secret in frontend code.

### Control it from your page

```js
VolaeWidget.open();            // e.g. from your own "Contact us" button
VolaeWidget.close();
await VolaeWidget.identify(user); // after sign-in (same shape as above)
await VolaeWidget.reset();        // after sign-out: start over as a new anonymous visitor
```

`window.volaeWidget = { open: true }` opens the panel on load (without taking focus from your page).

## Use it from a bundler

```ts
import { mountWidget } from "@volae/widget";

const widget = mountWidget({ key: "wk_…", user, locale: "en" });
widget.open();
// widget.close(), widget.identify(user), widget.reset(), widget.destroy()
```

## What visitors see

- A round button (right or left, your brand color). On phones the panel fills the screen.
- AI answers marked "AI", with their sources underneath and "Did that solve it? Yes / Not yet". "Not yet" passes the chat to a person.
- "Talk to a person" in the header. After a handoff, a card says who has it and how soon they usually reply; signed-out visitors can leave an email for the reply.
- Replies from you, with your name, arrive live.
- English and Chinese text, following the browser.
- Keyboard: Enter sends, Shift+Enter adds a line, Esc closes. The panel is a labelled dialog and focus returns to the button when it closes.

## Privacy

The widget stores one thing on the visitor's device: a random visitor id in `localStorage` (`volae_wvid`). It does not read or set cookies on your site.

## Local demo

```bash
pnpm --filter @volae/widget demo   # http://localhost:4319
```

A fake Notely site with a fake Volae server (no real services). Use the bar at the top to switch signed-in / handoff scenes and language, have "Sol" reply, or drop the live connection to see the widget fall back to polling.
