@voiceai/sdk

Voice AI Bot SDK - Easy integration for voice and text chat widgets.

Installation

npm install @voiceai/sdk
# or
yarn add @voiceai/sdk
# or
pnpm add @voiceai/sdk

Quick Start

Using ES Modules (React, Vue, etc.)

import { createVoiceBot } from '@voiceai/sdk';

const bot = createVoiceBot({
  apiKey: 'vb_live_your_api_key',
  serverUrl: 'wss://api.yourserver.com/ws',
  domain: 'ecommerce',
  theme: {
    primaryColor: '#6366f1',
  },
});

// The widget will auto-initialize and show

Using Script Tag (CDN)

<script src="https://unpkg.com/@voiceai/sdk/dist/browser.browser.js"></script>
<script>
  const bot = VoiceBot.createVoiceBot({
    apiKey: 'vb_live_your_api_key',
    serverUrl: 'wss://api.yourserver.com/ws',
    domain: 'ecommerce',
  });
</script>

Configuration Options

interface VoiceBotConfig {
  // Required
  apiKey: string;              // Your API key from the dashboard

  // Server
  serverUrl?: string;          // WebSocket server URL (default: wss://api.voiceai.io/ws)
  
  // Behavior
  domain?: 'ecommerce' | 'healthcare' | 'support' | 'general';
  voiceEnabled?: boolean;      // Enable voice input (default: true)
  autoInit?: boolean;          // Auto-initialize on creation (default: true)
  autoShow?: boolean;          // Show widget immediately (default: true)
  
  // Positioning
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  containerId?: string;        // Mount in specific element instead of floating

  // Theming
  theme?: {
    primaryColor?: string;     // Brand color (default: #007bff)
    backgroundColor?: string;  // Widget background (default: #ffffff)
    textColor?: string;        // Text color (default: #333333)
    fontFamily?: string;       // Font family
    borderRadius?: string;     // Border radius (default: 12px)
    customCss?: string;        // Additional CSS
  };

  // User context (for personalization & analytics)
  userContext?: {
    userId?: string;
    email?: string;
    name?: string;
    metadata?: Record<string, unknown>;
  };

  // Event callbacks
  callbacks?: {
    onReady?: () => void;
    onConnect?: () => void;
    onDisconnect?: () => void;
    onMessageSent?: (message: ChatMessage) => void;
    onMessageReceived?: (message: ChatMessage) => void;
    onError?: (error: VoiceBotError) => void;
    onVoiceStart?: () => void;
    onVoiceEnd?: (duration: number) => void;
    onOpen?: () => void;
    onClose?: () => void;
  };
}

API Methods

const bot = createVoiceBot({ apiKey: '...' });

// Control visibility
bot.open();           // Open the chat widget
bot.close();          // Minimize the widget
bot.toggle();         // Toggle open/closed

// Send messages
bot.sendMessage('Hello!');

// Get chat history
const messages = bot.getMessages();
bot.clearMessages();

// Check status
bot.isConnected();    // Returns boolean
bot.isOpen();         // Returns boolean

// Update configuration
bot.updateConfig({ theme: { primaryColor: '#ff0000' } });

// Cleanup
bot.destroy();

Examples

React Integration

import { useEffect, useRef } from 'react';
import { createVoiceBot, VoiceBotInstance } from '@voiceai/sdk';

function App() {
  const botRef = useRef<VoiceBotInstance | null>(null);

  useEffect(() => {
    botRef.current = createVoiceBot({
      apiKey: process.env.REACT_APP_VOICEBOT_API_KEY!,
      serverUrl: 'wss://api.yourserver.com/ws',
      callbacks: {
        onMessageReceived: (msg) => console.log('New message:', msg),
      },
    });

    return () => {
      botRef.current?.destroy();
    };
  }, []);

  return <div>Your app content</div>;
}

Vue Integration

<script setup>
import { onMounted, onUnmounted, ref } from 'vue';
import { createVoiceBot } from '@voiceai/sdk';

const bot = ref(null);

onMounted(() => {
  bot.value = createVoiceBot({
    apiKey: import.meta.env.VITE_VOICEBOT_API_KEY,
    serverUrl: 'wss://api.yourserver.com/ws',
  });
});

onUnmounted(() => {
  bot.value?.destroy();
});
</script>

Embedded in Specific Container

<div id="chat-container"></div>

<script>
  const bot = VoiceBot.createVoiceBot({
    apiKey: 'vb_live_xxx',
    containerId: 'chat-container',
    autoShow: true,
  });
</script>

License

MIT