@volara/widget

Volara chat widget

Drop a live chat launcher onto any website with a single line of HTML. No framework, no build step on your side, no backend to run. The widget is a tiny, self-contained script that renders a floating button and a chat panel, and talks to Volara over a public, domain-restricted widget key.

<script src="https://cdn.volara.chat/widget.js" data-key="YOUR_WIDGET_KEY" async></script>

Paste that just before </body> (or anywhere in the page — async keeps it out of your critical path) and you're done.

Heads up: the cdn.volara.chat host is still being set up. Until it's live you can self-host the built dist/widget.js from your own static host or CDN and point the src at it — everything else works the same.

Getting a widget key

• Sign in to your Volara dashboard.
• Go to Settings → Widget (widget configuration).
• Copy the widget key and add the domains you'll embed it on.

The widget key is public and safe to ship in your HTML. It only works on the domains you allow-list, and it cannot read or write anything outside the chat session it opens. It is not your secret API key — never put the secret key on a web page.

Options

Configure everything with data-* attributes on the same <script> tag:

Attribute	Required	Default	What it does
data-key	yes	—	Your public widget key.
data-api	no	https://api.volara.chat	Override the API base URL (mostly for staging/self-host).
data-color	no	#f97316 (Volara bloom)	Accent color for the launcher, header, and your bubbles.
data-position	no	bottom-right	bottom-right or bottom-left.

Example with customization:

<script
  src="https://cdn.volara.chat/widget.js"
  data-key="wgt_live_abc123"
  data-color="#2563eb"
  data-position="bottom-left"
  async
></script>

What it does

• Shows a floating launcher button; clicking it opens a chat panel.
• On first open it starts a session and a conversation, then remembers them in localStorage so returning visitors keep their history (scoped per widget key).
• Visitor messages send instantly (optimistic display), and the widget polls for agent / AI replies every few seconds while the panel is open.
• Renders inside a Shadow DOM, so your site's CSS can't break the widget and the widget's CSS can't leak onto your page.
• Handles the rough edges: offline, expired session, chat disabled, or a domain that isn't allow-listed all show a clear message instead of failing silently.
• Accessible (ARIA roles, keyboard support, Escape to close, visible focus) and responsive — on phones the panel goes full-screen.

How it talks to Volara

All requests use the public widget key and a short-lived session token the server issues. The secret API key never touches the browser.

Call	Purpose
POST /api/widget/session	Start a session, get a sessionToken.
POST /api/widget/messages (Bearer token)	Send a visitor message.
GET /api/widget/messages?since=… (Bearer)	Poll for agent / AI replies.

Build it yourself

The widget builds with a single dev dependency (esbuild).

bun install
bun run --filter @volara/widget build
# emits dist/widget.js (minified, for the CDN) and dist/widget.dev.js (readable)

Open demo.html in a browser to try the dev build locally. Point data-api at your local backend to test the full flow.

License

MIT — see LICENSE.