AI Avatar Widget - User Guide

The AI Avatar Widget allows you to add an interactive AI video conversation to your website with just a few lines of code. Your visitors can click a button to start a live video chat with an AI-powered avatar.

What your visitors will experience: - Click a button on your website - A video window opens showing an AI avatar - Have a natural conversation with voice and video - Built-in controls to mute, turn camera on/off, and hang up

Important: Domain Authorization

Before you can use the widget, your domain must be authorized. The widget includes built-in security that only allows it to run on pre-approved domains.

When you receive your agent ID, make sure to add your website's domain (e.g., example.com) to the allowed domains list in the admin console.

If you see an error like "Widget Not Authorized," you need to add your domain in the admin console.

Adding the widget to your site is simple - just two steps!

Step 1: Add the Script Tag

Copy this script tag and paste it into your HTML file, right before the closing </body> tag:

<script type="module" src="https://widgets.wavesay.com/avatar-widget.js"></script>

Place this code wherever you want the button to appear on your page:

<start-avatar
  agent-id="YOUR-AGENT-ID"
  max-duration="300">
</start-avatar>

Note: Replace YOUR-AGENT-ID with your unique agent identifier and 300 with your desired call duration in seconds.

Complete Example

Here's what your HTML might look like:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to My Website</h1>
  <p>Have questions? Talk to our AI assistant!</p>

  <!-- The AI Avatar Widget -->
  <start-avatar
    agent-id="YOUR-AGENT-ID"
    max-duration="300">
  </start-avatar>

  <!-- Widget Script (place before closing body tag) -->
  <script type="module" src="https://widgets.wavesay.com/avatar-widget.js"></script>
</body>
</html>

That's it! Your widget is now live on your site.

Setting the Call Duration

The max-duration attribute controls how long each video call can last (in seconds). This is a required attribute.

<start-avatar
  agent-id="YOUR-AGENT-ID"
  max-duration="180">
</start-avatar>

Common durations: - 60 = 1 minute - 180 = 3 minutes - 300 = 5 minutes - 600 = 10 minutes

Important: The call will automatically end when the time limit is reached.

Customizing the Button Text

By default, the widget displays a button that says "Start Video Call". You can change this text to anything you want:

<start-avatar
  agent-id="YOUR-AGENT-ID"
  max-duration="300"
  button-text="Chat with AI">
</start-avatar>

Examples

For customer support:

<start-avatar
  agent-id="YOUR-AGENT-ID"
  max-duration="180"
  button-text="Get Help">
</start-avatar>

For sales:

<start-avatar
  agent-id="YOUR-AGENT-ID"
  max-duration="600"
  button-text="Talk to an Expert">
</start-avatar>

For demos:

<start-avatar
  agent-id="YOUR-AGENT-ID"
  max-duration="120"
  button-text="Try Our AI Demo">
</start-avatar>

Using Your Own Button or Image

Instead of the default button, you can use your own HTML elements as triggers. Simply place your custom HTML inside the <start-avatar> tags:

Custom Button

<start-avatar agent-id="YOUR-AGENT-ID" max-duration="300">
  <button class="my-custom-button">
    🎥 Launch Video Chat
  </button>
</start-avatar>

Custom Link

<start-avatar agent-id="YOUR-AGENT-ID" max-duration="180">
  <a href="#" class="video-link">
    Click here to chat with AI
  </a>
</start-avatar>

Custom Image

<start-avatar agent-id="YOUR-AGENT-ID" max-duration="300">
  <img src="/images/chat-button.png"
       alt="Start video chat"
       style="cursor: pointer; width: 200px;">
</start-avatar>

Complex Custom Trigger

<start-avatar agent-id="YOUR-AGENT-ID" max-duration="600">
  <div class="call-to-action">
    <img src="/avatar-icon.svg" alt="">
    <h3>Need Help?</h3>
    <p>Connect with our AI assistant</p>
    <button class="cta-button">Start Now →</button>
  </div>
</start-avatar>

Styling Your Custom Button

When you use a custom trigger, you can style it with your own CSS just like any other element on your page:

<style>
  .my-video-button {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
    padding: 16px 32px;
    border: none;
    border-radius: 50px;
    font-size: 18px;
    font-weight: 600;
    cursor: pointer;
    box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
    transition: all 0.3s ease;
  }

  .my-video-button:hover {
    transform: translateY(-2px);
    box-shadow: 0 6px 20px rgba(102, 126, 234, 0.6);
  }
</style>

<start-avatar agent-id="YOUR-AGENT-ID" max-duration="300">
  <button class="my-video-button">
    Start Video Call
  </button>
</start-avatar>

Styling Tips

Match your website's design: - Use your site's colors and fonts - Match your existing button styles - Keep it consistent with your brand

Make it stand out: - Use contrasting colors - Add hover effects - Include an icon or emoji

Make it clear: - Use action words ("Start", "Talk", "Connect") - Include what will happen ("Video Call", "Chat", "Demo")

What Happens When Someone Clicks

Here's what your visitors will experience:

Click the Button
Visitor clicks your widget button or custom trigger
Video Window Opens
A full-screen dialog appears with a loading message
"Setting up session" appears briefly
Connection Established
The AI avatar appears on screen
Video call begins automatically
Your visitor's camera may activate (they can turn it off)
During the Call
Visitors can:
- Talk naturally with the AI avatar
- Mute/unmute their microphone
- Turn their camera on/off
- Hang up to end the call
The call lasts until the max-duration time limit is reached
Call Ends
Window closes automatically or when visitor hangs up
Visitor returns to your website

Session Limits

