GenAI Widget 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>

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

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.

Option	Type	Default	Description
`primaryColor`	String	`"#1E3264"`	Primary brand color (button background, etc.)
`secondaryColor`	String	`"#1E3264"`	Secondary color
`userDialogBackgroundColor`	String	`"#89ED96"`	Background color for user message bubbles
`systemDialogBackgroundColor`	String	`"#1E3264"`	Background color for system/assistant message bubbles
`textColor`	String	`"#051024"`	Primary text color
`secondaryTextColor`	String	`"#1E3264"`	Secondary text color
`buttonTextColor`	String	`"#ffffff"`	Text color on the floating chat button
`buttonPosition`	String	`"bottom-right"`	Position of the floating button. Options: `top-left`, `top-right`, `bottom-left`, `bottom-right`
`buttonIcon`	String	(default star SVG)	URL to an image or inline SVG for the button icon
`buttonRadius`	String	`"99999px"`	Border radius of the button (e.g. `"8px"` or `"99999px"` for pill)
`logoUrl`	String	Preferabli logo URL	Logo displayed in the chat UI
`systemProfilePictureUrl`	String	Preferabli icon URL	Avatar for the assistant in the chat

Content Configuration (Server-Side)

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

Option	Type	Default	Description
`welcomeTitle`	String	`"Hi there!"`	Title on the welcome screen
`welcomeMessage`	String	`"How can I help you today?"`	Short message below the title
`welcomeBulletPoints`	Array of Strings	`["Explore our products", "Food pairings", "Check availability"]`	Bullet points shown on the welcome screen
`welcomeButtonText`	String	`"Let's begin!"`	Label of the button that starts the chat

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

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();

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();