rtAVrtAV Platform

VBot Widget Integration

The VBot widget is a ready-to-use video chat customer support bot that you can easily integrate into any web application. It provides a floating button interface with a full-featured chat experience powered by rtAV's realtime AI avatar technology.

Get Started

Download the VBot widget JavaScript file and include it in your HTML:

Download VBot Widget:

/vbot.min.js (Recommended - Minified, ~42KB)

URL: https://platform.rtav.io/vbot.min.js

/vbot.js (Development - Unminified, ~70KB)

URL: https://platform.rtav.io/vbot.js

<!DOCTYPE html>
<html>
<head>
  <title>My App with VBot</title>
</head>
<body>
  <!-- Your page content -->
  
  <!-- Include VBot widget (use .min.js for production) -->
  <script src="https://platform.rtav.io/vbot.min.js"></script>
  <script>
    // Initialize VBot when page loads
    window.addEventListener('DOMContentLoaded', () => {
      const vbot = new VBot({
        title: 'Customer Support',
        name: 'Assistant',
        face: 'your-face-id',
        voice: 'your-voice-id',
        driving: 'IdleListeningEncouraging',
        model: 'gpt-5.2',
        instructions: 'You are a helpful customer support assistant.',
        // Option 1: Use platform-hosted endpoint (recommended - no backend required)
        clientSecretsUrl: 'https://platform.rtav.io/api/vbot/client-secrets?apiKeyName=Your API Key Name',
        // Option 2: Use your own endpoint
        // clientSecretsUrl: '/api/client-secrets',
        wsUrl: 'wss://api.rtav.io/v1/realtime',
        welcome_message: 'Hello! How can I help you today?',
        color: '#4CAF50',
        label: 'Chat with AI',
        icon: 'https://example.com/logo.png',  // Optional: custom icon (URL, base64, or inline SVG)
        max_words: 100,  // Limit responses to approximately 100 words (~130 tokens)
        enableExtractPageContent: true  // Optional: automatically extract and include page content
      });
      
      // Store reference globally if needed
      window.vbotInstance = vbot;
    });
  </script>
</body>
</html>

Configuration Options

The VBot constructor accepts the following configuration options:

OptionTypeDescription
titlestringWidget title displayed in header
namestringAssistant name
facestringFace/avatar ID (from your assets)
voicestringVoice ID (from your assets)
drivingstringDriving animation (e.g., 'IdleListeningEncouraging')
modelstringLLM model (default: 'gpt-5.2')
instructionsstringSystem instructions for the AI assistant
clientSecretsUrlstringURL endpoint to get ephemeral keys (required). Use platform-hosted endpoint: https://platform.rtav.io/api/vbot/client-secrets?apiKeyName=Your Key Name (requires domain whitelisting), or your own backend endpoint.
wsUrlstringWebSocket URL (default: 'wss://api.rtav.io/v1/realtime')
welcome_messagestringMessage shown when user connects
idle_timeoutnumberIdle timeout in seconds (0 = disabled)
idle_messagestringMessage shown when idle timeout triggers
goodbye_messagestringMessage shown when user disconnects
colorstringTheme color (hex, default: '#4CAF50')
labelstringLabel text shown above collapsed icon button
iconstringCustom icon for the button. Supports: URL (e.g., 'https://example.com/logo.png'), base64 (e.g., 'data:image/png;base64,...'), or inline SVG. If not specified or image fails to load, uses default phone icon.
max_wordsnumberMaximum words per response (converted to tokens: 1 word ≈ 1.3 tokens, rounded up). Takes precedence over max_output_tokens if both are set.
max_output_tokensnumber | stringMaximum output tokens per response (integer 1-4096, or "inf" for no limit). If max_words is set, it takes precedence and this option is ignored.
enableExtractPageContentbooleanEnable automatic extraction of page content to include in assistant instructions (default: false). When enabled, the widget extracts page title and content after connection and automatically updates the session instructions.
customContentSelectorsstring[] | nullCustom CSS selectors for page content extraction (default: null). If not provided, uses default selectors: ['main article', 'article', 'main .content', '.content', '#main-content', '#content', 'main']

Response Length Limits:

Use max_words to limit responses in a more intuitive way (e.g., "limit to 100 words"). The widget automatically converts words to tokens using a 1.3:1 ratio (1 word ≈ 1.3 tokens). For example, setting max_words: 100 will limit responses to approximately 130 tokens. Alternatively, use max_output_tokens for direct token-based control.

Customizing the Icon

You can customize the VBot button icon to match your brand. Icons are displayed at 60x60 pixels. The icon supports multiple formats:

// Option 1: URL to an image (automatically sized to 60x60)
const vbot = new VBot({
  // ... other config
  icon: 'https://example.com/logo.png',
  // or use your site's favicon
  icon: 'https://example.com/favicon.ico'
});

// Option 2: Base64 encoded image (automatically sized to 60x60)
const vbot = new VBot({
  // ... other config
  icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'
});