The widget has these session characteristics: - Timed sessions: Calls automatically end after the configured max-duration - One session per visitor: Each visitor can try the demo once per browser - Reset by clearing browser data: Visitors can clear cookies/local storage to try again

Multiple Widgets on One Page

You can add multiple widgets to the same page, each with different settings:

<!-- Sales team -->
<start-avatar
  agent-id="SALES-AGENT-ID"
  max-duration="600"
  button-text="Talk to Sales">
</start-avatar>

<!-- Support team -->
<start-avatar
  agent-id="SUPPORT-AGENT-ID"
  max-duration="300"
  button-text="Get Support">
</start-avatar>

<!-- Product demo -->
<start-avatar agent-id="DEMO-AGENT-ID" max-duration="120">
  <button class="demo-btn">Try Product Demo</button>
</start-avatar>

Browser Support

The widget works on all modern browsers:

Desktop Browsers

✅ Chrome (version 90+)
✅ Firefox (version 88+)
✅ Safari (version 14+)
✅ Microsoft Edge (version 90+)
✅ Opera (version 76+)

Mobile Browsers

✅ iOS Safari (version 14+)
✅ Chrome for Android (version 90+)
✅ Chrome for iOS
✅ Firefox for Android (version 88+)

Requirements

Modern browser with webcam and microphone support
JavaScript enabled
Internet connection

Troubleshooting

What you see: An error message that says "This widget is not authorized to run on domain: yourdomain.com"

What this means: Your website's domain hasn't been added to the allowed domains list for your agent.

How to fix: 1. Log into the admin console 2. Navigate to your agent's settings 3. Add your website's domain (e.g., example.com or www.example.com) to the allowed domains list 4. Save the changes 5. Refresh your website

Note: Both example.com and www.example.com are different domains. Make sure to provide the exact domain you're using.

Check these things:

Domain is authorized: Make sure your domain is in the allowed list (see above)

Script tag is present:

<script type="module" src="https://YOUR-CDN-URL/avatar-widget.js"></script>

Agent ID is set:

<start-avatar agent-id="YOUR-AGENT-ID" max-duration="300"></start-avatar>

Max duration is set: Make sure you've included the max-duration attribute (a positive number in seconds)
Browser is supported: Make sure you're using a modern browser (see Browser Support above)

Button Appears But Nothing Happens

Possible causes:

Camera/Microphone Permissions
Your browser may be blocking camera/microphone access
Look for a camera icon in your browser's address bar
Click it and allow permissions
Pop-up Blocker
Some browsers might block the video window
Check for pop-up blocked notifications
Allow pop-ups for your website
JavaScript Errors
Open your browser's developer console (F12)
Look for any red error messages
Contact support with the error details

"You've Already Used This Demo"

What's happening: - The widget remembers that you've already tried the demo - Demo sessions are limited to once per browser

Solutions: - Clear your browser data: 1. Open browser settings 2. Clear cookies and site data 3. Refresh the page

Try a different browser:
Open the site in a different browser
Use incognito/private mode:
Open an incognito/private window
Visit your website again

Video Doesn't Load / Stays on "Loading..."

Try these steps:

Check your internet connection
Video calls require a stable internet connection
Try refreshing the page
Restart your browser
Close all browser windows
Open browser again and try
Try a different browser
Test if the issue happens in another browser
Check firewall/antivirus
Some security software blocks video connections
Try temporarily disabling it

Camera/Microphone Not Working

Permission steps:

Chrome: 1. Click the camera icon in the address bar 2. Select "Always allow" 3. Refresh the page

Firefox: 1. Click the permissions icon (left of address bar) 2. Enable camera and microphone 3. Refresh the page

Safari: 1. Go to Safari > Settings > Websites 2. Select Camera and Microphone 3. Allow access for your website

Still Having Issues?

If you're still experiencing problems: - Try restarting your computer - Update your browser to the latest version - Contact support with: - What browser you're using (Chrome, Firefox, etc.) - What happens when you click the button - Any error messages you see

Frequently Asked Questions

Can I use this on any website?

Yes! The widget works with any website - WordPress, Shopify, Wix, Squarespace, or custom HTML. However, you must add your domain to the allowed domains list in the admin console first (see Domain Authorization section above).

Does it work on mobile?

Yes! The widget works on mobile phones and tablets with supported browsers.

Will it conflict with my site's design?

No! The widget uses Shadow DOM technology to isolate its styles from your website's CSS.

Can I have multiple widgets on one page?

Yes! You can add as many widgets as you need, each with different agent IDs.

How long can video sessions last?

Video sessions last for the duration you specify in the max-duration attribute (in seconds). For example, max-duration="300" allows 5-minute calls.

Do visitors need to create an account?

No! Visitors can start video calls immediately without creating an account or logging in.

What data is collected?

The widget only requires temporary camera/microphone access during calls. Check with your provider for their specific privacy policy.

Can I customize how it looks?

Yes! You can use custom triggers (buttons, images, links) and style them however you want with CSS.

Does it work with WordPress?

Yes! Just paste the code into a Custom HTML block or your theme's footer. Remember to add your WordPress domain to the allowed domains list in the admin console first.

Does it work with Shopify?

Yes! Add the code to your theme's template files or use a custom HTML section. Make sure to add your Shopify domain (e.g., yourstore.myshopify.com) to the allowed domains list in the admin console.

Can I test it on localhost or a staging site?

Yes! Just add your testing domains (e.g., localhost, staging.example.com) to the allowed domains list in the admin console.

Need Help?

If you have questions or need assistance: - Contact your widget provider - Check the browser console (F12) for error messages - Try the troubleshooting steps above

Enjoy your AI Avatar Widget! 🎥✨