npm package: @ko-ia/voice-widget
Description: Widget de chat de voz da KOIA para integração fácil em qualquer site
Author: KOIA Team
Latest version: 1.0.6

# KOIA Voice Widget

A modern, easy-to-integrate voice chat widget for any website. Built with the KOIA Voice SDK for real-time voice interactions with AI agents.

## Features

- **Voice Recognition** - Real-time voice transcription
- **Voice Response** - Natural AI voice responses
- **Chat Interface** - Clean, modern chat UI with message history
- **Customizable** - Colors, position, texts, and behavior
- **Framework Agnostic** - Works with HTML, React, Vue, Angular, and more
- **Mobile Responsive** - Optimized for both desktop and mobile
- **Easy Integration** - Just one script tag and widget element

## Quick Start

### 1. Include the Script

```html
<script src="https://your-cdn.com/koia-voice-widget.min.js" async></script>
```

### 2. Add the Widget

```html
<koia-voice-widget
  api-token="your-api-token"
  agent-id="your-agent-id">
</koia-voice-widget>
```

That's it! The widget will appear in the bottom-right corner of your page.

## Installation

### Option 1: CDN (Recommended)

```html
<script src="https://your-cdn.com/koia-voice-widget.min.js" async></script>
```

### Option 2: Download

1. Download the latest release from [Releases](https://github.com/your-org/koia-voice-widget/releases)
2. Host the file on your server
3. Include it in your HTML

### Option 3: Build from Source

```bash
git clone https://github.com/your-org/koia-voice-widget.git
cd koia-voice-widget
npm install
npm run build
```

## Configuration

### Required Attributes

| Attribute | Description |
|-----------|-------------|
| `api-token` | Your KOIA API authentication token |
| `agent-id` | ID of the AI agent to use for conversations |

### Optional Attributes

| Attribute | Default | Description |
|-----------|---------|-------------|
| `title` | "KOIA Voice Assistant" | Title displayed in chat header |
| `primary-color` | "#14B8A6" | Primary color for the widget |
| `header-color` | same as primary-color | Color of the chat header |
| `position` | "bottom-right" | Widget position (bottom-right, bottom-left, top-right, top-left) |
| `welcome-message` | "Bem-vindo! Clique no botão..." | Initial welcome message |
| `connection-message` | "Clique para iniciar uma conversa" | Message shown before connecting |
| `close-button-text` | "Fechar" | Text for close button tooltip |
| `mute-enabled` | "true" | Show/hide mute button |
| `base-url` | "https://api.dev.ko-ia.com" | KOIA API base URL |

## Examples

### Basic Usage

```html
<koia-voice-widget
  api-token="your-token-here"
  agent-id="your-agent-id">
</koia-voice-widget>
```

### Customized Widget

```html
<koia-voice-widget
  api-token="your-token-here"
  agent-id="your-agent-id"
  title="Sales Assistant"
  primary-color="#2563eb"
  header-color="#1d4ed8"
  position="bottom-left"
  welcome-message="Hello! How can I help you with our products?"
  connection-message="Click to start talking about sales"
  mute-enabled="true">
</koia-voice-widget>
```

### Multiple Widgets

```html
<!-- Sales Widget -->
<koia-voice-widget
  api-token="token1"
  agent-id="sales-agent"
  title="Sales"
  primary-color="#10b981"
  position="bottom-right">
</koia-voice-widget>

<!-- Support Widget -->
<koia-voice-widget
  api-token="token2"
  agent-id="support-agent"
  title="Support"
  primary-color="#dc2626"
  position="bottom-left">
</koia-voice-widget>
```

## Framework Integration

### React

```jsx
function App() {
  return (
    <div>
      <h1>My App</h1>
      <koia-voice-widget 
        api-token="your-token"
        agent-id="your-agent"
        title="AI Assistant"
      />
    </div>
  );
}
```

### Vue.js

```vue
<template>
  <div>
    <h1>My App</h1>
    <koia-voice-widget 
      api-token="your-token"
      agent-id="your-agent"
      title="AI Assistant"
    />
  </div>
</template>
```

### Angular

```typescript
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule { }
```

```html
<!-- app.component.html -->
<koia-voice-widget 
  api-token="your-token"
  agent-id="your-agent">
</koia-voice-widget>
```

## JavaScript API

### Accessing the Widget

```javascript
const widget = document.querySelector('koia-voice-widget');
```

### Methods

```javascript
// Open/close chat window
widget.openChat();
widget.closeChat();

// Start/end voice calls
widget.startCall();
widget.endCall();

// Check widget state
console.log(widget.isOpen);        // Chat window open/closed
console.log(widget.isConnected);   // Voice connection status
```

### Events

```javascript
// Listen to widget events
widget.addEventListener('connected', (e) => {
  console.log('Widget connected to voice service');
});

widget.addEventListener('disconnected', (e) => {
  console.log('Widget disconnected');
});

widget.addEventListener('message', (e) => {
  console.log('New message:', e.detail);
});
```

## Styling

The widget uses CSS custom properties that can be overridden:

```css
koia-voice-widget {
  --primary-color: #your-color;
  --background: #ffffff;
  --text-color: #1f2937;
  --border-radius: 16px;
}
```

## Browser Support

- **Chrome**: 60+
- **Firefox**: 55+
- **Safari**: 11+
- **Edge**: 79+
- **Mobile**: iOS 11+, Android Chrome 60+

## Requirements

- **HTTPS**: Required for microphone access
- **Microphone Permission**: Users must grant microphone access
- **Internet Connection**: Required for voice processing

## Development

### Setup

```bash
git clone https://github.com/your-org/koia-voice-widget.git
cd koia-voice-widget
npm install
```

### Development Server

```bash
npm run dev
```

Opens development server at `http://localhost:3000` with hot reload.

### Build

```bash
npm run build
```

Creates optimized build in `dist/` directory.

### Project Structure

```
koia-voice-widget/
├── src/
│   ├── widget.js          # Main widget code
│   └── koia-sdk.js        # KOIA Voice SDK
├── examples/
│   ├── basic.html         # Basic usage example
│   └── customized.html    # Advanced customization example
├── dist/                  # Build output
├── package.json
├── vite.config.js
└── README.md
```

## Troubleshooting

### Widget Not Appearing

1. Ensure script is loaded correctly
2. Check browser console for errors
3. Verify required attributes are provided
4. Make sure page is served over HTTPS

### Voice Not Working

1. Verify page is served over HTTPS
2. Check microphone permissions
3. Test in supported browser
4. Verify API credentials

### Connection Issues

1. Check `api-token` is valid
2. Verify `agent-id` exists
3. Confirm internet connectivity
4. Check browser network tab for API errors

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- **Documentation**: [https://docs.ko-ia.com](https://docs.ko-ia.com)
- **Issues**: [GitHub Issues](https://github.com/your-org/koia-voice-widget/issues)
- **Email**: support@ko-ia.com

## Changelog

### v1.0.0
- Initial release
- Real-time voice chat functionality
- Customizable appearance and behavior
- Framework-agnostic web component
- Mobile responsive design

---

Built with ❤️ by the KOIA team