GenAI Chat Options

Script Tag Attributes

When you load the widget via a <script> tag, you can set these attributes on the script element.

data-api-key

Type: String
Required: Yes
Default: none

Your GenAI API key for authentication. The widget will not initialize without it.

<script
  src="%SCRIPT_URL%/genai-embeddable-widget.js"
  data-api-key="%API_KEY%"
></script>

data-hide-widget

Type: String
Required: No
Default: "false"

Set to "true" to hide the floating chat button. Use this when you want to open the widget only via your own UI (e.g. a custom button) by dispatching the genai-widget:open event.

<script
  src="%SCRIPT_URL%/genai-embeddable-widget.js"
  data-api-key="%API_KEY%"
  data-hide-widget="true"
></script>

data-locale

Type: String
Required: No
Default: "en"

Widget UI language. See Widget Language for the full list of supported codes.

<script
  src="%SCRIPT_URL%/genai-embeddable-widget.js"
  data-api-key="%API_KEY%"
  data-locale="en"
></script>

data-opt-out-tracking

Type: String
Required: No
Default: "false"

Set to "true" to opt the user out of tracking on initialization. Use this when your site uses an opt-in cookie/privacy policy and tracking should stay disabled until the user consents. See Opt Out Tracking for full details.

<script
  src="%SCRIPT_URL%/genai-embeddable-widget.js"
  data-api-key="%API_KEY%"
  data-opt-out-tracking="true"
></script>

---

Programmatic Options (WidgetInitConfig)

When you initialize the widget with new GenAIEmbeddableWidget(config), pass an object with these properties.

apiKey

Type: String
Required: Yes
Default: none

Your GenAI API key.

var widget = new GenAIEmbeddableWidget({
  apiKey: '%API_KEY%',
});

onReady

Type: Function
Required: No
Default: null

Callback invoked when the widget has finished initializing (styles injected, button and iframe created, config loaded).

var widget = new GenAIEmbeddableWidget({
  apiKey: '%API_KEY%',
  onReady: function() {
    console.log('Widget ready');
  },
});

locale

Type: String
Required: No
Default: "en"

Initial widget UI language. Overrides data-locale when both are set. See Widget Language for supported codes.

var widget = new GenAIEmbeddableWidget({
  apiKey: '%API_KEY%',
  locale: 'es',
});

optOutTracking

Type: Boolean
Required: No
Default: false

Allows you to opt a user out of tracking based on cookie consent or privacy preferences.
When enabled, tracking-related data will not be collected for the session.

This is typically triggered after a user declines cookies or opts out via a privacy control. For an opt-in cookie/privacy policy, initialize with optOutTracking: true, then switch to false when the user elects to opt in. See Opt Out Tracking for full details.

var widget = new GenAIEmbeddableWidget({
  apiKey: '%API_KEY%',
  optOutTracking: true, // disable tracking on initialization
});

// after the user accepts the tracking / cookie policy
widget.optOutTracking(false);

Notes:

• Can be toggled dynamically after initialization via optOutTracking(optOut) or the genai-widget:opt-out-tracking event
• Recommended to integrate with your site's cookie consent manager
• Applies to all instances of Preferabli Widgets

---

Theme Configuration (Server-Side)

Theme options are managed in the Preferabli dashboard and fetched by the widget at runtime. They are not passed in the client-side script. The following defaults apply when not overridden in the dashboard.

---

Content Configuration (Server-Side)

Welcome screen content is also managed in the Preferabli dashboard. These defaults apply when not overridden.

---

Widget Control Events

You can open, close, or toggle the chat by dispatching custom events on window. This works whether you initialized via script tag (auto-init) or programmatically.

genai-widget:open

Opens the chat panel.

window.dispatchEvent(new CustomEvent('genai-widget:open'));

genai-widget:close

Closes the chat panel.

window.dispatchEvent(new CustomEvent('genai-widget:close'));

genai-widget:toggle

Toggles the chat panel (open if closed, close if open).

window.dispatchEvent(new CustomEvent('genai-widget:toggle'));

genai-widget:ready

Fired when the widget is fully loaded and ready. Listen only (do not dispatch).

window.addEventListener('genai-widget:ready', function() {
  console.log('Widget is ready');
});

genai-widget:set-locale

Updates the widget locale at runtime without reloading the page.

window.dispatchEvent(new CustomEvent('genai-widget:set-locale', {
  detail: { locale: 'es' },
}));

genai-widget:opt-out-tracking

Opts the user out of (or back into) tracking at runtime. Pass detail.optOut as true to disable tracking, or false to enable it. See Opt Out Tracking.

window.dispatchEvent(new CustomEvent('genai-widget:opt-out-tracking', {
  detail: { optOut: true },
}));

// enable tracking after the user accepts the cookie / privacy policy
window.dispatchEvent(new CustomEvent('genai-widget:opt-out-tracking', {
  detail: { optOut: false },
}));

---

Public Methods

When you have a reference to the widget instance (e.g. var widget = new GenAIEmbeddableWidget({ apiKey: '...' });), you can call these methods.

open()

Opens the chat panel.

widget.open();

close()

Closes the chat panel.

widget.close();

toggle()

Toggles the chat panel open or closed.

widget.toggle();

setLocale(locale)

Updates the widget locale at runtime. See Widget Language for supported codes.

widget.setLocale('es');

optOutTracking(optOut)

Opts the user out of (or back into) tracking. See Opt Out Tracking.

Parameters:

• optOut (Boolean) — true to disable tracking; false to enable tracking

var widget = new GenAIEmbeddableWidget({
  apiKey: '%API_KEY%',
  optOutTracking: true, // disable tracking on initialization
});

// enable tracking after the tracking policy is accepted
widget.optOutTracking(false);

destroy()

Removes the widget from the page (floating button and iframe) and cleans up event listeners. Use this when unmounting the widget from a single-page app or when the user logs out.

widget.destroy();