Getting Started - Voltai Documentation

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

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>

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:

Option	Type	Default	Description
`apiKey`	string	required	Your API key for authentication
`enableGuestUser`	boolean	`false`	Allow users to chat without signing in
`authClickEvents`	object	`{ mode: "observe" }`	Control what happens after widget sign-in/sign-out button clicks. `mode` can be `"observe"` or `"intercept"`
`defaultOrgName`	string	—	Preferred organization name for authenticated users who belong to multiple organizations
`title`	string	`"Voltai"`	Text shown in the widget header
`initialMessage`	string	—	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.
`hideWidgetButton`	boolean	`false`	Hide the floating button (use with programmatic control)
`colors`	object	—	Custom color theme (see Styling)
`hide`	object	—	Hide specific UI elements (see Hide Elements)
`onReady`	function	—	Called when the widget shell is mounted
`onAuthReady`	function	—	Called when auth initialization has settled. Receives `{ isLoggedIn, isGuest }`
`onOpen`	function	—	Called when widget opens
`onClose`	function	—	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:

A floating button appears in the bottom-right corner of your page
Users click the button to open the chat panel
They can type questions and receive AI-powered responses
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

​Prerequisites

​Installation

​Configuration options

​Basic example

​What happens next

​Troubleshooting

Prerequisites

Installation

Configuration options

Basic example

What happens next

Troubleshooting