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

# JavaScript API

> Control the chat widget programmatically with the Decimal JavaScript API.

The widget exposes a global `Decimal` object with the following methods.

## Decimal.boot(options)

Manually initializes the widget. Required when using `data-disable-autoboot`.

| Parameter    | Type   | Description                                                                                                                     |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `user_token` | string | A signed JWT for authenticated sessions. Required when [identity verification](/chat-widgets/identity-verification) is enabled. |
| `metadata`   | object | Key-value pairs included with escalation tickets (e.g. account ID, plan type).                                                  |

```js theme={null}
Decimal.boot({
  user_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  metadata: {
    account_id: 'id_asdf',
    plan: 'enterprise',
  }
});
```

## Decimal.show(options)

Opens the chat widget programmatically. Equivalent to clicking the launcher button.

| Parameter      | Type   | Description                                                                                                                                                            |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `presentation` | string | `'modal'` opens the widget as a centered modal with a backdrop instead of the corner popup. Defaults to the standard floating popup. Ignored in sidebar display modes. |

```js theme={null}
Decimal.show();

// Open as a centered modal
Decimal.show({ presentation: 'modal' });
```

If called before the widget has finished loading, the open is queued and runs once it's ready. In modal presentation, clicking the backdrop or pressing <kbd>Esc</kbd> closes the widget.

## Decimal.hide()

Closes the chat widget programmatically. Equivalent to clicking the launcher button again.

```js theme={null}
Decimal.hide();
```

## Decimal.showButton() / Decimal.hideButton()

Show or hide the launcher button without removing the widget. Unlike the `data-hide-button` attribute (which hides the button for the entire session), these toggle it at runtime — for example, hiding the launcher on certain pages or revealing it after a user action.

```js theme={null}
Decimal.hideButton();
Decimal.showButton();
```

The widget can still be opened while the button is hidden by calling [`Decimal.show()`](#decimalshowoptions).

## Decimal.shutdown()

Removes the chat widget completely. Call `Decimal.boot()` again to restart from scratch.

```js theme={null}
Decimal.shutdown();
```

## Decimal.update(options)

Updates widget metadata after initialization. Merged with existing metadata and included when escalating to a human.

| Parameter  | Type   | Description                                      |
| ---------- | ------ | ------------------------------------------------ |
| `metadata` | object | Key-value pairs to merge with existing metadata. |

```js theme={null}
Decimal.update({
  metadata: {
    account_id: 'id_asdf',
    plan: 'enterprise',
  }
});
```

The widget automatically tracks the current page and includes it in metadata as `_pageUrl` and `_pageTitle` (query strings are stripped to avoid leaking tokens or PII). Single-page-app navigations are detected and synced automatically — you don't need to call `update()` on route changes.

## Decimal.theme(options)

Customizes widget appearance. Can be called before or after `Decimal.boot()`. To reset to defaults, call `Decimal.theme(Decimal.DEFAULT_THEME)`.

```js theme={null}
Decimal.theme({
  colorScheme: 'dark',
  primaryColor: '#3B82F6',
  backgroundColor: '#18181B',
  textColor: '#FAFAFA',
  textColorSecondary: '#FFFFFF',
  textColorMuted: '#A1A1AA'
});
```

### Colors

| Parameter            | Description                                                       | Default   |
| -------------------- | ----------------------------------------------------------------- | --------- |
| `colorScheme`        | `'light'` \| `'dark'` \| `'auto'`. Controls browser color scheme. | `'light'` |
| `primaryColor`       | Launcher button, user message bubbles, action buttons.            | `#18181B` |
| `backgroundColor`    | Widget background color.                                          | `#FFFFFF` |
| `textColor`          | Headings, body text, input labels, "Powered by Decimal".          | `#18181B` |
| `textColorSecondary` | Text on primary-colored elements (user messages, buttons).        | `#FFFFFF` |
| `textColorMuted`     | Timestamps, secondary labels, metadata.                           | `#71717A` |
| `borderColor`        | Widget border and internal dividers.                              | none      |

Pass `null` for any color to reset it to the component default.

### Position & Size

These options only affect the widget container in floating mode, designed for use with `data-hide-button`. All values are CSS strings (e.g. `'20px'`, `'50%'`).

| Parameter         | Description                | Default        |
| ----------------- | -------------------------- | -------------- |
| `width`           | Widget width.              | `380px`        |
| `height`          | Widget height.             | `640px`        |
| `top`             | Distance from top edge.    | `unset`        |
| `bottom`          | Distance from bottom edge. | `80px`         |
| `left`            | Distance from left edge.   | `unset`        |
| `right`           | Distance from right edge.  | `20px`         |
| `transformOrigin` | Animation origin point.    | `bottom right` |

### Button Position

Position the launcher button independently from the widget container.

| Parameter      | Description                       | Default |
| -------------- | --------------------------------- | ------- |
| `buttonTop`    | Button distance from top edge.    | `unset` |
| `buttonBottom` | Button distance from bottom edge. | `20px`  |
| `buttonLeft`   | Button distance from left edge.   | `unset` |
| `buttonRight`  | Button distance from right edge.  | `20px`  |

### Content

`theme()` also accepts content overrides for the widget's header and greeting. These can be set here or via [data attributes](/chat-widgets/installation#data-attributes) on the script tag.

| Parameter           | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `headerTitle`       | Title shown in the widget header.                            |
| `headerSubtitle`    | Subtitle shown under the header title.                       |
| `greeting`          | Greeting headline shown on the empty conversation screen.    |
| `greetingSubtitle`  | Text shown under the greeting headline.                      |
| `suggestedMessages` | Array of up to 6 prompt strings shown as one-click starters. |

```js theme={null}
Decimal.theme({
  headerTitle: 'Acme Support',
  greeting: 'Hi there 👋',
  greetingSubtitle: 'Ask us anything about your account.',
  suggestedMessages: [
    'How do I reset my password?',
    'Where can I find my invoices?',
  ],
});
```