A conversational AI widget wrapper for ElevenLabs, built with Preact and TypeScript. This library provides a customizable web component for integrating conversational AI into web applications.
- 🎙️ Voice-enabled conversational AI widget
- 🎨 Customizable UI with Tailwind CSS
- 📱 Responsive design with multiple trigger styles
- 🌐 Multi-language support
- 🔧 Web Component architecture for easy integration
- ⚡ Built with Preact for optimal performance
- 🎯 TypeScript support with full type definitions
npm install @askbenny/convai-widget-core<!DOCTYPE html>
<html>
<head>
<title>ConvAI Widget Demo</title>
</head>
<body>
<script type="module">
import { registerWidget } from '@askbenny/convai-widget-core';
// Register the web component
registerWidget();
// Create and configure the widget
const widget = document.createElement('askbenny-convai');
widget.setAttribute('agent-id', 'your-agent-id');
document.body.appendChild(widget);
</script>
</body>
</html>import { registerWidget } from '@askbenny/convai-widget-core';
// Register with a custom tag name
registerWidget('my-convai-widget');The widget accepts various attributes for customization:
<askbenny-convai
agent-id="your-agent-id"
server-location="us"
language="en"
trigger-style="compact"
></askbenny-convai>- Node.js 18+
- pnpm (recommended) or npm
# Clone the repository
git clone https://github.com/askbenny/convai-widget-core.git
cd widget-v2
# Install dependencies
pnpm install
# Start development server
pnpm devpnpm dev- Start development serverpnpm build- Build for productionpnpm test- Run tests with Vitestpnpm lint- Run all linting checkspnpm lint:ts- TypeScript type checkingpnpm lint:es- ESLint checkingpnpm lint:prettier- Prettier formatting check
The project uses Vitest with Playwright for browser testing:
pnpm testTests run in a real browser environment with microphone permissions for comprehensive testing of voice features.
src/
├── components/ # Reusable UI components
├── contexts/ # React/Preact contexts for state management
├── orb/ # 3D orb visualization
├── styles/ # CSS and styling
├── types/ # TypeScript type definitions
├── utils/ # Utility functions and hooks
├── widget/ # Main widget components
├── index.ts # Main entry point
└── index.dev.tsx # Development entry point
- Preact: Lightweight React alternative for optimal bundle size
- Web Components: Shadow DOM encapsulation for style isolation
- TypeScript: Full type safety and developer experience
- Tailwind CSS: Utility-first CSS framework
- Vite: Fast build tool and development server
- Vitest: Fast unit and browser testing
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature - Make your changes and add tests
- Run linting:
pnpm lint - Run tests:
pnpm test - Commit your changes:
git commit -m 'Add new feature' - Push to the branch:
git push origin feature/new-feature - Submit a pull request
This project is configured to automatically publish to npm when code is merged to the main branch.
The automated release workflow requires the following GitHub secrets:
Used for publishing packages to npm registry.
Setup Instructions:
-
Generate an npm access token:
- Log in to npmjs.com
- Go to your account settings → Access Tokens
- Click "Generate New Token"
- Choose "Classic Token" with "Automation" type
- Copy the generated token
-
Add the token to GitHub:
- Go to your repository on GitHub
- Navigate to Settings → Secrets and variables → Actions
- Click "New repository secret"
- Name:
NPM_TOKEN - Value: Paste your npm token
- Click "Add secret"
This token is automatically provided by GitHub Actions and doesn't need manual configuration. It's used for:
- Git operations (pushing version tags)
- Creating GitHub releases
- Accessing repository content
Permissions: The workflow requires these permissions (already configured in .github/workflows/npm-publish.yml):
contents: write- For pushing commits and creating releasespackages: write- For publishing packages
The build process requires several environment variables for server endpoints. Add these as GitHub secrets:
Server URLs:
VITE_SERVER_URL- Default server URLVITE_SERVER_URL_US- US region server URLVITE_SERVER_URL_EU_RESIDENCY- EU region server URLVITE_SERVER_URL_IN_RESIDENCY- India region server URL
WebSocket URLs:
VITE_WEBSOCKET_URL- Default WebSocket URLVITE_WEBSOCKET_URL_US- US region WebSocket URLVITE_WEBSOCKET_URL_EU_RESIDENCY- EU region WebSocket URLVITE_WEBSOCKET_URL_IN_RESIDENCY- India region WebSocket URL
Setup Instructions:
- Go to your repository on GitHub
- Navigate to Settings → Secrets and variables → Actions
- For each variable above:
- Click "New repository secret"
- Name: Use the exact variable name (e.g.,
VITE_SERVER_URL_US) - Value: Enter the appropriate URL for your environment
- Click "Add secret"
Note: These variables must be prefixed with VITE_ to be accessible in the Vite build process. The values should be the actual URLs for your ElevenLabs endpoints.
-
When code is merged to
main, the workflow automatically:- Runs tests and linting
- Checks if the current version is already published
- Increments the patch version (e.g., 0.0.15 → 0.0.16)
- Builds the project
- Publishes to npm
- Creates a git tag and GitHub release
- Commits the version change with
[skip ci]to avoid loops
-
To skip the automated release, include
[skip ci]in your commit message. -
For manual version control:
- Minor version:
pnpm version:minor - Major version:
pnpm version:major - Pre-release:
pnpm version:prerelease
- Minor version:
MIT © ElevenLabs
For issues and questions, please visit our GitHub repository.