@voxdb/chat-widget

A beautiful, AI-powered customer support chat widget for React applications. Embed intelligent, conversational customer support directly into your website with just a few lines of code.

✨ Features

• 🤖 AI-Powered Responses - Natural language understanding powered by advanced AI
• 💬 Real-Time Chat - WebSocket support for instant messaging
• 🎨 Customizable - Themes, colors, and positioning options
• 📱 Mobile Responsive - Works seamlessly on all devices
• 🔒 Secure - API key authentication and secure connections
• 🌓 Dark/Light Mode - System-aware theme support
• 📝 Markdown Support - Rich text rendering with code blocks
• 🎯 Event Callbacks - Track user interactions and messages
• ♿ Accessible - Keyboard navigation and focus management
• 🔔 Unread Badge - Visual indicator for new messages

📦 Installation

npm install @voxdb/chat-widget
# or
yarn add @voxdb/chat-widget
# or
pnpm add @voxdb/chat-widget

🚀 Quick Start

Basic Usage

import React from 'react';
import { VoxDBChatWidget } from '@voxdb/chat-widget';
// CSS is automatically included - no separate import needed!

function App() {
  return (
    <VoxDBChatWidget
      apiKey="sk_live_your_api_key_here"
      companyId={123}
    />
  );
}

With Customization

import React from 'react';
import { VoxDBChatWidget } from '@voxdb/chat-widget';
import '@voxdb/chat-widget/dist/index.css';

