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

<script src="https://your-cdn.com/koia-voice-widget.min.js" async></script>

2. Add the Widget

<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)

<script src="https://your-cdn.com/koia-voice-widget.min.js" async></script>

Option 2: Download

1. Download the latest release from Releases
2. Host the file on your server
3. Include it in your HTML

Option 3: Build from Source

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

<koia-voice-widget
  api-token="your-token-here"
  agent-id="your-agent-id">
</koia-voice-widget>

Customized Widget

<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

<!-- 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

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

<template>
  <div>
    <h1>My App</h1>
    <koia-voice-widget 
      api-token="your-token"
      agent-id="your-agent"
      title="AI Assistant"
    />
  </div>
</template>

Angular

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule { }

<!-- app.component.html -->
<koia-voice-widget 
  api-token="your-token"
  agent-id="your-agent">
</koia-voice-widget>

JavaScript API

Accessing the Widget

const widget = document.querySelector('koia-voice-widget');

Methods

// 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

// 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:

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

git clone https://github.com/your-org/koia-voice-widget.git
cd koia-voice-widget
npm install

Development Server

npm run dev

Opens development server at http://localhost:3000 with hot reload.

Build

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 file for details.

Support

• Documentation: https://docs.ko-ia.com
• Issues: GitHub Issues
• Email: [email protected]

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