npm package: @kivox/widget
Description: Web Component widget for embeddable chat and voice interfaces
Author: Juan Mesa
Latest version: 0.1.0-beta.37

# Kivox Widget

`@kivox/widget` is the official embeddable web widget for interacting with Kivox. It provides a ready-to-use chat and voice interface that can be embedded into any website or web application with minimal setup. The widget is built on top of [@kivox/client](https://github.com/ekisa-team/kivox/tree/main/packages/kivox-client) and handles UI, audio I/O, session lifecycle, and real-time events automatically.

Features

- Embeddable custom element (`<kivox-widget>`)
- Chat and voice conversation modes
- Real-time streaming responses and events
- Built-in audio recording and playback
- Session lifecycle management
- Themeable UI (light/dark, future custom themes)
- Framework-agnostic (works in any site or SPA)

## Documentation

<https://docs.kivox.com.co/packages/kivox-widget>

## Installation

```bash
# NPM
npm install @kivox/widget

# PNPM
pnpm add @kivox/widget

# Yarn
yarn add @kivox/widget

# Bun
bun add @kivox/widget
```

## Installation (CDN)

The widget can also be loaded directly from a CDN without a build step. This is the easiest way to embed Kivox into static sites or server-rendered pages.

```html
<script type="module">
  import 'https://cdn.jsdelivr.net/npm/@kivox/widget/dist/index.js';
</script>
```

Or with a pinned version (recommended for production):

```html
<script type="module">
    import 'https://cdn.jsdelivr.net/npm/@kivox/widget@0.1.0/dist/index.js';
</script>
```

Then use the custom element:

```html
<kivox-widget
  agent-id="019bb51e-e45f-75e3-b828-94fdf231711e"
  base-url="http://localhost:7700"
  mode="chat"
  theme="light">
</kivox-widget>
```

## Basic example (HTML)

```ts
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Kivox Widget</title>
    <script type="module">
      import '@kivox/widget';
    </script>
  </head>
  <body>
    <kivox-widget
      agent-id="019bb51e-e45f-75e3-b828-94fdf231711e"
      base-url="http://localhost:7700"
      mode="chat"
      theme="light">
    </kivox-widget>
  </body>
</html>
```

## Basic example (JavaScript)

```ts
import "@kivox/widget";

const widget = document.createElement("kivox-widget");

widget.agentId = "019bb51e-e45f-75e3-b828-94fdf231711e";
widget.baseUrl = "http://localhost:7700";
widget.mode = "voice";
widget.theme = "dark";

document.body.appendChild(widget);
```

## Authentication

```ts
import "@kivox/widget";

const widget = document.createElement("kivox-widget");

widget.agentId = "019bb51e-e45f-75e3-b828-94fdf231711e";
widget.baseUrl = "http://localhost:7700";
widget.headers = {
 Authorization: "Bearer token",
};

document.body.appendChild(widget);
```

## Attributes

| Name       | Type                     | Description                   |
| ---------- | ------------------------ | ----------------------------- |
| `agent-id` | `string`                 | ID of the agent to connect to |
| `base-url` | `string`                 | Base URL of the Kivox API     |
| `mode`     | `"chat" \| "voice"`      | Conversation mode             |
| `theme`    | `"light" \| "dark"`      | Widget theme                  |
| `headers`  | `Record<string, string>` | Additional HTTP headers       |

## Events

The widget emits DOM events for integration and observability.

```ts
widget.addEventListener('kivox:ready', () => {
  console.log('Widget ready');
});

widget.addEventListener('kivox:message', (e: any) => {
  console.log('Message event:', e.detail);
});

widget.addEventListener('kivox:error', (e: any) => {
  console.error('Widget error:', e.detail);
});
```

## Relationship to the Kivox Client

The widget is built on top of the official Kivox client:

- `@kivox/client` handles protocol, sessions, events, and audio primitives
- `@kivox/widget` adds UI, theming, and interaction layers

If you need full control over UX, state, or rendering, use the client directly instead of the widget.

## Other examples

- [widget-chat-demo](https://github.com/ekisa-team/kivox/tree/main/examples/widget-chat-demo)
- [widget-voice-demo](https://github.com/ekisa-team/kivox/tree/main/examples/widget-voice-demo)

## Contributing

[CONTRIBUTING.md](https://github.com/ekisa-team/kivox/blob/main/CONTRIBUTING.md)

## License

[LICENSE](https://github.com/ekisa-team/kivox/blob/main/LICENSE)