# @dynaris/widget
**Add an AI chat + voice agent to any website. One script tag.**
[](https://www.npmjs.com/package/@dynaris/widget)
[](https://www.npmjs.com/package/@dynaris/widget)
[](https://github.com/dynaris-ai/dynaris-widget/blob/main/LICENSE)
[](https://bundlephobia.com/package/@dynaris/widget)
An embeddable AI chat widget that connects your website to the [Dynaris](https://dynaris.ai) platform — the same multi-agent pipeline powering WhatsApp, SMS, and voice channels, now as a floating chat bubble on your page. Optional **in-browser voice mode** lets users speak directly to your AI agent using LiveKit WebRTC.
No frameworks. No backend to write. No configuration overhead. Drop it in and your users are talking to AI in under 2 minutes.
```html
```
That's it. Seriously.
> **New to Dynaris?** Get your API key and set up your AI agent at [dynaris.ai](https://dynaris.ai).
---
## Features
- **Zero runtime dependencies** — pure ES modules, ~35 KB gzipped, no React/Vue required
- **One file for script tag** — styles inlined in the UMD build, nothing extra to load
- **In-browser voice AI** — real-time voice sessions via LiveKit WebRTC (opt-in, see [Voice Mode](#voice-mode))
- **Real-time streaming** — SSE with automatic polling fallback; works behind any proxy
- **File attachments** — users can paste images or attach files up to 5 MB
- **Session persistence** — conversation history survives page reloads via `localStorage`
- **Programmatic API** — `show()`, `hide()`, `send()`, `showWithVoice()`, `destroy()`
- **TypeScript support** — type definitions included
- **Framework agnostic** — works with React, Next.js, Vue, Svelte, or plain HTML
---
## Install
**Script tag (zero setup):**
```html
```
**NPM / pnpm:**
```bash
npm install @dynaris/widget
# or
pnpm add @dynaris/widget
```
---
## Integration
### JavaScript / ES Module
```js
import { init } from '@dynaris/widget';
const controller = init({
apiKey: 'YOUR_API_KEY',
apiUrl: 'https://api.dynaris.ai',
title: 'Chat Support',
subtitle: 'AI assistant',
welcomeMessage: 'Welcome! How can I help you?',
privacyPolicyUrl: 'https://yoursite.com/privacy',
position: 'bottom-right',
});
// Programmatic control
controller.show();
controller.hide();
controller.toggle();
controller.send('Hello!');
controller.destroy();
```
### React / Next.js
```jsx
// components/ChatWidget.jsx
import { useEffect } from 'react';
export function ChatWidget() {
useEffect(() => {
let ctrl;
import('@dynaris/widget').then(({ init }) => {
ctrl = init({
apiKey: process.env.NEXT_PUBLIC_DYNARIS_API_KEY,
apiUrl: process.env.NEXT_PUBLIC_DYNARIS_API_URL,
title: 'Chat Support',
welcomeMessage: 'Hi! How can I help you?',
});
});
return () => ctrl?.destroy();
}, []);
return null;
}
```
Add to your root layout:
```jsx
// app/layout.jsx
import { ChatWidget } from '@/components/ChatWidget';
export default function RootLayout({ children }) {
return (
{children}
);
}
```
`.env.local`:
```env
NEXT_PUBLIC_DYNARIS_API_KEY=your_api_key_here
NEXT_PUBLIC_DYNARIS_API_URL=https://api.dynaris.ai
```
---
## Voice Mode
The widget supports **in-browser voice sessions** powered by LiveKit WebRTC. Users click a microphone button in the chat header to start a real-time voice conversation with your AI agent — no phone number, no external app, no redirect.
### Enable voice (script tag)
```html
```
### Enable voice (JS/NPM)
```js
import { init } from '@dynaris/widget';
const controller = init({
apiKey: 'YOUR_API_KEY',
voiceEnabled: true,
voiceAgentId: 'YOUR_VOICE_AGENT_ID',
voiceCallLabel: 'Talk to our AI',
voiceParticipantName: 'Website Visitor', // optional
});
// Programmatically open and immediately start a voice session
controller.showWithVoice();
```
### Voice configuration options
| Option | Data Attribute | JS Key | Description |
|--------|---------------|--------|-------------|
| Enable voice | `data-voice-enabled` | `voiceEnabled` | Show the voice button in the header |
| Voice agent ID | `data-voice-agent-id` | `voiceAgentId` | Your Dynaris voice agent configuration ID |
| Call label | `data-voice-call-label` | `voiceCallLabel` | Header CTA text (default: `Call our voice AI`) |
| Participant name | `data-voice-participant-name` | `voiceParticipantName` | Name shown in the LiveKit room |
| Voice API URL | `data-voice-api-url` | `voiceApiUrl` | Override voice API base URL (defaults to `apiUrl`) |
| Agent name | `data-voice-agent-name` | `voiceAgentName` | LiveKit worker name override |
| Session duration | `data-voice-session-duration-minutes` | `voiceSessionDurationMinutes` | Browser voice token duration in minutes (default: 60) |
| Phone number | `data-voice-phone-number` | `voicePhoneNumber` | Fallback `tel:` number if not using browser voice |
| Call URL | `data-voice-call-url` | `voiceCallUrl` | Link to a `/voice` page instead of `tel:` |
---
## Configuration
All options work as `data-*` attributes (script tag) or keys in the config object (JS/NPM).
| Option | Data Attribute | JS Key | Default | Description |
|--------|---------------|--------|---------|-------------|
| API Key | `data-api-key` | `apiKey` | — | Sent as `X-Api-Key` header (preferred) |
| User ID | `data-user-id` | `userId` | — | Legacy: userId when apiKey not used |
| API URL | `data-api-url` | `apiUrl` | `https://api.dynaris.ai` | Gateway base URL |
| Title | `data-title` | `title` | `Chat` | Agent name in the header |
| Subtitle | `data-subtitle` | `subtitle` | `Speak directly with our AI` | Text under the title |
| Welcome Message | `data-welcome-message` | `welcomeMessage` | — | First message shown on open. Supports `**bold**` |
| Privacy Policy URL | `data-privacy-policy-url` | `privacyPolicyUrl` | — | Adds a privacy link in the footer |
| Logo URL | `data-logo-url` | `logoUrl` | — | Chat bubble / launcher icon |
| Header Logo URL | `data-header-logo-url` | `headerLogoUrl` | — | Logo in the widget header bar |
| Position | `data-position` | `position` | `bottom-right` | `bottom-right` or `bottom-left` |
| Viewer | `data-viewer` | `viewer` | `embed` | `embed` (floating) or `mobile-app` (full-viewport WebView) |
| Use Polling | `data-use-polling` | `usePolling` | `false` | Force polling instead of SSE |
| Hide Powered By | `data-hide-powered-by` | `hidePoweredBy` | `false` | Hide the Dynaris footer mark |
---
## Build Output
| File | Format | Use Case |
|------|--------|---------|
| `dist/dynaris-widget.es.js` | ESM | Bundlers (Vite, Next.js, Webpack) |
| `dist/dynaris-widget.umd.cjs` | UMD | `