\n
\n );\n}\n```\n\n### ๐ง **Option 2: Client SDK (Any Framework)**\n\nUse with vanilla JavaScript, Vue, Angular, or any framework:\n\n```javascript\nimport { VoxketClient } from '@voxket-ai/voxket-live';\n\n// Create client\nconst client = new VoxketClient({\n appId: \"your-app-id\",\n appSecret: \"your-app-secret\",\n baseUrl: \"https://your.voxket.api\",\n agentId: \"your-agent-id\",\n participantName: \"User\"\n});\n\n// Connect and render UI\nawait client.connect();\nclient.renderUI({\n target: '#voxket-container', // CSS selector or HTMLElement\n channels: ['voice', 'chat'], // add a video channel for AI-avatar calls (see Video below)\n theme: 'dark',\n displayType: 'widget',\n autoStart: true\n});\n```\n\n### ๐๏ธ **Option 3: Advanced React Integration**\n\nFull React ecosystem with providers and hooks:\n\n```tsx\nimport { VoxketProvider, useVoxket } from '@voxket-ai/voxket-live';\n\nfunction App() {\n return (\n My App
\n\n \n {session &&
\n );\n}\n```\n\n## ๐ฅ **Video: AI Avatar Calls**\n\nThe `video` modality is a face-to-face call with a real-time AI avatar. It doesn't use LiveKit or a Voxket session: the avatar vendor runs the conversation (speech-to-text, LLM and voice) for a persona configured with that vendor. The widget shows it with the same header, message bubbles and call controls as voice and chat: mute, video on/off, transcript (with a box to type to the avatar), stop speaking and end call. [Anam](https://anam.ai) is built in.\n\n### 1. Set up the persona (once, in [Anam Lab](https://lab.anam.ai))\n\n1. Create a persona: avatar, voice, system prompt and knowledge.\n2. In the persona's widget settings, add every origin the widget runs on to **Allowed Domains**, e.g. `https://www.example.com`, plus `http://localhost:3000` for local development.\n3. Copy the persona id.\n\n### 2. Turn on the `video` channel\n\nAdd a `video` channel with its avatar. Everything else stays as you have it.\n\n**React**\n\n```tsx\nSession active: {session.id}
}\n\n
\n );\n}\n```\n\n### ๐ฏ **Interactive UI Examples**\n- **๐ Forms & Surveys** - Collect user feedback\n- **๐ Data Visualization** - Show charts and graphs \n- **๐ Product Catalogs** - Display interactive product lists\n- **๐
Appointment Scheduling** - Calendar integrations\n- **๐ณ Payment Flows** - Secure payment processing\n- **๐ฎ Custom Games** - Interactive experiences\n\n## ๐ก **Event System**\n\n### ๐ **Connection Events**\n\n```javascript\nclient.on('connection.connected', () => {\n console.log('โ
Connected to Voxket');\n});\n\nclient.on('connection.disconnected', (reason) => {\n console.log('โ Disconnected:', reason);\n});\n\nclient.on('connection.error', (error) => {\n console.error('๐จ Connection error:', error);\n});\n```\n\n## ๐ **Custom Event System**\n\n### ๐ก **Register Event Emitters**\n\nRegister custom event emitters to listen for LiveKit text stream topics:\n\n```typescript\nimport { VoxketClient } from '@voxket-ai/voxket-live';\n\nconst client = new VoxketClient(config);\n\n// Register an event emitter for custom events\nclient.registerEventEmitter('custom_event_topic', (data) => {\n console.log('Custom event received:', data);\n // Handle your custom business logic\n handleCustomEvent(data);\n});\n\n// Register multiple event emitters\nclient.registerEventEmitter('user_action', (actionData) => {\n console.log('User action:', actionData);\n analytics.track('user_action', actionData);\n});\n\nclient.registerEventEmitter('system_notification', (notification) => {\n showNotification(notification);\n});\n```\n\n### ๐ฏ **Event Listener Registration**\n\nRegister event listeners for any SDK events with automatic cleanup:\n\n```typescript\n// Register event listeners with automatic unsubscribe\nconst unsubscribe = client.registerEventListener('chat.message.received', (message) => {\n console.log('New message:', message);\n updateUI(message);\n});\n\n// Manual cleanup when needed\nunsubscribe();\n\n// Register multiple listeners\nclient.registerEventListener('connection.connected', () => {\n console.log('Connected to Voxket!');\n updateConnectionStatus('connected');\n});\n\nclient.registerEventListener('agent.thinking', () => {\n showTypingIndicator();\n});\n```\n\n### ๐ข **Business Integration Examples**\n\n#### **Real-time Notifications**\n```typescript\n// Listen for agent-triggered notifications\nclient.registerEventEmitter('agent_notification', (data) => {\n // Show toast notification\n showToast({\n title: data.title,\n message: data.message,\n type: data.type\n });\n});\n\n// Listen for system updates\nclient.registerEventEmitter('system_update', (updateInfo) => {\n if (updateInfo.type === 'maintenance') {\n showMaintenanceWarning(updateInfo.schedule);\n }\n});\n```\n\n#### **Custom Analytics Integration**\n```typescript\n// Track custom business events\nclient.registerEventEmitter('business_event', (eventData) => {\n // Send to your analytics platform\n analytics.track(eventData.event_name, {\n ...eventData.properties,\n timestamp: new Date().toISOString(),\n session_id: client.getCurrentSession()?.id\n });\n});\n\n// Example: Track user interactions\nclient.registerEventEmitter('user_interaction', (interaction) => {\n mixpanel.track('Voxket User Interaction', {\n interaction_type: interaction.type,\n interaction_data: interaction.data,\n user_id: getCurrentUserId()\n });\n});\n```\n\n#### **Workflow Automation**\n```typescript\n// Trigger business workflows\nclient.registerEventEmitter('workflow_trigger', (workflowData) => {\n switch (workflowData.workflow_type) {\n case 'lead_qualification':\n triggerLeadQualificationWorkflow(workflowData.lead_data);\n break;\n case 'support_escalation':\n escalateToHumanAgent(workflowData.ticket_data);\n break;\n case 'appointment_booking':\n processAppointmentRequest(workflowData.appointment_data);\n break;\n }\n});\n```\n\n### ๐ฌ **Chat & Messaging Events**\n\n```javascript\nclient.on('chat.message.received', (message) => {\n console.log('๐ฌ New message:', message);\n displayMessage(message);\n});\n\nclient.on('chat.message.sent', (message) => {\n console.log('๐ค Message sent:', message);\n logOutgoingMessage(message);\n});\n\nclient.on('transcription.received', (transcription) => {\n console.log('๐ค Voice transcription:', transcription);\n displayTranscription(transcription);\n});\n```\n\n---\n\n## ๐ **Rich Content & Markdown Support**\n\nThe Voxket SDK automatically detects and renders rich content in chat messages, including **GitHub Flavored Markdown (GFM)** with full support for tables, links, code blocks, and more.\n\n### โจ **Supported Markdown Features**\n\n#### ๐ **Tables with Embedded Links**\n\nAgent messages can include formatted tables with clickable links embedded within table cells:\n\n```markdown\n| CRA Partner | Registration Link | Description |\n|-------------|-------------------|-------------|\n| **CAMS** | [Click here to register](https://app.camsnps.in/register) | Computer Age Management Services |\n| **KFintech** | [Register now](https://kfintech.com/register) | Widely used platform |\n```\n\n**Renders as:**\n\n| CRA Partner | Registration Link | Description |\n|-------------|-------------------|-------------|\n| **CAMS** | [Click here to register](https://app.camsnps.in/register) | Computer Age Management Services |\n| **KFintech** | [Register now](https://kfintech.com/register) | Widely used platform |\n\n#### ๐ **Links**\n\n```markdown\nCheck out [Voxket AI](https://voxket.ai) for more information!\n\nVisit https://voxket.ai (auto-linked)\n```\n\n**Features:**\n- โ
Embedded links in text: `[text](url)`\n- โ
Auto-detection of bare URLs\n- โ
External link icon indicator\n- โ
Opens in new tab with `target=\"_blank\"`\n- โ
Proper security with `rel=\"noopener noreferrer\"`\n\n#### ๐ **Lists**\n\n```markdown\n**Unordered Lists:**\n- Item one\n- Item two\n - Nested item\n - Another nested item\n\n**Ordered Lists:**\n1. First step\n2. Second step\n3. Third step\n```\n\n#### ๐ป **Code Blocks**\n\n````markdown\nInline code: `const greeting = \"Hello\"`\n\n```javascript\n// Syntax-highlighted code block\nfunction greet(name) {\n return `Hello, ${name}!`;\n}\n```\n````\n\n**Features:**\n- โ
Syntax highlighting for 180+ languages\n- โ
Inline code with backticks\n- โ
Multi-line code blocks with language specification\n- โ
Theme-aware styling (dark/light modes)\n\n#### ๐ **Headings & Formatting**\n\n```markdown\n# Heading 1\n## Heading 2\n### Heading 3\n\n**Bold text**\n*Italic text*\n~~Strikethrough~~\n\n> Blockquote for important information\n```\n\n#### ๐ผ๏ธ **Images**\n\n```markdown\n\n```\n\n**Features:**\n- โ
Automatic lazy loading\n- โ
Responsive sizing\n- โ
Rounded corners with shadow\n\n---\n\n### ๐จ **Theming for Rich Content**\n\nAll markdown elements automatically adapt to your chosen theme:\n\n```tsx\nRate your experience
\n\n
\n );\n}\n\n// Register the component\nawait client.registerFrontendRPC(\n 'customer_satisfaction_survey',\n SurveyForm,\n 'modal' // Can be 'embedded', 'modal', or 'fullscreen'\n);\n```\n\n### ๐ **E-commerce Product Showcase**\n\n```typescript\nfunction ProductCatalog({ handler, data }: VoxketInteractiveViewProps) {\n const [selectedProduct, setSelectedProduct] = useState(null);\n \n const products = data?.products || [];\n\n const handleSelectProduct = (product: any) => {\n handler?.didSuccess({\n selected_product: product,\n action: 'add_to_cart'\n });\n };\n\n return (\n \n {data?.title || 'Rate Your Experience'}\n
\n \n\n \n
\n\n \n {[1,2,3,4,5].map(num => (\n setRating(num)}\n className={`w-10 h-10 rounded ${\n rating >= num ? 'bg-blue-500 text-white' : 'bg-gray-200'\n }`}\n >\n {num}\n \n ))}\n
\n \n \n setFeedback(e.target.value)}\n className=\"w-full p-2 border rounded\"\n rows={3}\n />\n
\n\n \n \n \n
\n \n
\n );\n}\n```\n\n### ๐
**Appointment Scheduler**\n\n```typescript\nfunction AppointmentBooker({ handler, data }: VoxketInteractiveViewProps) {\n const [selectedSlot, setSelectedSlot] = useState('');\n const [contactInfo, setContactInfo] = useState({ name: '', email: '' });\n \n const availableSlots = data?.available_slots || [];\n\n const handleBooking = () => {\n handler?.didSuccess({\n appointment: {\n slot: selectedSlot,\n contact: contactInfo,\n type: data?.appointment_type,\n booked_at: new Date().toISOString()\n }\n });\n };\n\n return (\n Recommended Products
\n\n {products.map((product: any) => (\n
\n \n 
\n handleSelectProduct(product)}\n className=\"mt-2 w-full bg-blue-500 text-white py-2 rounded\"\n >\n Add to Cart\n \n
\n ))}\n {product.name}
\n${product.price}
\n\n \n Book Appointment\n \n
\n );\n}\n```\n\n## ๐ **Session Analytics & Metrics**\n\n### ๐ **Session Metrics Interface**\n\n```typescript\ninterface SessionMetrics {\n sessionId: string;\n startTime: Date;\n endTime?: Date;\n duration?: number; // Duration in milliseconds\n totalMessages: number; // Total messages exchanged\n connectionIssues: number; // Network issues count\n participantCount: number; // Number of participants\n events: SessionLog[]; // All session events\n}\n\ninterface SessionLog {\n timestamp: Date;\n event: string; // Event type\n data?: any; // Event data\n sessionId?: string; // Associated session\n participantId?: string; // Participant who triggered event\n}\n```\n\n### ๐ **Analytics Integration Examples**\n\n```typescript\n// Google Analytics 4\nclient.on('session.created', (session) => {\n gtag('event', 'voxket_session_start', {\n session_id: session.id,\n agent_id: session.agentId,\n modalities: session.activeModalities.join(',')\n });\n});\n\n// Mixpanel\nclient.on('chat.message.received', (message) => {\n mixpanel.track('Voxket Message Received', {\n session_id: client.getCurrentSession()?.id,\n message_type: message.sender.type,\n message_length: message.content.length,\n timestamp: message.timestamp\n });\n});\n\n// Custom Analytics\nconst analyticsTracker = {\n trackSession: (event: string, data: any) => {\n fetch('/api/analytics', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ event, data, timestamp: new Date() })\n });\n }\n};\n\nclient.on('session.ended', (session, metrics) => {\n analyticsTracker.trackSession('session_completed', {\n duration: metrics.duration,\n message_count: metrics.totalMessages,\n quality_score: calculateQualityScore(metrics)\n });\n});\n```\n\n## ๐ ๏ธ **Enterprise Features**\n\n### ๐ **Security & Compliance**\n\n```typescript\n// HIPAA-compliant configuration\nconst healthcareClient = new VoxketClient({\n appId: \"healthcare-app\",\n appSecret: \"hipaa-compliant-secret\",\n baseUrl: \"https://secure-api.voxket.com\",\n agentId: \"patient-support\",\n \n // Disable session logging for compliance\n enableSessionLogging: false,\n \n onSessionStart: (sessionId) => {\n // HIPAA audit logging\n complianceLogger.logPatientInteraction({\n sessionId,\n patientId: getCurrentPatient().id,\n timestamp: new Date(),\n actionType: 'SESSION_START'\n });\n }\n});\n\n// Only use secure text-based modalities\nawait healthcareClient.connect();\nhealthcareClient.renderUI({\n modality: ['chat'], // Text only for security\n theme: 'light',\n enableSessionLogging: false\n});\n```\n\n### ๐ข **Multi-tenant Architecture**\n\n```typescript\nclass TenantManager {\n private clients: MapBook Appointment
\n \n\n \n
\n\n \n {availableSlots.map((slot: string) => (\n setSelectedSlot(slot)}\n className={`p-2 rounded border ${\n selectedSlot === slot \n ? 'bg-blue-500 text-white' \n : 'bg-gray-50 hover:bg-gray-100'\n }`}\n >\n {slot}\n \n ))}\n
\n \n setContactInfo({...contactInfo, name: e.target.value})}\n className=\"w-full p-2 border rounded mb-2\"\n />\n setContactInfo({...contactInfo, email: e.target.value})}\n className=\"w-full p-2 border rounded\"\n />\n
\n\n Loading...
;\n \n return \n {isConnecting &&
\n );\n}\n```\n\n#### **2. Progressive Enhancement**\n```typescript\n// Start with basic features, enhance based on capabilities\nconst client = new VoxketClient(config);\n\n// Check agent capabilities\nconst agentInfo = client.getCurrentAgentInfo();\nconst supportedModalities = agentInfo?.modality_supported || ['chat'];\n\n// Render appropriate UI\nclient.renderUI({\n modality: supportedModalities.includes('voice') \n ? ['voice', 'chat'] \n : ['chat'],\n theme: userPreferences.theme || 'vox'\n});\n```\n\n#### **3. Accessibility**\n```typescript\n// Ensure keyboard navigation and screen reader support\nConnecting to support...
}\n {connectionError && {connectionError}
}\n \n \n \n {isActive && (\n
\n );\n}\n```\n\n### ๐ **Vue 3 Composition API**\n```typescript\n\n \n ๐ข Support session active\n
\n )}\n \n \n
\n )}\n Session Summary
\nDuration: {Math.round(sessionMetrics.duration! / 1000)}s
\nMessages: {sessionMetrics.totalMessages}
\n\n \n \n
\n\n\n\n```\n\n### ๐
ฐ๏ธ **Angular Component**\n```typescript\n// voxket.service.ts\nimport { Injectable } from '@angular/core';\nimport { VoxketClient } from '@voxket-ai/voxket-live';\n\n@Injectable({ providedIn: 'root' })\nexport class VoxketService {\n private client: VoxketClient;\n\n constructor() {\n this.client = new VoxketClient({\n appId: environment.voxketAppId,\n appSecret: environment.voxketAppSecret,\n baseUrl: environment.voxketBaseUrl\n });\n }\n\n async startChat(containerId: string, agentId: string) {\n await this.client.connect();\n this.client.renderUI({\n target: `#${containerId}`,\n agentId,\n modality: ['chat'],\n theme: 'dark'\n });\n }\n\n disconnect() {\n this.client.removeAllUI();\n this.client.disconnect();\n }\n}\n\n// chat.component.ts\n@Component({\n selector: 'app-chat',\n template: `\n \n \n \n
\n `\n})\nexport class ChatComponent implements OnDestroy {\n isLoading = false;\n\n constructor(private voxketService: VoxketService) {}\n\n async startChat() {\n this.isLoading = true;\n try {\n await this.voxketService.startChat('angular-voxket-container', 'support-agent');\n } finally {\n this.isLoading = false;\n }\n }\n\n ngOnDestroy() {\n this.voxketService.disconnect();\n }\n}\n```\n\n### ๐ช **Svelte Integration**\n```svelte\n\n\n\n\n \n \n \n
\n\n\n```\n\n## ๐ **Deployment & Production**\n\n### ๐ญ **Production Checklist**\n\n```typescript\n// โ
Production configuration\nconst client = new VoxketClient({\n appId: process.env.VOXKET_APP_ID!, // From secure environment\n appSecret: process.env.VOXKET_APP_SECRET!, // From secure environment\n baseUrl: process.env.VOXKET_BASE_URL!, // Production URL\n debug: false, // Disable debug logs\n \n // Error tracking\n onError: (error) => {\n // Send to error monitoring service (Sentry, etc.)\n console.error('Voxket error:', error);\n errorTracker.captureException(error);\n }\n});\n\n// โ
Health check endpoint\napp.get('/health/voxket', async (req, res) => {\n try {\n // Test Voxket API connectivity\n const response = await fetch(`${process.env.VOXKET_BASE_URL}/health`);\n if (response.ok) {\n res.status(200).json({ status: 'healthy' });\n } else {\n res.status(503).json({ status: 'unhealthy' });\n }\n } catch (error) {\n res.status(503).json({ status: 'error', error: error.message });\n }\n});\n```\n\n### ๐ **Monitoring & Analytics**\n\n```typescript\n// Production monitoring setup\nclass VoxketMonitoring {\n static setupMonitoring(client: VoxketClient) {\n // Connection monitoring\n client.on('connection.connected', () => {\n this.trackEvent('voxket_connected');\n });\n \n client.on('connection.error', (error) => {\n this.trackError('voxket_connection_error', error);\n });\n \n // Session analytics\n client.on('session.created', (session) => {\n this.trackEvent('voxket_session_start', {\n session_id: session.id,\n agent_id: session.agentId\n });\n });\n \n // Performance monitoring\n const startTime = Date.now();\n client.on('connection.connected', () => {\n const connectionTime = Date.now() - startTime;\n this.trackTiming('voxket_connection_time', connectionTime);\n });\n }\n \n private static trackEvent(event: string, data?: any) {\n // Send to your analytics service\n analytics.track(event, data);\n }\n \n private static trackError(event: string, error: Error) {\n // Send to error monitoring\n errorTracker.captureException(error, { tags: { component: 'voxket' } });\n }\n \n private static trackTiming(metric: string, duration: number) {\n // Send to performance monitoring\n performanceTracker.timing(metric, duration);\n }\n}\n\n// Apply monitoring\nVoxketMonitoring.setupMonitoring(client);\n```\n\n## ๐ **API Reference Summary**\n\n### ๐๏ธ **Core Classes**\n\n- **`VoxketClient`** - Main SDK client for programmatic control\n- **`VoxketWidget`** - React component for easy integration \n- **`VoxketProvider`** - React context provider for advanced usage\n\n### ๐จ **Display Types**\n\n- **`widget`** - Embedded widget mode\n- **`popup`** - Floating popup mode \n- **`fullscreen`** - Full-screen overlay mode\n\n### ๐ญ **Themes**\n\n- **`vox`** - Default Voxket branded theme\n- **`dark`** - Dark mode theme\n- **`light`** - Light mode theme\n- **Custom** - Create your own theme object\n\n### ๐ช **Modalities**\n\n- **`voice`** - Voice conversations with transcription\n- **`chat`** - Text-based messaging\n- **`video`** - AI-avatar call; requires the `avatar` prop ([details](#-video-ai-avatar-calls))\n\nA `video` modality without an `avatar`, or a `screen_share` modality from an older integration or backend, is ignored and reported through `onError` (`CONFIGURATION_ERROR`); if nothing else is left, the session starts as `voice`.\n\n### ๐ก **Event Categories**\n\n- **Connection Events** - `connection.*`\n- **Session Events** - `session.*` \n- **Chat Events** - `chat.*`\n- **Agent Events** - `agent.*`\n- **Media Events** - `track.*`\n- **RPC Events** - `rpc.*`\n\n## ๐ค **Community & Support**\n\n### ๐ **Documentation**\n- [API Reference](https://docs.voxket.com/api)\n- [Integration Guides](https://docs.voxket.com/guides)\n- [Example Projects](https://github.com/voxket-ai/examples)\n\n### ๐ **Getting Help**\n- [GitHub Issues](https://github.com/voxket-ai/voxket-web-sdk/issues)\n- [Discord Community](https://discord.gg/voxket)\n- [Support Email](mailto:support@voxket.com)\n\n### ๐งช **Contributing**\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n### ๐ **License**\nMIT License - see [LICENSE](./LICENSE) file for details.\n\n---\n\n## ๐ **Ready to Get Started?**\n\n1. **Install the SDK**: `npm install @voxket-ai/voxket-live`\n2. **Get your credentials** from the [Voxket Dashboard](https://dashboard.voxket.com)\n3. **Choose your integration method** (Widget, Client SDK, or Advanced React)\n4. **Start building amazing AI-powered experiences!**\n\n### ๐ก **Need help?** \nCheck out our [Quick Start Guide](https://docs.voxket.com/quickstart) or join our [Discord community](https://discord.gg/voxket) for real-time support!\n\n---\n\n**Built with โค๏ธ by the Voxket team**\n","readmeFilename":"README.md"}