// Option 3: Inline SVG (60x60 with matching viewBox)
const vbot = new VBot({
  // ... other config
  icon: '<svg width="60" height="60" viewBox="0 0 60 60"><circle cx="30" cy="30" r="30" fill="#4CAF50"/></svg>'
});

// Option 4: Inline SVG with larger viewBox (automatically scaled)
// If your SVG has coordinates larger than 60x60, use viewBox to scale it
const vbot = new VBot({
  // ... other config
  // SVG with 75x75 coordinates, scaled to fit 60x60 using viewBox
  icon: '<svg width="60" height="60" viewBox="0 0 75 75"><path d="M0 18.75C0 8.39466 8.39466 0 18.75 0H56.25C66.6053 0 75 8.39466 75 18.75V56.25C75 66.6053 66.6053 75 56.25 75H18.75C8.39466 75 0 66.6053 0 56.25V18.75Z" fill="#fff"/></svg>'
});

// Option 5: Update icon dynamically
window.vbotInstance.updateConfig({
  icon: 'https://example.com/new-logo.png'
});

// Remove custom icon (use default)
window.vbotInstance.updateConfig({
  icon: null
});

Icon Size:

All icons are displayed at 60x60 pixels. Images (URL or base64) are automatically scaled to fit this size.

SVG ViewBox Scaling:

For inline SVGs, use the viewBox attribute to scale larger SVGs to fit the 60x60 bounds. Set width="60" height="60" and use viewBox to match your SVG's coordinate system. For example, if your SVG uses 75x75 coordinates, use viewBox="0 0 75 75" and the browser will automatically scale it to fit the 60x60 display size.

Note: If an image URL fails to load, the widget automatically falls back to the default phone icon with circle background. For best results, use square images (60x60px or larger) with transparent backgrounds. The default icon includes a 60x60 circle background using the primary theme color.

Setting Up Client Secrets Endpoint

The VBot widget requires a backend endpoint to generate ephemeral keys. You have two options:

Option 1: Use Platform-Hosted Endpoint (Recommended)

The rtAV platform provides a hosted client-secrets endpoint that you can use directly, eliminating the need to host your own backend endpoint. This simplifies integration and reduces onboarding friction.

Step 1: Whitelist Your Domain

Go to your Whitelisted Domains page and add your domain (e.g., https://example.com).

Step 2: Get Your API Key Name

Go to your API Keys page and note the name of the API key you want to use (e.g., Production Key).

Step 3: Configure VBot with Platform Endpoint

Use the platform's hosted endpoint with your API key name as a query parameter:

// Use platform-hosted endpoint (no backend required!)
const vbot = new VBot({
  title: 'Customer Support',
  name: 'Assistant',
  face: 'your-face-id',
  voice: 'your-voice-id',
  driving: 'IdleListeningEncouraging',
  model: 'gpt-5.2',
  instructions: 'You are a helpful customer support assistant.',
  // Use platform endpoint with your API key name
  clientSecretsUrl: 'https://platform.rtav.io/api/vbot/client-secrets?apiKeyName=Production Key',
  wsUrl: 'wss://api.rtav.io/v1/realtime',
  welcome_message: 'Hello! How can I help you today?',
  color: '#4CAF50',
  label: 'Chat with AI',
  max_words: 100
});

Security Note:

The platform endpoint uses your API key name (not the actual key value) to identify your account. The actual API key is never exposed in the request, and only whitelisted domains can make cross-origin requests. This provides secure access without requiring you to host your own endpoint.

Option 2: Host Your Own Endpoint

If you prefer to host your own client-secrets endpoint, create an endpoint that accepts a POST request and returns an ephemeral key for session creation:

// Example Node.js/Express endpoint
app.post('/api/client-secrets', async (req, res) => {
  try {
    const response = await fetch('https://api.rtav.io/v1/realtime/client_secrets', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        expires_after: {
          anchor: 'created_at',
          seconds: 3600
        },
        session: {
          type: 'realtime',
          model: req.body.session?.model || 'gpt-5.2',
          instructions: req.body.session?.instructions || 'You are a helpful assistant.',
          face: req.body.session?.face,
          voice: req.body.session?.voice,
          driving: req.body.session?.driving,
          max_output_tokens: req.body.session?.max_output_tokens
        }
      })
    });
    
    const data = await response.json();
    res.json(data);
  } catch (error) {
    res.status(500).json({ error: 'Failed to create ephemeral key' });
  }
});

Updating Configuration Dynamically

You can update the VBot configuration at runtime, including instructions, without disconnecting the session:

// Update configuration dynamically
if (window.vbotInstance) {
  window.vbotInstance.updateConfig({
    instructions: 'You are now a coding assistant. Help with programming questions.',
    model: 'gpt-5.2',
    color: '#2196F3',
    label: 'Code Help',
    icon: 'https://example.com/code-icon.png',  // Update icon dynamically
    max_words: 150  // Limit to 150 words for concise coding help
  });
}

