JavaScript API - Decimal

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 is enabled.
`metadata`	object	Key-value pairs included with escalation tickets (e.g. account ID, plan type).

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.

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 Esc closes the widget.

Decimal.hide()

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

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.

Decimal.hideButton();
Decimal.showButton();

The widget can still be opened while the button is hidden by calling Decimal.show().

Decimal.shutdown()

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

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.

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

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

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?',
  ],
});

​Decimal.boot(options)

​Decimal.show(options)

​Decimal.hide()

​Decimal.showButton() / Decimal.hideButton()

​Decimal.shutdown()

​Decimal.update(options)

​Decimal.theme(options)

​Colors

​Position & Size

​Button Position

​Content