@voxket-ai/voxket-live
Version:
A React widget for embedding Voxket-powered audio/video/chat experiences.
197 lines (152 loc) • 10.5 kB
Markdown
# Voxket Live SDK (`@voxket-ai/voxket-live`)
Voxket Live is a React SDK that allows you to seamlessly embed Voxket-powered AI agent experiences (audio, video, and chat) directly into your web application. It provides a client interface for users to interact with your configured Voxket agents.
## Features
- Easy integration into any React application.
- Supports audio, video, and text chat interactions with Voxket AI agents.
- Customizable welcome screen and prompts.
- Flexible styling and sizing options.
- Built with LiveKit for real-time communication.
## Installation
You can install the Voxket Live SDK using npm:
```bash
npm install @voxket-ai/voxket-live
```
or
```bash
yarn add @voxket-ai/voxket-live
```
The package is currently published at version `1.0.13`. For the latest version, you can use:
```bash
npm install @voxket-ai/voxket-live@latest
```
## Usage
To use the Voxket Live widget in your React application, simply import and use the component. **No separate CSS import is required** - styles are automatically included:
```tsx
import React from 'react';
import VoxketWidget, { VoxketWidgetProps } from '@voxket-ai/voxket-live';
const MyCustomApp = () => {
const widgetProps: VoxketWidgetProps = {
agentId: "your-unique-agent-id", // Replace with your actual Agent ID
baseUrl: "https://your.voxket.api", // Replace with your Voxket instance base URL
appId: "your-voxket-app-id", // Replace with your Voxket App ID
appSecret: "your-voxket-app-secret", // Replace with your Voxket App Secret
participantName: "GuestUser", // Optional: Name for the user interacting with the agent
// welcomeTitle: "Welcome to Voxket!", // Optional: Custom title for the welcome screen
// welcomeSubTitle: "How can I help you today?", // Optional: Custom subtitle
// prompts: ["Tell me about your services", "What are your hours?"], // Optional: Suggested prompts
// width: "400px", // Optional: Custom width (e.g., "400px", "w-96")
// height: "600px", // Optional: Custom height (e.g., "600px", "h-[30rem]")
};
return (
<div>
<h1>My Application Integrating Voxket</h1>
<p>The Voxket Live widget is displayed below:</p>
<VoxketWidget {...widgetProps} />
</div>
);
};
export default MyCustomApp;
```
### ✅ Auto-Included Styles
As of version 1.0.22+, **CSS styles are automatically injected** when you import the component. You don't need to manually import any CSS files!
## Props
The `VoxketWidget` component accepts the following props:
| Prop | Type | Required | Default | Description |
|---------------------|--------------|----------|-------------|------------------------------------------------------------------------------------------------------------|
| `agentId` | `string` | Yes | | Your unique Voxket Agent ID. |
| `baseUrl` | `string` | Yes | | The base URL for your Voxket API services. |
| `appId` | `string` | Yes | | Your Voxket Application ID. |
| `appSecret` | `string` | Yes | | Your Voxket Application Secret. |
| `participantName` | `string` | No | `'User'` | The display name for the user interacting with the agent. |
| `className` | `string` | No | `''` | Custom CSS class to apply to the root widget container for additional styling. |
| `prompts` | `string[]` | No | `[]` | An array of suggested questions or prompts to display on the welcome screen. |
| `statusMessage` | `string` | No | `''` | A message to display on the welcome screen, potentially for agent status or custom greetings. |
| `welcomeTitle` | `string` | No | `''` | Custom title for the widget's welcome screen. |
| `welcomeSubTitle` | `string` | No | `''` | Custom subtitle for the widget's welcome screen. |
| `width` | `string` | No | `'w-96'` | Defines the widget width. Accepts Tailwind CSS classes (e.g., `w-96`) or standard CSS values (e.g., `500px`). |
| `height` | `string` | No | `'h-[25rem]'` | Defines the widget height. Accepts Tailwind CSS classes (e.g., `h-[25rem]`) or CSS values (e.g., `600px`). |
| `loadingText` | `string` | No | `''` | Text displayed while the session is initializing and connecting. |
| `suportsChatInput` | `boolean` | No | `true` | Enables or disables the text chat input feature. |
| `suportsVideoInput` | `boolean` | No | `true` | Enables or disables the user's video input feature. |
| `suportsScreenShare`| `boolean` | No | `true` | Enables or disables the screen sharing feature for the user. |
| `theme` | `'dark' \| 'light' \| 'vox'` | No | `'vox'` | Sets the widget's visual theme. |
| `onSessionStart` | `(sessionId: string) => void` | No | `undefined` | Callback fired when a session starts. Receives the session ID. |
| `onSessionEnd` | `(metrics: SessionMetrics) => void` | No | `undefined` | Callback fired when a session ends. Receives session metrics. |
| `enableSessionLogging` | `boolean` | No | `true` | Enables or disables session logging functionality. |
| `onSessionLogsUpdate` | `(logs: SessionLog[]) => void` | No | `undefined` | Callback fired when session logs are updated. Provides real-time access to session events. |
| `onSessionMetricsUpdate` | `(metrics: SessionMetrics) => void` | No | `undefined` | Callback fired when session metrics are updated. Provides real-time access to session metrics. |
*(Note: `suportsChatInput` had a typo `suportsChatInput` in some internal example files, but the correct prop name used by the widget is `suportsChatInput`.)*
## Functionality Details
- **Welcome Screen:** Greets the user and can display custom titles, subtitles, and suggested prompts. The session starts when the user initiates it from this screen.
- **Session View:** Once connected, this view handles the live interaction with the agent, including audio, video (if enabled), and chat.
- **Device Permissions:** The widget will request microphone and camera permissions as needed when the session starts.
- **Error Handling:** Basic error messages are displayed for connection issues or media device errors using toast notifications.
## Session Logging
The widget provides comprehensive session logging capabilities that allow you to capture and analyze user interactions in real-time.
### Basic Session Logging
```tsx
import VoxketWidget from '@voxket-ai/voxket-live';
function App() {
const handleSessionStart = (sessionId: string) => {
console.log('Session started:', sessionId);
};
const handleSessionEnd = (metrics: any) => {
console.log('Session ended:', metrics);
};
return (
<VoxketWidget
agentId="your-agent-id"
// ... other props
onSessionStart={handleSessionStart}
onSessionEnd={handleSessionEnd}
enableSessionLogging={true}
/>
);
}
```
### Real-time Session Data Access
Get access to session logs and metrics in real-time:
```tsx
import VoxketWidget, { SessionLog, SessionMetrics } from '@voxket-ai/voxket-live';
function App() {
const [sessionLogs, setSessionLogs] = useState<SessionLog[]>([]);
const [sessionMetrics, setSessionMetrics] = useState<SessionMetrics | null>(null);
const handleSessionLogsUpdate = (logs: SessionLog[]) => {
setSessionLogs(logs);
// Send to your analytics service
analytics.track('session_logs_update', { logCount: logs.length });
};
const handleSessionMetricsUpdate = (metrics: SessionMetrics) => {
setSessionMetrics(metrics);
// Update your dashboard
updateDashboard(metrics);
};
return (
<VoxketWidget
agentId="your-agent-id"
// ... other props
onSessionLogsUpdate={handleSessionLogsUpdate}
onSessionMetricsUpdate={handleSessionMetricsUpdate}
enableSessionLogging={true}
/>
);
}
```
### Available Session Events
- `SESSION_STARTED` - When a session begins
- `SESSION_ENDED` - When a session ends
- `PARTICIPANT_CONNECTED` - When a participant joins
- `PARTICIPANT_DISCONNECTED` - When a participant leaves
- `DATA_RECEIVED` - When a message is received
- `TRACK_PUBLISHED` - When media tracks are published
- `CONNECTION_ISSUE` - When connection problems occur
For detailed session logging documentation, see [CONSUMER_SESSION_LOGGING.md](./CONSUMER_SESSION_LOGGING.md).
## Styling
The widget is styled using Tailwind CSS. You can customize its appearance:
1. **Size:** Use the `width` and `height` props.
2. **Custom CSS:** Add your own styles by passing a `className` to the widget and defining corresponding CSS rules in your project.
3. **Tailwind Overrides:** If your project also uses Tailwind CSS, you might be able to override styles by ensuring your Tailwind configuration and selectors have higher specificity if needed.
## Contributing
This SDK is part of the Voxket AI agent marketplace. For issues, feature requests, or contributions, please refer to the main project repository or contact Voxket support. (Assuming a standard open-source or enterprise support model - adjust as needed).
## License
This SDK is [MIT Licensed](./LICENSE). (Assuming MIT from the existing LICENSE file).