> ## 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
  widget: true,                  // set false for trigger-only mode (no bubble)
  userToken: 'jwt-token',        // optional SSO token
  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.trigger(eventName, context, options)`

Shows a proactive message card above the bubble. See [Event Triggers](/saas/chat-widget/triggers) for full documentation.

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

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

### `boostgpt.dismiss(eventName)`

Removes a specific trigger card.

### `boostgpt.dismissAll()`

Removes all active trigger cards.

## 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();
boostgpt.trigger('event-name', context, { text: 'Need help?' });
```

## Custom Trigger 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 custom triggers:

```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();
});
```