@buzztrail-ai/engage

AI-powered video conversations for any website platform.

Overview

@buzztrail-ai/engage enables AI-powered video conversations on any website platform. Add an interactive AI presenter to your site in minutes - no complex setup required.

⚠️ Account Required: You need an active BuzzTrail account to use this package. Sign up at buzztrail.ai to get your customer ID and configure your AI presenter.

Features

• Interactive AI Presenters: Engage website visitors with lifelike AI video conversations
• Works Everywhere: Wix, Webflow, WordPress, Shopify, or any custom website
• Simple Integration: Just call BuzzTrail.createConversation()
• Fast Loading: Ultra-lightweight package that won't slow down your site
• Mobile-Friendly: Automatically adapts to desktop, tablet, and mobile screens
• Customizable: Match your brand with custom colors, text, and styling
• Multi-Language Support: 32 languages built-in with auto-translation
• Lead Capture: Optional forms to collect visitor information before conversation
• GDPR Compliant: Privacy-first lead capture with consent management
• No Technical Skills: Works without coding knowledge (perfect for Wix users)
• TypeScript Support: Full type definitions included

Table of Contents

• Getting Started
• Quick Start
• Wix Integration Guide
• Configuration API
  • ConversationOptions
  • configOverride API
• Configuration Examples
• TypeScript Support
• Browser Support
• Troubleshooting
• Version History

Getting Started

Prerequisites

1. BuzzTrail Account: Sign up at buzztrail.ai
2. Customer ID: You'll receive this after account setup
3. AI Presenter: Configure your presenter in the BuzzTrail dashboard

Installation

NPM (for developers)

npm install @buzztrail-ai/engage

yarn add @buzztrail-ai/engage

pnpm add @buzztrail-ai/engage

CDN (for Wix, Webflow, no-code platforms)

Recommended - Semver @1 (always latest v1.x):

<script src="https://cdn.jsdelivr.net/npm/@buzztrail-ai/engage@1/buzztrail.umd.js"></script>

Specific Version (for testing):

<script src="https://cdn.jsdelivr.net/npm/@buzztrail-ai/[email protected]/buzztrail.umd.js"></script>

Fallback CDN (unpkg):

<script src="https://unpkg.com/@buzztrail-ai/engage@1/buzztrail.umd.js"></script>

Note: The @1 semver URL automatically updates to the latest v1.x version (e.g., v1.0.95). Use specific versions for testing, then switch to @1 for production.

Quick Start

CDN Usage (Wix, Webflow, etc.)

<!-- 1. Add a container element to your page -->
<div id="buzztrail-container"></div>

<!-- 2. Add the BuzzTrail script -->
<script src="https://cdn.jsdelivr.net/npm/@buzztrail-ai/engage@1/buzztrail.umd.js"></script>

<!-- 3. Initialize BuzzTrail -->
<script>
  BuzzTrail.createConversation('buzztrail-container', {
    customerId: 'your-customer-id'
  });
</script>

That's it! The video conversation will appear in your container.

With Callbacks

For more control, add callback functions:

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

<script src="https://cdn.jsdelivr.net/npm/@buzztrail-ai/engage@1/buzztrail.umd.js"></script>
<script>
  BuzzTrail.createConversation('my-container', {
    customerId: 'your-customer-id',
    onStart: () => console.log('Conversation started'),
    onEnd: () => console.log('Conversation ended'),
    onError: (error) => console.error('Error:', error)
  });
</script>

NPM Usage (TypeScript/JavaScript)

import { BuzzTrail } from '@buzztrail-ai/engage';
import type { ConversationOptions } from '@buzztrail-ai/engage';

const options: ConversationOptions = {
  customerId: 'acme-corp',
  onStart: () => {
    console.log('Conversation started');
  },
  onEnd: () => {
    console.log('Conversation ended');
  },
  onError: (error) => {
    console.error('Error:', error);
  }
};

BuzzTrail.createConversation('my-container', options);

Wix Integration Guide

Wix requires special handling due to iframe permission restrictions. Follow these steps:

Step 1: Add a Container Element

1. Open Wix Editor for your site
2. Click "Add Elements" (+) → Select "Strip" or "Box"
3. Position and size the element where you want the video conversation
4. Right-click the element → "View Properties" → Note the Element ID (e.g., comp-mfy88b7h)

Step 2: Add BuzzTrail via Custom Code

1. Open Settings → Advanced → Custom Code
2. Click "+ Add Custom Code"
3. Paste the following code (replace your-customer-id and element ID):

