HGA Backend Integration Guide

🎯 What is HGA Backend?

HGA (HeyGen Avatar) is an enterprise-grade backend service that provides:
• Photorealistic avatar streaming via HeyGen SDK
• Advanced API control and customization
• JWT-based authentication and session management
• Production-ready with rate limiting and security

🎬

HeyGen Avatars

Photorealistic AI avatars with professional voice synthesis

🔐

Secure Sessions

JWT authentication with session management and rate limiting

⚡

Real-time API

WebSocket streaming with RESTful control endpoints

🌐

Cross-domain

CORS-enabled for embedding in any website

🚀 Quick Start (5 minutes)

Get started immediately with the basic embed code:

<!-- Load the HGA embed script -->
<script src="https://hga-avatar-widget.rr-startech-innovation.workers.dev/embed.js"></script>

<!-- Widget container -->
<div id="hga-avatar-container" style="width: 800px; height: 600px;"></div>

<script>
// Initialize the widget
window.addEventListener('DOMContentLoaded', function() {
    // Basic initialization
    if (typeof HGAAvatarWidget !== 'undefined') {
        HGAAvatarWidget.init({
            container: '#hga-avatar-container',
            width: '100%',
            height: '100%'
        });
    }
});
</script>

✅ That's it! The widget will load with default settings and handle authentication automatically.

⚙️ Advanced Configuration

Customize the widget behavior and appearance:

Widget Configuration

HGAAvatarWidget.init({
    // Container
    container: '#avatar-widget',
    width: '800px',
    height: '600px',

    // Avatar Settings
    avatarId: 'heygen-avatar-id',  // Optional: specific avatar
    voiceId: 'en-US-JennyNeural',  // Voice selection

    // Behavior
    autoStart: true,               // Auto-start session
    showControls: true,            // Show control buttons
    allowMicrophone: true,         // Enable voice input

    // UI Customization
    theme: 'dark',                 // 'light' or 'dark'
    borderRadius: '12px',          // Custom border radius
    showBranding: false,           // Hide Techtree Avatar branding

    // Event Callbacks
    onReady: function() {
        console.log('Avatar widget is ready');
    },
    onMessage: function(message) {
        console.log('Avatar said:', message);
    },
    onError: function(error) {
        console.error('Widget error:', error);
    }
});

Event Handling

// Listen for widget events
window.addEventListener('message', function(event) {
    if (event.origin !== 'https://hga-avatar-widget.rr-startech-innovation.workers.dev') {
        return; // Security check
    }

    switch (event.data.type) {
        case 'avatar_ready':
            console.log('Avatar is ready to chat');
            break;

        case 'avatar_speaking':
            console.log('Avatar started speaking');
            break;

        case 'avatar_finished':
            console.log('Avatar finished speaking');
            break;

        case 'user_message':
            console.log('User said:', event.data.message);
            break;

        case 'error':
            console.error('Avatar error:', event.data.error);
            break;
    }
});

// Send commands to the widget
function sendMessage(text) {
    const iframe = document.querySelector('#hga-avatar-container iframe');
    iframe.contentWindow.postMessage({
        type: 'speak',
        text: text
    }, '*');
}

Custom Styling

<style>
/* Container styling */
#hga-avatar-container {
    border: 2px solid #667eea;
    border-radius: 12px;
    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
    overflow: hidden;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

/* Responsive design */
@media (max-width: 768px) {
    #hga-avatar-container {
        width: 100% !important;
        height: 400px !important;
    }
}

/* Loading state */
#hga-avatar-container.loading {
    background: #f8f9fa;
    display: flex;
    align-items: center;
    justify-content: center;
}

#hga-avatar-container.loading::before {
    content: "Loading avatar...";
    color: #666;
    font-size: 1.1rem;
}
</style>

🔌 Direct API Integration

For advanced use cases, integrate directly with the HGA API:

Authentication

POST /api/v1/token

Generate a session token for avatar interactions

curl -X POST https://hga-avatar-widget.rr-startech-innovation.workers.dev/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "unique-session-id",
    "userId": "user-123"
  }'

Response: { "token": "eyJhbGciOiJIUzI1NiIs...", "expires": 1641234567 }

Start Avatar Session

POST /api/v1/stream/start

Initialize a streaming avatar session

curl -X POST https://hga-avatar-widget.rr-startech-innovation.workers.dev/api/v1/stream/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "avatarId": "heygen-avatar-id",
    "quality": "high"
  }'

Send Message to Avatar

POST /api/v1/stream/speak

Make the avatar speak a message

curl -X POST https://hga-avatar-widget.rr-startech-innovation.workers.dev/api/v1/stream/speak \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello! How can I help you today?",
    "voiceId": "en-US-JennyNeural"
  }'

🏭 Production Setup

Configure the widget for production deployment:

⚠️ Production Considerations:
• Request domain whitelisting for CORS access
• Implement proper error handling and fallbacks
• Consider rate limiting for your specific use case
• Test thoroughly on mobile devices

Environment Configuration

// Production configuration
const config = {
    // Use production endpoint
    apiUrl: 'https://hga-avatar-widget-production.rr-startech-innovation.workers.dev',

    // Environment-specific settings
    environment: 'production',
    debug: false,

    // Error handling
    onError: function(error) {
        // Log to your analytics service
        analytics.track('avatar_error', {
            error: error.message,
            timestamp: new Date().toISOString()
        });

        // Show user-friendly message
        showErrorMessage('Avatar temporarily unavailable. Please try again.');
    },

    // Fallback for unsupported browsers
    onUnsupported: function() {
        document.getElementById('avatar-container').innerHTML =
            '<p>Your browser doesn\'t support this feature. Please use Chrome, Firefox, or Safari.</p>';
    }
};

HGAAvatarWidget.init(config);

Mobile Optimization

<style>
/* Mobile-first responsive design */
.avatar-container {
    width: 100%;
    max-width: 800px;
    margin: 0 auto;
}

/* Phone landscape and up */
@media (min-width: 568px) {
    .avatar-container {
        height: 400px;
    }
}

/* Tablet and up */
@media (min-width: 768px) {
    .avatar-container {
        height: 500px;
    }
}

/* Desktop and up */
@media (min-width: 1024px) {
    .avatar-container {
        height: 600px;
    }
}

/* Touch-friendly controls */
@media (hover: none) and (pointer: coarse) {
    .avatar-controls button {
        min-height: 44px;
        min-width: 44px;
        font-size: 1.1rem;
    }
}
</style>

📚 Examples & Resources

🔗

Live Examples

Basic Embed Demo

Security Testing

Responsive Design

📖

Documentation

Backend Services Guide

HeyGen API Docs

🛠

Tools

Security Testing

API Key Management (Contact Support)

💬

Support

Email: rr.startech.innovation@gmail.com

Response time: 24-48 hours

🎉 Ready to deploy?
Your HGA integration is complete! Don't forget to:
• Test on multiple devices and browsers
• Request domain whitelisting for production
• Monitor usage and performance
• Compare with Techtree Avatar for simpler use cases →