// Update only instructions (session will update via WebSocket)
window.vbotInstance.updateConfig({
  instructions: 'New instructions based on current page context...'
});

// Update response length limit dynamically
window.vbotInstance.updateConfig({
  max_words: 50  // Switch to shorter responses (converts to ~65 tokens)
});

Note: When updating instructions,model, voice,face, driving,max_words, or max_output_tokenswhile connected, the widget automatically sends a session.updatemessage to update the session without disconnecting. This allows you to change the assistant's behavior dynamically based on context. Visual properties like color, label, and iconare updated immediately in the UI without affecting the session.

Automatic Page Content Extraction

The VBot widget can automatically extract page content and include it in the assistant's instructions, allowing the bot to answer questions about the current page context. This feature is especially useful for documentation sites, product pages, or any content-rich pages where users might ask questions about what they're reading.

// Enable automatic page content extraction
const vbot = new VBot({
  title: 'Customer Support',
  name: 'Assistant',
  face: 'your-face-id',
  voice: 'your-voice-id',
  driving: 'IdleListeningEncouraging',
  model: 'gpt-5.2',
  instructions: 'You are a helpful customer support assistant.',
  clientSecretsUrl: 'https://platform.rtav.io/api/vbot/client-secrets?apiKeyName=Your API Key Name',
  wsUrl: 'wss://api.rtav.io/v1/realtime',
  welcome_message: 'Hello! How can I help you today?',
  color: '#4CAF50',
  label: 'Chat with AI',
  // Enable automatic page content extraction
  enableExtractPageContent: true
});

// With custom content selectors (for specific page structures)
const vbot = new VBot({
  // ... other config
  enableExtractPageContent: true,
  // Use custom selectors to target specific content areas
  customContentSelectors: [
    '#main-content',
    '.article-body',
    'main article',
    '.product-description'
  ]
});

How It Works:

  • After the widget connects, it automatically extracts the page title and main content
  • Content is extracted using default selectors (or your custom selectors if provided)
  • Non-content elements (scripts, styles, navigation, etc.) are automatically filtered out
  • The extracted content (limited to 5000 characters) is appended to your base instructions
  • The session is updated via session.update without disconnecting
  • Content extraction happens once per connection (reset on disconnect/reconnect)

Default Content Selectors:

If customContentSelectors is not provided, the widget uses these default selectors in order:

['main article', 'article', 'main .content', '.content', '#main-content', '#content', 'main']

The widget tries each selector until it finds content with at least 100 characters. If no suitable content is found, it falls back to extracting paragraph text from the page.

Example: Manual Page-Specific Instructions

If you prefer more control over how page content is extracted and included, you can manually update instructions based on the current page:

// Example: Manually update instructions based on page
window.addEventListener('DOMContentLoaded', () => {
  const vbot = new VBot({
    // ... initial config (without enableExtractPageContent)
  });
  
  window.vbotInstance = vbot;
  
  // Update instructions when page content changes
  function updateInstructionsForPage() {
    const pageTitle = document.title;
    const pageContent = document.body.innerText.substring(0, 500);
    
    vbot.updateConfig({
      instructions: `You are helping on a page about "${pageTitle}". 
      Context: ${pageContent}
      Provide helpful assistance related to this content.`
    });
  }
  
  // Update when page loads
  updateInstructionsForPage();
  
  // Update on navigation (if using SPA)
  // window.addEventListener('popstate', updateInstructionsForPage);
});

Widget Features

  • Video Avatar: Real-time video of the AI assistant speaking
  • Text Chat: Type messages and receive text responses
  • Voice Input: Toggle microphone for voice conversations
  • Conversation History: View past messages in the chat
  • Page Content Extraction: Automatically extract and include page content in assistant context
  • Collapsible UI: Minimizes to a floating button when not in use
  • Customizable: Theme color, labels, messages, and custom icons
  • Idle Management: Automatic timeout and goodbye messages

Integration with React/Next.js

If you're using React or Next.js, you can integrate VBot with our React Context API for per-page configuration:

// Using VBotContext in a React component
import { useEffect } from 'react'
import { useVBot } from '@/contexts/VBotContext'

export default function MyPage() {
  const { setConfig } = useVBot()
  
  useEffect(() => {
    setConfig({
      title: 'Page Support',
      name: 'Helper',
      instructions: 'Help with this page...',
      label: 'Get Help',
      enabled: true,
      // ... other config
    })
    
    return () => setConfig(null) // Cleanup
  }, [setConfig])
  
  return <div>Page content</div>
}

For more details on React integration, see the React Integration Guide.

Browser Compatibility

The VBot widget requires modern browsers with support for:

  • WebSocket API
  • Web Audio API (AudioContext, AudioWorklet)
  • MediaDevices API (for microphone access)
  • ES6+ JavaScript features

Supported browsers: Chrome 66+, Firefox 60+, Safari 14.1+, Edge 79+

Next Steps