<script src="https://cdn.jsdelivr.net/npm/@buzztrail-ai/engage@1/buzztrail.umd.js"></script>
<script>
  BuzzTrail.createConversation('comp-mfy88b7h', {
    customerId: 'your-customer-id'
  });
</script>

4. Configure the snippet:
   • Name: BuzzTrail Engage
   • Add to Pages: Choose "All pages" or specific pages
   • Place Code in: Select "Body - end" (recommended)
5. Click "Apply"
6. Publish your site

Finding the Correct Container ID

Each Wix page element has a unique ID. To find the correct container ID for your page:

1. Open your published Wix page in a browser
2. Open the browser's Developer Tools (F12 or right-click → Inspect)
3. In the Console tab, paste this code and press Enter:

document.querySelectorAll('[id^="comp-"]').forEach(el => {
  console.log(`ID: ${el.id}, Size: ${el.offsetWidth}x${el.offsetHeight}px`);
});

4. Look for a container with dimensions around 700x500px or larger - this is ideal for video display
5. Copy that container's ID (e.g., comp-abc123xyz) and use it in createConversation()

Why Custom Code (Not Embed HTML)?

• Wix Embed HTML wraps code in an iframe, which blocks camera/microphone permissions
• Custom Code runs directly on the page, allowing proper permissions
• This is the only way to enable video conversations on Wix

Configuration API

ConversationOptions

The main options object passed to BuzzTrail.createConversation():

interface ConversationOptions {
  // REQUIRED
  customerId: string;           // Your BuzzTrail customer ID

  // OPTIONAL CALLBACKS
  onStart?: () => void;         // Fired when conversation starts
  onEnd?: () => void;           // Fired when conversation ends
  onError?: (error: Error) => void;  // Fired on errors

  // OPTIONAL OVERRIDES (for testing/customization)
  configOverride?: Partial<CustomerConfig>;
}

configOverride API Reference

The configOverride option allows you to override any aspect of your customer configuration at runtime. This is useful for:

• Testing: Try different themes, languages, or features without changing backend config
• A/B Testing: Test different button text, colors, or gating forms
• Page-Specific Customization: Different settings for different pages
• Development/Debugging: Enable debug logging to troubleshoot issues

Complete configOverride Structure

