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

# Functions

> Control the widget programmatically with SDK methods

The `Voltai.load()` function returns an instance with methods to control the widget from your code.

```javascript theme={null}
const voltai = Voltai.load({
  apiKey: 'your-api-key'
});

// Now you can use voltai.open(), voltai.close(), voltai.login(), etc.
```

## Widget visibility

### open()

Opens the chat panel.

If the visitor does not already have a guest or signed-in session, the widget opens into its verification step first. After verification completes, the chat UI appears automatically.

```javascript theme={null}
voltai.open();
```

### close()

Closes the chat panel.

```javascript theme={null}
voltai.close();
```

### toggle()

Toggles the chat panel open or closed.

```javascript theme={null}
voltai.toggle();
```

<Tip>
  Use these methods to integrate the widget with your own UI. For example, open the chat when a user clicks a "Need help?" button.
</Tip>

## Sending messages

### sendChat(query, options)

Sends a chat message programmatically. This lets you start conversations from your own code, like a search box or help button.

If the visitor does not already have a guest or signed-in session, the widget opens, keeps the latest queued query, shows the verification step, and submits the message automatically after verification succeeds.

```javascript theme={null}
await voltai.sendChat('How do I reset my password?', {
  topics: ['Support']
});
```

**Parameters:**

| Name      | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `query`   | string | The message to send           |
| `options` | object | Required settings (see below) |

**Options:**

| Property  | Type       | Required | Description                                                                                  |
| --------- | ---------- | -------- | -------------------------------------------------------------------------------------------- |
| `topics`  | `string[]` | Yes      | Topic names to associate with the message. The backend resolves names to full topic objects. |
| `newChat` | boolean    | No       | Start a new conversation (default: `false`)                                                  |

**Returns:** `Promise<void>`

### Example: Basic usage

```javascript theme={null}
await voltai.sendChat('Show me getting started guides', {
  topics: ['Documentation', 'Tutorials']
});
```

### Example: Start a new chat

```javascript theme={null}
await voltai.sendChat('I have a billing question', {
  topics: ['Billing'],
  newChat: true
});
```

### Example: Combined with open

```javascript theme={null}
// Open the widget and send a message
voltai.open();
await voltai.sendChat('What are your pricing plans?', {
  topics: ['Sales'],
  newChat: true
});
```

<Note>
  `sendChat()` no longer requires you to pre-authenticate the visitor yourself. If verification is needed, the widget handles it inline and submits the latest queued message afterward.
</Note>

<Tip>
  If multiple `sendChat()` calls are made before verification completes, the latest pending message replaces any earlier unsent one.
</Tip>

## Authentication

### login()

Opens the login popup for users to sign in.

You can call this before the widget is opened. If the widget is still finishing its initial auth bootstrap, the SDK waits until auth is ready and then runs the login flow.

```javascript theme={null}
await voltai.login();
```

### logout()

Logs out the current user and clears their session.

```javascript theme={null}
await voltai.logout();
```

### isLoggedIn()

Returns whether a user is signed in. Returns `false` for guest users, and also returns `false` until auth initialization has settled.

```javascript theme={null}
if (voltai.isAuthReady() && !voltai.isLoggedIn()) {
  await voltai.login();
}
```

**Returns:** `boolean`

### isAuthReady()

Returns whether the widget has finished restoring the current auth state.

```javascript theme={null}
if (!voltai.isAuthReady()) {
  console.log('Still initializing auth');
}
```

**Returns:** `boolean`

## Cleanup

### destroy()

Removes the widget from the page and cleans up all resources.

```javascript theme={null}
voltai.destroy();
```

Use this when:

* Navigating away in a single-page app
* Conditionally removing the widget
* Reinitializing with different settings

## Complete example

Here's a page with custom buttons to control the widget:

```html theme={null}
<button id="open-btn">Open Chat</button>
<button id="close-btn">Close Chat</button>
<button id="ask-btn">Ask a Question</button>
<button id="login-btn">Sign In</button>
<button id="logout-btn">Sign Out</button>

<script src="https://cdn.voltai.ai/widget@latest/voltai-widget.js"></script>
<script>
  const voltai = Voltai.load({
    apiKey: 'your-api-key',
    enableGuestUser: true
  });

  document.getElementById('open-btn').onclick = () => {
    voltai.open();
  };

  document.getElementById('close-btn').onclick = () => {
    voltai.close();
  };

  document.getElementById('ask-btn').onclick = async () => {
    voltai.open();
    await voltai.sendChat('How do I get started?', {
      topics: ['Getting Started']
    });
  };

  document.getElementById('login-btn').onclick = async () => {
    await voltai.login();
  };

  document.getElementById('logout-btn').onclick = async () => {
    await voltai.logout();
  };
</script>
```