convo-ai-embed
v3.0.0
Published
Embeddable conversational AI widget and webapp - tree-shakeable
Maintainers
bhupendra1011Readme
Convo AI Embed
Embeddable conversational AI widget and webapp components, powered by Agora's RTC technology.
Features
- Two deployment modes: Widget (floating) and WebApp (modal)
- Tree-shakeable architecture: Only import the mode you need
- Voice calling: Agora RTC integration for real-time voice communication
- Internal agent management: Built-in agent lifecycle handling
- Internal project status API: JWT-authenticated service integration (placeholder)
Installation
npm install convo-ai-embedUsage
Widget Mode (Floating Widget)
The widget appears as a floating button in the bottom-right corner of your page.
Option 1: ES Module Import (npm)
import 'convo-ai-embed/widget';<convo-agent-widget project-id="your-project-id"></convo-agent-widget>Option 2: CDN via unpkg
<!DOCTYPE html>
<html>
<head>
<script type="module" src="https://unpkg.com/[email protected]/dist/widget.js"></script>
</head>
<body>
<convo-agent-widget project-id="your-project-id"></convo-agent-widget>
</body>
</html>Option 3: React/Vue/Framework Usage
import { useEffect } from 'react';
import 'convo-ai-embed/widget';
export default function App() {
return (
<div className="App">
<h1>My App</h1>
<convo-agent-widget project-id="your-project-id"></convo-agent-widget>
</div>
);
}WebApp Mode (Modal Dialog)
The webapp shows a button that opens a full-screen modal dialog when clicked.
Option 1: ES Module Import (npm)
import 'convo-ai-embed/webapp';<convo-agent-webapp project-id="your-project-id"></convo-agent-webapp>Option 2: CDN via unpkg
<!DOCTYPE html>
<html>
<head>
<script type="module" src="https://unpkg.com/[email protected]/dist/webapp.js"></script>
</head>
<body>
<convo-agent-webapp project-id="your-project-id"></convo-agent-webapp>
</body>
</html>Option 3: React/Vue/Framework Usage
import { useEffect } from 'react';
import 'convo-ai-embed/webapp';
export default function App() {
return (
<div className="App">
<h1>My App</h1>
<convo-agent-webapp project-id="your-project-id"></convo-agent-webapp>
</div>
);
}Using Both Widget and WebApp Together
You can use both components on the same page:
ES Module Import
import 'convo-ai-embed/widget';
import 'convo-ai-embed/webapp';
export default function App() {
return (
<div className="App">
<h1>Hello CodeSandbox</h1>
<convo-agent-webapp project-id="your-project-id"></convo-agent-webapp>
<convo-agent-widget project-id="your-project-id"></convo-agent-widget>
</div>
);
}CDN via unpkg
<!DOCTYPE html>
<html>
<head>
<script type="module" src="https://unpkg.com/[email protected]/dist/widget.js"></script>
<script type="module" src="https://unpkg.com/[email protected]/dist/webapp.js"></script>
</head>
<body>
<h1>My Website</h1>
<convo-agent-webapp project-id="your-project-id"></convo-agent-webapp>
<convo-agent-widget project-id="your-project-id"></convo-agent-widget>
</body>
</html>Attributes
Both web components accept the same attribute:
| Attribute | Type | Required | Description |
|-----------|------|----------|-------------|
| project-id | string | Yes | Your agent identifier |
Architecture
The SDK is organized with two main entry points and internal modules:
src/
├── widget/ # Widget entry point (exported)
│ ├── widget.ts
│ ├── voiceManager.ts
│ └── index.ts
├── webapp/ # WebApp entry point (exported)
│ ├── webapp.ts
│ └── index.ts
├── agent/ # Internal - Agent lifecycle management
│ └── AgentManager.ts
├── services/ # Internal - API services
│ └── projectStatus.ts
└── types.ts # Shared TypeScript typesBuild Output
The build generates separate tree-shakeable bundles:
dist/widget.js- Widget bundle (~19KB + shared voice manager)dist/webapp.js- WebApp bundle (~17KB + shared voice manager)dist/voiceManager-*.js- Shared voice manager (~1.7MB including Agora SDK)
Tree-shaking: Only the imported bundle and shared dependencies are included in your final app.
Development
# Install dependencies
pnpm install
# Development mode
pnpm dev
# Build
pnpm build
# Type checking
pnpm check-typesAPI Reference
Web Components
<convo-agent-widget>
Floating widget component that appears in the bottom-right corner.
Import:
import 'convo-ai-embed/widget';Attributes:
project-id(required): Your agent identifier
<convo-agent-webapp>
Modal webapp component with button trigger.
Import:
import 'convo-ai-embed/webapp';Attributes:
project-id(required): Your agent identifier
Internal Architecture
The SDK uses internal modules (not exported) for agent and service management:
Internal Agent Manager
- Handles agent lifecycle (join, leave, status)
- Currently uses placeholder implementations
- Will be connected to real agent service
Internal Project Status Service
- Checks project status with JWT authentication
- Currently returns dummy data
- Will be connected to real managed service API
These modules are used internally by the widget and webapp components and are not accessible to consumers.
Browser Support
- Chrome 54+
- Firefox 63+
- Safari 10.1+
- Edge 79+
License
MIT
Support
- Issues: GitHub Issues
- Documentation: Full Documentation