configOverride: {
  // === CORE SETTINGS ===

  /** Override language (affects button text, form labels, etc.) */
  language?: string;  // 'en', 'es', 'de', 'fr', 'no', etc. (32 languages supported)

  /** Override conversation duration (in seconds) */
  conversation_duration_seconds?: number;  // e.g., 180, 300, 600

  /** Override redirect URL (where to send user after conversation ends) */
  redirect_url?: string;  // e.g., 'https://example.com/thank-you'

  /** Override API base URL (for testing custom backends) */
  apiBaseUrl?: string;  // Default: https://dwdytxxqcvlrmyemonxz.supabase.co/functions/v1

  /** Enable debug logging (shows all [BuzzTrail:...] logs in console) */
  debug?: boolean;  // Default: false (production mode - no logs)

  // === UI CONFIGURATION ===
  ui?: {

    // --- THEME SETTINGS ---
    theme?: {
      /** Main background color (hex) */
      backgroundColor?: string;  // e.g., '#ffffff', '#f5f5f5'

      /** Accent/brand color - used for button, highlights (hex) */
      accentColor?: string;  // e.g., '#a3e635', '#ff0000'

      /** Primary text color (hex) */
      textColor?: string;  // e.g., '#1a1a1a', '#333333'

      /** Secondary background color (hex) */
      backgroundAccent?: string;

      /** Border color (hex) */
      borderColor?: string;
    },

    // --- BUTTON SETTINGS ---
    button?: {
      /**
       * Button text
       * - Set to null to use auto-translated text based on language
       * - Set to custom string to override (e.g., 'Talk with Susan')
       */
      text?: string | null;  // e.g., 'Talk to Our AI', null for auto-translate

      /**
       * Button position relative to video panel
       * - 'center-center': Full-screen centered (default for Wix)
       * - 'bottom-right': Fixed bottom-right widget
       * - 'bottom-left': Fixed bottom-left widget
       * - 'top-right': Fixed top-right widget
       * - 'top-left': Fixed top-left widget
       */
      position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center-center';

      /**
       * Custom button background color (overrides theme.accentColor)
       * - Leave undefined to use theme.accentColor
       * - Set to hex color to override
       */
      backgroundColor?: string;

      /** Custom button border color */
      borderColor?: string;
    },

    // --- VIDEO SETTINGS (idle avatar video) ---
    video?: {
      /** URL to avatar video (shown before conversation starts) */
      videoUrl?: string;  // e.g., 'https://video.wixstatic.com/...'

      /** URL to poster image (shown before video loads) */
      posterUrl?: string;

      /** Whether video should be muted */
      muted?: boolean;  // Default: true

      /** Whether video should loop */
      loop?: boolean;  // Default: true

      /** Whether video should autoplay */
      autoplay?: boolean;  // Default: true
    },

    // --- RESPONSIVE SETTINGS ---
    responsive?: {
      /** Desktop dimensions (screen width > 768px) */
      desktop?: {
        width?: number;   // Default: 720
        height?: number;  // Default: 405
        aspectRatio?: string;  // e.g., '16/9'
      },

      /** Tablet dimensions (screen width 481-768px) */
      tablet?: {
        width?: number;   // Default: 480
        height?: number;  // Default: 270
        aspectRatio?: string;
      },

      /** Mobile dimensions (screen width <= 480px) */
      mobile?: {
        width?: number;   // Default: 280
        height?: number;  // Default: 350
        aspectRatio?: string;  // e.g., '4/5'
      }
    }
  },

  // === GATING/LEAD CAPTURE ===
  gating?: {
    /** Enable/disable gating form */
    enabled?: boolean;  // Default: false

    /**
     * Gating mode
     * - 'standalone': Show form before conversation (current)
     * - 'pre-join': Show form in Daily.co pre-join screen (future)
     */
    mode?: 'standalone' | 'pre-join';  // Default: 'standalone'

    /**
     * Fields to collect from user
     * - Array can include: 'name', 'email', 'phone', 'company'
     */
    collectInfo?: ('name' | 'email' | 'phone' | 'company')[];  // Default: ['name', 'email']

    /**
     * Required fields (must be subset of collectInfo)
     * - These fields must be filled before form can be submitted
     */
    requiredInfo?: ('name' | 'email' | 'phone' | 'company')[];  // Default: ['name', 'email']

    /** Whether to pass collected info to Tavus conversation */
    passToConversation?: boolean;  // Default: true

    /** Email validation settings */
    emailValidation?: {
      /**
       * Block free email providers (Gmail, Yahoo, Outlook.com, etc.)
       * - Useful for B2B lead qualification
       */
      blockFreeProviders?: boolean;  // Default: true

      /** Additional email domains to block (e.g., ['competitor.com']) */
      customBlockedDomains?: string[];
    },

    /**
     * Show GDPR-compliant privacy consent checkbox
     * - Required for EU visitors per GDPR regulations
     */
    gdprCompliant?: boolean;  // Default: false

    /** Custom submit button text */
    submitButtonText?: string;  // Default: auto-translated based on language

    /**
     * Language for form labels
     * - If not set, uses main language setting
     * - 32 languages supported (same as main language option)
     */
    language?: string;

    /** Custom field labels (for custom translations or branding) */
    customLabels?: {
      name?: string;          // Default: auto-translated 'Name'
      email?: string;         // Default: auto-translated 'Email'
      phone?: string;         // Default: auto-translated 'Phone'
      company?: string;       // Default: auto-translated 'Company'
      submitButton?: string;  // Default: auto-translated 'Continue'
    }
  }
}

Supported Languages (32 total)

English (en), Spanish (es), French (fr), German (de), Italian (it), Portuguese (pt), Dutch (nl), Russian (ru), Polish (pl), Turkish (tr), Arabic (ar), Hindi (hi), Chinese Simplified (zh), Chinese Traditional (zh-TW), Japanese (ja), Korean (ko), Vietnamese (vi), Thai (th), Indonesian (id), Malay (ms), Filipino (fil), Norwegian (no), Swedish (sv), Danish (da), Finnish (fi), Greek (el), Hebrew (he), Czech (cs), Hungarian (hu), Romanian (ro), Ukrainian (uk), Bulgarian (bg)

Configuration Examples

Example 1: Change Language to Spanish

BuzzTrail.createConversation('container-id', {
  customerId: 'your-customer-id',
  configOverride: {
    language: 'es'  // Button and form will auto-translate to Spanish
  }
});

Example 2: Custom Theme (Red Accent Color)

BuzzTrail.createConversation('container-id', {
  customerId: 'your-customer-id',
  configOverride: {
    ui: {
      theme: {
        accentColor: '#ff0000',  // Red button
        backgroundColor: '#ffffff',
        textColor: '#1a1a1a'
      }
    }
  }
});

