> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boostgpt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Programmatic controls for the chat widget

## Initialization

```js theme={null}
boostgpt.init({
  botId: 'YOUR_BOT_UUID',       // required
  position: 'bottom-right',      // optional override
  metadata: { page: 'pricing' }, // optional context
});
```

Returns the `boostgpt` API object with the methods below.

## Methods

### `boostgpt.open()`

Opens the chat frame. No-op if already open.

### `boostgpt.close()`

Minimizes the widget back to the bubble. No-op if already closed.

### `boostgpt.toggle()`

Toggles between open and closed states.

### `boostgpt.hide()`

Hides the entire widget (bubble + frame) from the page. Useful for conditionally showing the widget based on user state.

### `boostgpt.show()`

Shows the widget again after `hide()`.

### `boostgpt.destroy()`

Removes the widget from the DOM entirely and cleans up event listeners.

### `boostgpt.addMessage(text, options)`

Adds a custom message card above the bubble without firing an event.

## Events

Listen for widget lifecycle events:

```js theme={null}
boostgpt.on('open', () => {
  console.log('Widget opened');
});

boostgpt.on('close', () => {
  console.log('Widget closed');
});

boostgpt.on('ready', () => {
  console.log('Chat iframe loaded');
});

boostgpt.on('messageSent', (message) => {
  console.log('User sent:', message);
});
```

| Event | Description |
| - | - |
| `open` | Widget frame opened |
| `close` | Widget frame closed |
| `ready` | Chat iframe finished loading |
| `messageSent` | User sent a message in the chat |

## Global Access

The widget is available globally as `boostgpt` (and `BoostGPTWidget` for backwards compatibility):

```js theme={null}
boostgpt.open();
boostgpt.close();
boostgpt.toggle();
```

## Custom Chat Buttons

Use the programmatic API to open the widget from your own buttons:

```html theme={null}
<button onclick="boostgpt.open()">Chat with us</button>
```

You can hide the default bubble and use only your own buttons:

```js theme={null}
boostgpt.init({ botId: 'YOUR_BOT_UUID' });
boostgpt.hide();  // hide the bubble

// Open from your own UI
document.getElementById('help-btn').addEventListener('click', () => {
  boostgpt.show();
  boostgpt.open();
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.