function App() {
  return (
    <VoxDBChatWidget
      apiKey="sk_live_your_api_key_here"
      companyId={123}
      apiBaseUrl="https://api.voxdb.dev"
      position="bottom-right"
      primaryColor="#6366f1"
      theme="system"
      customerEmail="[email protected]"
      customerName="John Doe"
      onOpen={() => console.log('Chat opened')}
      onClose={() => console.log('Chat closed')}
      onMessageSend={(message) => console.log('Sent:', message)}
      onMessageReceived={(message) => console.log('Received:', message)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

📖 API Reference

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | apiKey | string | ✅ Yes | - | Your VoxDB API key (starts with sk_live_ or sk_test_) | | companyId | number | ✅ Yes | - | Your company ID from VoxDB dashboard | | apiBaseUrl | string | ❌ No | 'https://api.voxdb.dev' | API base URL (for self-hosted instances) | | position | 'bottom-right' \| 'bottom-left' | ❌ No | 'bottom-right' | Widget position on screen | | primaryColor | string | ❌ No | '#6366f1' | Primary color for widget (hex format) | | customerEmail | string | ❌ No | - | Pre-fill customer email for personalization | | customerName | string | ❌ No | - | Pre-fill customer name for personalization | | theme | 'light' \| 'dark' \| 'system' | ❌ No | 'system' | Widget theme (system follows OS preference) | | onOpen | () => void | ❌ No | - | Callback when chat widget opens | | onClose | () => void | ❌ No | - | Callback when chat widget closes | | onMessageSend | (message: string) => void | ❌ No | - | Callback when user sends a message | | onMessageReceived | (message: ChatMessage) => void | ❌ No | - | Callback when AI responds | | onError | (error: string) => void | ❌ No | - | Callback for error handling |

TypeScript Types

interface VoxDBChatWidgetProps {
  apiKey: string;
  companyId: number;
  apiBaseUrl?: string;
  position?: 'bottom-right' | 'bottom-left';
  primaryColor?: string;
  customerEmail?: string;
  customerName?: string;
  theme?: 'light' | 'dark' | 'system';
  onOpen?: () => void;
  onClose?: () => void;
  onMessageSend?: (message: string) => void;
  onMessageReceived?: (message: ChatMessage) => void;
  onError?: (error: string) => void;
}

interface ChatMessage {
  id: string;
  conversation_id: string;
  sender_type: 'customer' | 'ai' | 'admin';
  sender_id?: number;
  message: string;
  created_at: string;
  meta?: any;
}

🔑 Getting Your API Key

1. Log in to your VoxDB Dashboard
2. Navigate to Settings → API Keys
3. Click "Create API Key"
4. Copy the API key (⚠️ it's only shown once!)
5. Use it in your widget configuration

Note: API keys start with sk_live_ for production or sk_test_ for testing.

🎨 Customization Examples

Custom Colors

<VoxDBChatWidget
  apiKey="sk_live_..."
  companyId={123}
  primaryColor="#ff6b6b" // Custom red color
/>

Dark Theme

<VoxDBChatWidget
  apiKey="sk_live_..."
  companyId={123}
  theme="dark"
/>

Pre-fill Customer Info

<VoxDBChatWidget
  apiKey="sk_live_..."
  companyId={123}
  customerEmail={user.email}
  customerName={user.name}
/>

Track User Interactions

<VoxDBChatWidget
  apiKey="sk_live_..."
  companyId={123}
  onOpen={() => {
    // Track chat opened event
    analytics.track('chat_opened');
  }}
  onMessageSend={(message) => {
    // Log user messages
    console.log('User sent:', message);
  }}
  onMessageReceived={(message) => {
    // Track AI responses
    analytics.track('ai_response_received', {
      messageLength: message.message.length
    });
  }}
  onError={(error) => {
    // Handle errors
    errorReporting.captureException(new Error(error));
  }}
/>

🌐 Framework Support

React (16.8+)

import { VoxDBChatWidget } from '@voxdb/chat-widget';
// CSS is automatically included - no separate import needed!

Next.js

// pages/_app.tsx or app/layout.tsx
import { VoxDBChatWidget } from '@voxdb/chat-widget';
import '@voxdb/chat-widget/dist/index.css';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <VoxDBChatWidget
        apiKey={process.env.NEXT_PUBLIC_VOXDB_API_KEY}
        companyId={Number(process.env.NEXT_PUBLIC_VOXDB_COMPANY_ID)}
      />
    </>
  );
}

Vite

// main.tsx
import { VoxDBChatWidget } from '@voxdb/chat-widget';
import '@voxdb/chat-widget/dist/index.css';

🔧 Advanced Usage

Environment Variables

For security, store your API key in environment variables:

# .env.local
NEXT_PUBLIC_VOXDB_API_KEY=sk_live_your_api_key_here
NEXT_PUBLIC_VOXDB_COMPANY_ID=123

<VoxDBChatWidget
  apiKey={process.env.NEXT_PUBLIC_VOXDB_API_KEY!}
  companyId={Number(process.env.NEXT_PUBLIC_VOXDB_COMPANY_ID)}
/>

Conditional Rendering

{process.env.NODE_ENV === 'production' && (
  <VoxDBChatWidget
    apiKey={process.env.NEXT_PUBLIC_VOXDB_API_KEY!}
    companyId={Number(process.env.NEXT_PUBLIC_VOXDB_COMPANY_ID)}
  />
)}

Dynamic Customer Info

const [customerInfo, setCustomerInfo] = useState(null);

useEffect(() => {
  // Fetch customer info from your auth system
  fetchCustomerInfo().then(setCustomerInfo);
}, []);

return (
  <VoxDBChatWidget
    apiKey="sk_live_..."
    companyId={123}
    customerEmail={customerInfo?.email}
    customerName={customerInfo?.name}
  />
);

🐛 Troubleshooting

Widget Not Appearing

1. Check CSS import: Make sure you've imported the CSS file

   import '@voxdb/chat-widget/dist/index.css';

2. Verify API key: Ensure your API key is valid and active

3. Check console: Look for validation errors in browser console

4. Network issues: Check if API endpoint is accessible

Messages Not Sending

1. Check API key permissions: Ensure API key has chat permissions
2. Verify company ID: Make sure company ID matches your account
3. Check network tab: Look for failed API requests
4. WebSocket issues: Check if WebSocket connections are blocked

Styling Issues

1. CSS conflicts: Widget uses CSS variables - check for conflicts
2. Z-index: Widget has z-index: 9999 - adjust if needed
3. Theme: Try setting explicit theme instead of 'system'

TypeScript Errors

# Install React types if missing
npm install --save-dev @types/react @types/react-dom

🔒 Security Best Practices

1. Never commit API keys to version control
2. Use environment variables for API keys
3. Restrict API key permissions in VoxDB dashboard
4. Use HTTPS in production
5. Rotate API keys regularly

📝 License

MIT © VoxDB

🤝 Support

• Documentation: docs.voxdb.dev
• Issues: GitHub Issues
• Email: [email protected]

🚀 Changelog

1.0.0

• Initial release
• AI-powered chat widget
• Dark/light/system themes
• Markdown support
• Event callbacks
• Mobile responsive design
• WebSocket support

Made with ❤️ by VoxDB