Example 3: Custom Button Text

BuzzTrail.createConversation('container-id', {
  customerId: 'your-customer-id',
  configOverride: {
    ui: {
      button: {
        text: 'Talk with Susan'  // Custom button text
      }
    }
  }
});

Example 4: Enable Gating Form (All Fields)

BuzzTrail.createConversation('container-id', {
  customerId: 'your-customer-id',
  configOverride: {
    gating: {
      enabled: true,
      collectInfo: ['name', 'email', 'phone', 'company'],  // Collect all fields
      requiredInfo: ['name', 'email'],  // Only name and email required
      gdprCompliant: true  // Show GDPR consent checkbox
    }
  }
});

Example 5: Production Mode (No Debug Logs)

BuzzTrail.createConversation('container-id', {
  customerId: 'your-customer-id',
  configOverride: {
    debug: false  // Suppress all console logs (production mode)
  }
});

Example 6: Debug Mode (Enable Logging)

BuzzTrail.createConversation('container-id', {
  customerId: 'your-customer-id',
  configOverride: {
    debug: true  // Show all [BuzzTrail:...] logs for debugging
  }
});

Example 7: German Language + GDPR + Business Email Only

BuzzTrail.createConversation('container-id', {
  customerId: 'your-customer-id',
  configOverride: {
    language: 'de',  // German language
    gating: {
      enabled: true,
      collectInfo: ['name', 'email', 'company'],
      requiredInfo: ['name', 'email', 'company'],
      gdprCompliant: true,  // Show GDPR checkbox (required in EU)
      emailValidation: {
        blockFreeProviders: true  // Block Gmail, Yahoo, etc. (B2B only)
      }
    }
  }
});

Example 8: Mobile-Optimized Dimensions

BuzzTrail.createConversation('container-id', {
  customerId: 'your-customer-id',
  configOverride: {
    ui: {
      responsive: {
        mobile: {
          width: 320,
          height: 400,
          aspectRatio: '4/5'
        }
      }
    }
  }
});

TypeScript Support

This package includes full TypeScript type definitions. No need to install @types packages.

Type Imports

import type {
  // Configuration types
  CustomerConfig,
  UIConfig,
  ThemeConfig,
  ButtonConfig,
  VideoConfig,
  ResponsiveConfig,
  GatingConfig,
  ConversationOptions,
  VideoDimensions,
  ConversationState
} from '@buzztrail-ai/engage';

Example: Type-Safe Configuration

import { BuzzTrail } from '@buzztrail-ai/engage';
import type { ConversationOptions } from '@buzztrail-ai/engage';

const options: ConversationOptions = {
  customerId: 'acme-corp',

  configOverride: {
    language: 'es',  // TypeScript validates this is a valid language code
    ui: {
      theme: {
        accentColor: '#ff0000'  // TypeScript ensures this is a string
      }
    }
  },

  // TypeScript will autocomplete and validate these callbacks
  onStart: () => {
    console.log('Conversation started');
  },
  onEnd: () => {
    console.log('Conversation ended');
  },
  onError: (error: Error) => {
    console.error('Error:', error.message);
  }
};

// TypeScript ensures correct option types
BuzzTrail.createConversation('my-container', options);

API Reference

Global API (window.BuzzTrail)

BuzzTrail.createConversation(containerId, options)

Create a conversation in the specified container.

Parameters:

• containerId (string): DOM element ID to inject the conversation into
• options (ConversationOptions): Configuration options

Returns: Promise<void>

BuzzTrail.createConversation('my-container', {
  customerId: 'acme-corp',
  onStart: () => console.log('Started'),
  onEnd: () => console.log('Ended'),
  onError: (error) => console.error(error)
});

BuzzTrail.version

Get the package version.

console.log(BuzzTrail.version); // "1.0.95"

Note: Starting from v1.0.92, all published bundles include a version banner comment at the top:

/*! @buzztrail-ai/engage v1.0.95 | (c) BuzzTrail AI | https://www.buzztrail.ai */

Browser Support

• Chrome/Edge: Latest 2 versions ✅
• Firefox: Latest 2 versions ✅
• Safari: Latest 2 versions ✅
• Mobile: iOS Safari 14+, Chrome Android ✅

Requirements:

• HTTPS Required: Video conversations only work on secure (HTTPS) websites
• Camera/Microphone Permissions: Browser must support getUserMedia API

Troubleshooting

