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 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. The data-hide-button attribute hides it for the whole session; these two toggle it at runtime, so you can drop the launcher on certain pages or reveal it after the user does something.

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 tracks the current page itself and adds it to metadata as _pageUrl and _pageTitle, with query strings stripped so tokens and PII don’t leak. Single-page-app navigation is picked up too, so route changes need no update() call from you.

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.
`placeholderText`	Placeholder text shown in the chat input field. Defaults to “Ask anything…”.
`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?',
  ],
});

Getting Started

Support

Agents

Knowledge Base

Playground

Chat Widgets

Integrations

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

​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

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