Package Exports

@buzztrail-ai/engage

Readme

@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: Serve global audiences with built-in translations
Lead Capture: Optional forms to collect visitor information
No Technical Skills: Works without coding knowledge (perfect for Wix users)

Getting Started

Prerequisites

BuzzTrail Account: Sign up at buzztrail.ai
Customer ID: You'll receive this after account setup
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)

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

Fallback CDN (unpkg):

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

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.min.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.min.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

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

Step 2: Add BuzzTrail via Custom Code

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

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

Configure the snippet:
- Name: BuzzTrail Engage
- Add to Pages: Choose "All pages" or specific pages
- Place Code in: Select "Body - end" (recommended)
Click "Apply"
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:

Open your published Wix page in a browser
Open the browser's Developer Tools (F12 or right-click → Inspect)
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`);
});

Look for a container with dimensions around 700x500px or larger - this is ideal for video display
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

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,

  // API types
  CreateConversationRequest,
  CreateConversationResponse,
  EndConversationRequest,
  EndConversationResponse,
  ApiError,

  // Video call types
  CallUrlParams,
  CallTheme,
  CallIframeConfig,
  CallPostMessageEvent,
} 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',

  // 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);

Configuration

createConversation Options

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

  // Optional: Callbacks
  onStart?: () => void;
  onEnd?: () => void;
  onError?: (error: Error) => void;

  // Optional: Override customer config (for testing)
  configOverride?: Partial<CustomerConfig>;
}

Customer Configuration

Customer-specific configuration (persona ID, theme, etc.) is fetched from the BuzzTrail API using your customerId. This allows for runtime configuration changes without code updates.

Example configuration structure:

interface CustomerConfig {
  customerId: string;              // 'acme-corp'
  persona_id: string;              // AI presenter identifier
  replica_id: string;              // Video replica ID
  conversation_duration_seconds: number;  // Max duration
  language?: string;               // 'en', 'no', etc.
  ui: {
    theme: {
      backgroundColor: string;     // '#ffffff'
      accentColor: string;         // '#a3e635'
      textColor: string;           // '#1a1a1a'
    },
    button: {
      text: string;                // 'Talk to Our AI'
      position: string;            // 'center-center'
    },
    video: {
      videoUrl?: string;           // Avatar idle video
      muted?: boolean;
      loop?: boolean;
    },
    responsive: {
      desktop: { width: 720, height: 405 },
      tablet: { width: 480, height: 270 },
      mobile: { width: 280, height: 350 }
    }
  },
  gating?: {
    enabled: boolean;
    collectInfo: ['name', 'email', 'phone'],
    language: 'en',
    customLabels?: { ... }
  },
  redirect_url?: string;
}

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.destroy(containerId)`

Destroy and cleanup a conversation.

BuzzTrail.destroy('my-container');

`BuzzTrail.version`

Get the package version.

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

Browser Support

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

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

No Looping Video

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

Changelog

See CHANGELOG.md for version history.

License

Proprietary - BuzzTrail AI

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