> ## 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.

# Getting Started

> Add the Voltai Widget to your website in minutes

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

<Steps>
  <Step title="Include the script">
    Add the widget JavaScript file before your closing `</body>` tag:

    ```html theme={null}
    <script src="https://cdn.voltai.ai/widget@latest/voltai-widget.js"></script>
    ```

    <Tip>
      Use `@latest` for automatic updates, or pin to a specific version like `@1.0.0` for stability:

      ```html theme={null}
      <script src="https://cdn.voltai.ai/widget@1.0.0/voltai-widget.js"></script>
      ```
    </Tip>
  </Step>

  <Step title="Initialize the widget">
    Call `Voltai.load()` with your configuration:

    ```html theme={null}
    <script>
      const voltai = Voltai.load({
        apiKey: 'your-api-key',
        enableGuestUser: true,
        defaultOrgName: 'Acme',
        title: 'Support Chat'
      });
    </script>
    ```
  </Step>
</Steps>

## 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](/configuration/styling))                                                                                                                           |
| `hide`             | object   | —                     | Hide specific UI elements (see [Hide Elements](/configuration/hide))                                                                                                                 |
| `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:

```html theme={null}
<!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>
```

<Tip>
  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.
</Tip>

## 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

<Tip>
  Store the returned `voltai` instance if you want to control the widget programmatically. See [Functions](/configuration/functions) for available methods.
</Tip>

## 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