# 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 (

My Application Integrating Voxket

The Voxket Live widget is displayed below:

); }; 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 ( ); } ``` ### 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([]); const [sessionMetrics, setSessionMetrics] = useState(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 ( ); } ``` ### 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).