Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.voltai.ai/llms.txt

Use this file to discover all available pages before exploring further.

Follow these steps to add the Voltai Widget to your website.

​
Prerequisites

You’ll need:
  • An API key from your Voltai dashboard
  • Access to edit your website’s HTML

​
Installation

1

Include the script

Add the widget JavaScript file before your closing </body> tag:
<script src="https://cdn.voltai.ai/widget@latest/voltai-widget.js"></script>
Use @latest for automatic updates, or pin to a specific version like @1.0.0 for stability:
<script src="https://cdn.voltai.ai/widget@1.0.0/voltai-widget.js"></script>
2

Initialize the widget

Call Voltai.load() with your configuration:
<script>
  const voltai = Voltai.load({
    apiKey: 'your-api-key',
    enableGuestUser: true,
    defaultOrgName: 'Acme',
    title: 'Support Chat'
  });
</script>

​
Configuration options

The Voltai.load() function accepts a configuration object:
OptionTypeDefaultDescription
apiKeystringrequiredYour API key for authentication
enableGuestUserbooleanfalseAllow users to chat without signing in
authClickEventsobject{ mode: "observe" }Control what happens after widget sign-in/sign-out button clicks. mode can be "observe" or "intercept"
defaultOrgNamestring—Preferred organization name for authenticated users who belong to multiple organizations
titlestring"Voltai"Text shown in the widget header
initialMessagestring—Message shown in a dismissible popup the first time an unauthenticated user (guest or signed-out) opens the widget. Shown at most once per page load. If omitted, no popup is shown.
hideWidgetButtonbooleanfalseHide the floating button (use with programmatic control)
colorsobject—Custom color theme (see Styling)
hideobject—Hide specific UI elements (see Hide Elements)
onReadyfunction—Called when the widget shell is mounted
onAuthReadyfunction—Called when auth initialization has settled. Receives { isLoggedIn, isGuest }
onOpenfunction—Called when widget opens
onClosefunction—Called when widget closes

​
Basic example

Here’s a complete HTML page with the widget: 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to my website</h1>
  <p>Click the chat button in the corner to get help.</p>

  <script src="https://cdn.voltai.ai/widget@latest/voltai-widget.js"></script>
  <script>
    const voltai = Voltai.load({
      apiKey: 'your-api-key',
      enableGuestUser: true,
      defaultOrgName: 'Acme',
      title: 'Help Center',
      onReady: () => {
        console.log('Widget shell mounted');
      },
      onAuthReady: ({ isLoggedIn, isGuest }) => {
        console.log('Auth initialized', { isLoggedIn, isGuest });
      }
    });
  </script>
</body>
</html>
Set defaultOrgName when your authenticated users can belong to multiple organizations and you want the widget to prefer a specific org by name. If the named org is not available for that user, the widget falls back to their first available organization.

​
What happens next

Once initialized:
  1. A floating button appears in the bottom-right corner of your page
  2. Users click the button to open the chat panel
  3. They can type questions and receive AI-powered responses
  4. The widget automatically handles the conversation flow
Store the returned voltai instance if you want to control the widget programmatically. See Functions for available methods.

​
Troubleshooting

Widget doesn’t appear
  • Check that the JS file is loaded (look for 404 errors in browser console)
  • Verify your API key is correct
  • Make sure Voltai.load() is called after the script loads
Console shows authentication errors
  • Double-check your API key
  • If using guest mode, ensure enableGuestUser: true is set