"Domain not authorized" Error

Solution: Contact BuzzTrail support to authorize your domain. Domain authorization is managed by BuzzTrail admins for security purposes.

Camera/Microphone Not Working

• HTTPS Required: Video conversations only work on secure (HTTPS) websites
• Wix Users: Use Custom Code (Settings → Advanced), NOT the Embed HTML element
• Browser Permissions: Users must allow camera/microphone access when prompted

Video Not Appearing

• Check Account: Verify your BuzzTrail account is active
• Check Customer ID: Ensure you're using the correct customer ID from your dashboard
• Check Container: The HTML element with your container ID must exist on the page
• Check Console: Open browser DevTools (F12) to see any error messages
• Enable Debug Mode: Add configOverride: { debug: true } to see detailed logs

No Looping Video

• Make sure your customer config includes a ui.video.videoUrl property
• Check that the video URL is accessible and valid

Logs Showing in Production

If you see [BuzzTrail:...] logs in production:

1. Ensure you're using v1.0.95 or later
2. Set configOverride: { debug: false }
3. Purge CDN cache if using @1 semver URL:

   curl https://purge.jsdelivr.net/npm/@buzztrail-ai/engage@1/buzztrail.umd.js

Form Not Translating

If gating form fields aren't translating:

1. Ensure language is set in configOverride
2. Check that gating.language isn't overriding the main language
3. Ensure you're using v1.0.84 or later (i18n fix)

Version History

Latest Releases

• v1.0.95 (2025-10-29) - 🐛 CRITICAL FIX Fixed isProduction() to use __DEV__ flag, debug mode now works correctly
• v1.0.94 (2025-10-29) - ❌ BROKEN Attempted production mode fix but isProduction() always returned false
• v1.0.93 (2025-10-29) - Skipped due to npm conflicts
• v1.0.92 (2025-10-29) - 📋 VERSION BANNER All builds now include version comment at top for debugging
• v1.0.89 (2025-10-28) - 🏗️ ARCHITECTURE FIX Database now single source of truth, frontend trusts backend completely
• v1.0.88 (2025-10-28) - 🎉 FIXED RED BUTTON Removed DEFAULT_CONFIG.ui.button.backgroundColor blocking theme overrides
• v1.0.86 (2025-10-27) - 🎨 Fixed button transparency + Daily iframe visibility + theme migration
• v1.0.85 (2025-10-27) - 🎨 Button text contrast fix - bold text with shadow
• v1.0.84 (2025-10-27) - 🎉 Fixed i18n initialization - button text now translates correctly
• v1.0.83 (2025-10-26) - 🎨 Form contrast fix - solid white background with rounded corners
• v1.0.82 (2025-10-26) - 🌍 Button text auto-translate attempt (completed in v1.0.84)
• v1.0.81 (2025-10-26) - 🔒 GDPR hidden by default + removed Company from defaults
• v1.0.80 (2025-10-26) - ✅ Submit button disabled when validation errors exist
• v1.0.79 (2025-10-26) - ⚛️ React 18 downgrade (fixes flashing content on Wix)
• v1.0.78 (2025-10-25) - ⚡ On-blur validation (immediate feedback when user tabs out)
• v1.0.76 (2025-10-24) - 🔄 Schema transformation for agents array
• v1.0.71 (2025-10-24) - 📧 Default email validation (blocks Gmail/free providers)
• v1.0.66 (2025-10-23) - 🐛 Video URL fix (config merge bug)
• v1.0.62 (2025-10-23) - 🧹 Removed ALL auto-init code (first working version)
• v1.0.59 (2025-10-23) - 💰 Delays Tavus start until button click (saves credits!)
• v1.0.52 (2025-10-22) - 🎉 Initial production release with gating form

See CHANGELOG.md for complete version history.

CDN Cache Management

When publishing a new version, the @1 semver URL is cached by CDN providers. To force an immediate update:

# Purge jsdelivr CDN cache
curl https://purge.jsdelivr.net/npm/@buzztrail-ai/engage@1/buzztrail.umd.js

Alternatively, use a specific version for testing:

<script src="https://cdn.jsdelivr.net/npm/@buzztrail-ai/[email protected]/buzztrail.umd.js"></script>

Then switch back to @1 for production once verified.

Support

• Documentation: docs.buzztrail.ai
• Email: [email protected]
• Issues: Report bugs or request features via your account dashboard

License

Proprietary - BuzzTrail AI

Built with TypeScript • AI-Powered Video Conversations • Made for modern web platforms