HeyGen Avatar Widget

A customizable React component to embed HeyGen AI avatars in any React application.

Features

• Simple drop-in widget for any React app
• Customizable avatar, knowledge base, and appearance
• Streaming avatar video with real-time responses
• Voice and text chat interfaces
• Compatible with React 17+ and TypeScript
• Enhanced error handling and debugging (v0.1.8+)
• Direct API integration as fallback (v0.1.8+)

Installation

npm install heygen-avatar-widget @heygen/streaming-avatar
# or
yarn add heygen-avatar-widget @heygen/streaming-avatar

Prerequisites

This package requires the following:

1. HeyGen API account with:
   • A valid API token
   • At least one avatar created
2. An API endpoint in your application to fetch a streaming token

Usage

import { AvatarWidget } from "heygen-avatar-widget";
import "heygen-avatar-widget/styles.css"; // Import styles

function App() {
  return (
    <div className="App">
      <h1>My App with HeyGen Avatar</h1>

      {/* The widget will appear as a floating button */}
      <AvatarWidget
        avatarId="your-avatar-id"
        avatarName="Tyler-insuit-20220721"
        openingMessage="Hello! I'm Aiva. How can I help you today?"
      />
    </div>
  );
}

export default App;

API Reference

AvatarWidget Props

| Prop | Type | Required | Default | Description | | ---------------- | ------ | -------- | --------------------------- | ---------------------------------------------------------------------- | | knowledgeID | string | No | - | HeyGen knowledge base ID | | avatarId | string | Yes | Default avatar | ID of the HeyGen avatar to use | | avatarName | string | Yes | - | Specific avatar name to use (e.g. "Thaddeus_ProfessionalLook2_public") | | openingMessage | string | No | - | First message spoken by the avatar | | apiUrl | string | No | "https://api.heygen.com/v1" | Base URL for the HeyGen API | | className | string | No | "" | Additional CSS classes for the widget button |

Troubleshooting

"Cannot read properties of undefined (reading 'GOOD')" or "Cannot read properties of undefined (reading 'Low')"

If you encounter these errors, ensure:

1. You've installed @heygen/streaming-avatar as a dependency along with this package
2. If using Vite, configure it to properly resolve the dependency:

// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    include: ["@heygen/streaming-avatar"],
  },
});

NEW IN v0.1.8: This version includes fallbacks for common enum issues, which should resolve many of these errors automatically. If you're still experiencing issues, check the full troubleshooting guide in TROUBLESHOOTING.md.

No API calls after token retrieval

If you're experiencing issues where the avatar initializes but no API calls are made after token retrieval:

1. Check browser console for detailed logs
2. Ensure your backend is providing a valid HeyGen streaming token
3. Verify network connectivity to HeyGen's API endpoints
4. Make sure your HeyGen API key has proper permissions

See the complete troubleshooting guide in TROUBLESHOOTING.md for more details.

Backend Integration

This widget attempts to fetch a streaming token from the /api/avatar/streaming-token endpoint on your backend. You need to implement this endpoint to provide a valid HeyGen streaming token.

Example implementation using Express:

// Example Express endpoint
app.post("/api/avatar/streaming-token", async (req, res) => {
  try {
    const response = await fetch("https://api.heygen.com/v1/streaming/token", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": process.env.HEYGEN_API_KEY,
      },
    });

    const token = await response.text();
    res.send(token);
  } catch (error) {
    console.error("Error getting streaming token:", error);
    res.status(500).send("Failed to get streaming token");
  }
});

Styling

The widget uses Tailwind CSS utility classes by default. You can override styles by providing custom CSS classes.

Additional Resources

• Complete Documentation
• Troubleshooting Guide
• Example Backend Implementation
• Environment Variables Example

Version History

• 1.0.0 - First stable release with all features fully functional
• 0.3.8 - Final pre-release version with improvements and fixes
• 0.1.8 - Enhanced debugging, direct API integration, improved error handling
• 0.1.7 - Added fallback mechanisms for API compatibility
• 0.1.6 - Initial public release

License

MIT