@helllo-ai/spark-chat-widget/README.md

Helllo AI Spark Chat Widget — guided navigation embed for website assistants

# @helllo-ai/spark-chat-widget

[![unpkg](https://img.shields.io/badge/CDN-unpkg-blue)](https://unpkg.com/@helllo-ai/spark-chat-widget/)

Spark-only embeddable chat widget with **guided navigation**, session persistence, and site-wide install support. Use this package for assistants created via Spark onboarding — not the standard `@helllo-ai/agent-chat-widget`.

## Quick start

```html
<!-- Add to every page (footer / site-wide), not homepage only -->
<script src="https://unpkg.com/@helllo-ai/spark-chat-widget@latest/agent-chat.spark-core.latest.js"></script>
<script>
  window.AgentChatWidget.init({
    agentId: 'your-agent-id',
    embedKey: 'your-embed-key',
    title: 'Chat with us',
    primaryColor: '#2664eb',
    enableGuidedNavigation: true,
    sessionPersistTtlMs: 1800000,
    position: 'bottom-right',
    viewType: 'rail'
  });
</script>
```

## CDN URLs

| Environment | URL |
|-------------|-----|
| Latest | `https://unpkg.com/@helllo-ai/spark-chat-widget@latest/agent-chat.spark-core.latest.js` |
| Production | `https://unpkg.com/@helllo-ai/spark-chat-widget@latest/agent-chat.spark-core.prod.js` |
| Pinned version | `https://unpkg.com/@helllo-ai/spark-chat-widget@0.1.9/agent-chat.spark-core.latest.js` |

## Configuration

See `docs/features/SPARK_WIDGET_CORE.md` in the main repo for the full parameter list.

Common options:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `captureCustomerInfo` | `false` | Show name/email form before chat |
| `allowSkipCustomerInfo` | `true` | Allow skipping the form |
| `enableVoice` | `true` | Show voice channel in rail/hub |
| `viewType` | `'hub'` | `'hub'` or `'rail'` (channel icons) |
| `primaryColor` | — | Brand accent color (hex) |
| `enableGuidedNavigation` | `true` | Spark page navigation offers |

All options also support `data-*` attributes on the script tag.

## Development

Source of truth: `frontend/public/spark/agent-chat.spark-core.latest.js`

```bash
cd frontend
npm run build:spark-widget          # sync latest
npm run build:spark-widget:prod     # build prod variant
npm run publish:spark-widget        # bump + publish to npm
```