Widget Installation Guide

The Voxenly widget allows you to embed an AI voice assistant directly on your website. Visitors can click a button to start a conversation with your agent instantly.

1Quick Start

1. Enable Your Widget

Navigate to your agent in the Voxenly dashboard
Go to the Widget tab
Toggle Enable Widget to ON
Customize your settings (Title, Colors, Position)
Click Save Changes

2. Get Your Agent ID

Your Agent ID is displayed in the agent settings page. It looks like: cmiyo5fys0004l40bny2e95xb

3. Add the Widget Script

Add the widget script to your website. The script should be placed just before the closing </body> tag.

Installation Examples

HTML / Static Site

index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Website</title>
</head>
<body>
    <!-- Your website content -->

    <!-- Voxenly Widget Script -->
    <script
        src="https://app.voxenly.com/widget.js"
        data-agent-id="YOUR_AGENT_ID_HERE"
        defer
    ></script>
</body>
</html>

Next.js (App Router)

app/layout.tsx

import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <script
          src="https://app.voxenly.com/widget.js"
          data-agent-id="YOUR_AGENT_ID_HERE"
          defer
        ></script>
      </body>
    </html>
  );
}

React

App.tsx

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://app.voxenly.com/widget.js';
    script.setAttribute('data-agent-id', 'YOUR_AGENT_ID_HERE');
    script.defer = true;
    document.body.appendChild(script);

    return () => {
      // Cleanup: remove script when component unmounts
      document.body.removeChild(script);
    };
  }, []);

  return (
    <div>
      {/* Your app content */}
    </div>
  );
}

Troubleshooting

Widget Not Appearing?

Check that Enable Widget is toggled ON in the dashboard
Verify your Agent is Active
Ensure data-agent-id matches your agent's ID exactly
Check browser console for errors

CORS Errors

If you see CORS errors, check your script URL:

Correct: https://app.voxenly.com/widget.js
Wrong: http://app.voxenly.com/widget.js (missing HTTPS)

Configuration Options

Attribute	Description	Required
src	Must be `https://app.voxenly.com/widget.js`	Yes
data-agent-id	Your unique agent identifier	Yes
defer	Loads script after HTML parsing (recommended)	No