Configure your installation
Set options before loading or update supported appearance and behavior at runtime.
Initial configuration
Put this object before the loader. The same appearance renderer is used by Settings previews and installed widgets.
window.TruComWidgetConfig = {
color: '#245b46',
orientation: 'left',
offsetX: 24,
offsetY: 24,
hideMobileWidget: false,
helpEnabled: true,
serviceStatusEnabled: true
};Runtime configuration
Runtime overrides stay on the current page. They do not silently update workspace settings. Saved defaults are reapplied on a new page; options provided by that page then take precedence. An availability refresh preserves current runtime overrides.
await TruComWidget.configure({
color: '#245b46',
launcherLabel: 'Ask our team',
showLauncherLabel: true,
helpEnabled: false
});Supported options
| Option | Behavior |
|---|---|
| color, agentBubbleColor, agentTextColor, customerBubbleColor, customerTextColor | Six-digit hex colour; #111111 is the default primary colour. |
| theme | system, light or dark. |
| orientation / position | left or right; or a full position: top_left, top_right, center_left, center_right, bottom_left, bottom_right. |
| offsetX, offsetY | Integer pixels from 0 to 120. |
| launcherIcon | chat, messages, help or headset. |
| launcherSize / launcherShape | compact, standard, large / round, rounded. |
| launcherLabel / showLauncherLabel | Text label up to 240 characters / boolean. |
| panelSize / panelMaxHeight | compact, standard, wide / 440–900 desktop pixels. Mobile remains full height. |
| cornerRadius | 8–32 pixels. |
| fontFamily / textSize | system, rounded, serif / compact, standard, comfortable. |
| logoUrl | HTTPS image URL. Empty uses the configured workspace fallback. |
| showThemeToggle / showBranding | Boolean visibility preferences. |
| headerTitle, greetingTitle, greetingMessage, replyExpectation, inputPlaceholder, startButtonLabel, awayMessage | Text overrides, up to 500 characters each. |
| labels | Object containing documented label keys; each value up to 240 characters. |
| helpEnabled / serviceStatusEnabled | Widget display only. Public knowledge and status services stay active. |
| ratingEnabled, reviewEnabled, fileUploadsEnabled, endConversationEnabled | Boolean; enabling requires that capability to be enabled in widget settings. |
| hideWidget | Hide the widget on this page. open() rejects until shown again. |
| hideMobileWidget / hideDesktopWidget | Hide on the selected device category. |
| hideLauncher | Hide the default launcher; your own support button can still open the panel. |
| privacyNoticeEnabled / privacyNoticeUrl | Privacy link visibility / HTTPS privacy URL. |
| privacyNoticeCheckRequired / consentText | Require consent for this visitor session / text for that consent. A true requirement stays latched until session reset. |
| preChatEnabled | May enable pre-chat. It cannot bypass pre-chat requirements saved by the workspace. |
| language | BCP 47 language code. Core labels have built-in translations described in Localization. |
| customCss / launcherCss | Styles within the panel iframe / launcher shadow root, up to 20,000 characters each. |
| cookieDomain | Initial configuration only. Parent domain for an optional non-secret first-party visitor-context cookie. |
| gaKey | Optional GA4 measurement ID. Requires your own gtag or dataLayer setup. |
| displayMode / container | Initial configuration only: floating (default) or embedded; container is a CSS selector for embedded mode. |
| mobileMode | Initial configuration only: true to use mobile presentation in an embedded app. |
| nativeBridge | Opt-in native command/result and event bridge. |
Validation and capabilities
Unknown option names and invalid types reject with invalid_configuration. Container, display mode, cookie domain and mobile mode must be chosen before frame creation. Required workspace identity, pre-chat, consent, routing and file rules are enforced by the server. Appearance options do not grant access to history or enable disabled backend capabilities.