Skip to main content
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
defaultOrgNamestring—Preferred organization name for authenticated users who belong to multiple organizations
titlestring"Voltai"Text shown in the widget header
hideWidgetButtonbooleanfalseHide the floating button (use with programmatic control)
colorsobject—Custom color theme (see Styling)
hideobject—Hide specific UI elements: { imageAttachment, tagResources, tagTopic } (all boolean)
onReadyfunction—Called when widget is ready
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 is ready');
      }
    });
  </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