Configuration Reference

All configuration is set via window.lovinaSettings before calling window.lovinaChatSDK.run(). Settings are read once during initialization. To change settings at runtime, use the JavaScript API.

window.lovinaSettings = {
  position: 'right',
  displayMode: 'popup',
  colorScheme: 'auto',
  locale: 'en',
  branding: { /* ... */ },
  theme: { /* ... */ },
  texts: { /* ... */ },
  features: { /* ... */ },
};

Identity Verification (optional)

note

Identity verification is enforced per channel in off, monitor, or required mode. See Enforcement Modes for what each mode does, and When Verification Happens for when the check runs.

Passed to window.lovinaChatSDK.run() directly -- not window.lovinaSettings -- since it's a signed credential rather than a display setting.

window.lovinaChatSDK.run({
  baseUrl: 'https://chat.ailovina.com',
  websiteToken: 'YOUR_TOKEN',
  identity: {
    mode: 'user',
    userId: 'user-123',
    exp: 1735689600,
    sigHash: 'server-computed-hmac-hash',
  },
});

Option	Type	Description
`mode`	`'user'`	Identity mode. Only `'user'` is available today.
`userId`	`string`	The same user ID you pass to `setUser()`.
`exp`	`number`	Unix timestamp (seconds) after which the signature expires.
`sigHash`	`string`	HMAC signature computed on your server -- never in the browser.

Compute sigHash on your server, HMAC-SHA256 over exp:userId using your channel's signing secret. See the User Identification guide for sample code in Java, Node.js, Python, PHP, Ruby, and Go.

warning

Never compute sigHash in client-side code -- your signing secret must stay on your server.

Omit identity only on an off channel -- see Enforcement Modes.

Display Settings

Option	Type	Default	Description
`position`	`'left'` \| `'right'`	`'right'`	Which side of the screen the launcher bubble appears on.
`displayMode`	`'popup'` \| `'sidebar'` \| `'fullscreen'`	`'popup'`	How the chat panel renders. See Display Modes.
`type`	`'standard'` \| `'expanded'`	`'standard'`	Bubble style. `'standard'` shows an icon only; `'expanded'` shows an icon with text.
`hideMessageBubble`	`boolean`	`false`	When `true`, the launcher bubble is hidden. Use `$lovina.toggle('open')` to open programmatically.
`launcherTitle`	`string`	`''`	Text displayed next to the bubble icon when `type` is `'expanded'`.
`sidebarWidth`	`number`	`undefined`	Width in pixels when `displayMode` is `'sidebar'`.
`sidebarOverlay`	`boolean`	`undefined`	When `true`, sidebar overlays page content. When `false`, page content is pushed aside.

Appearance Settings

Option	Type	Default	Description
`colorScheme`	`'light'` \| `'dark'` \| `'auto'`	`'light'`	Color scheme. `'auto'` follows the user's OS preference.
`locale`	`string`	`'id'`	BCP 47 locale code (e.g., `'en'`, `'id'`, `'pt-BR'`). See Internationalization.
`useBrowserLanguage`	`boolean`	`true`	Auto-detect locale from `navigator.language`. Overrides `locale` if a match is found.

Branding

White-label configuration for replacing default assets and text. Set poweredBy: false for a fully white-labeled experience.

window.lovinaSettings = {
  branding: {
    brandName: 'Acme Support',
    logoUrl: 'https://example.com/logo.svg',
    bubbleIconUrl: 'https://example.com/bubble-icon.svg',
    faviconUrl: 'https://example.com/favicon.ico',
    poweredBy: false,
  },
};

Option	Type	Default	Description
`brandName`	`string`	`undefined`	Name displayed in the chat header (e.g., `'Acme Support'`).
`logoUrl`	`string`	`undefined`	URL to a custom logo image shown in the chat header.
`bubbleIconUrl`	`string`	`undefined`	URL to a custom icon for the launcher bubble. Should be SVG or PNG, 24x24 or 32x32 px with transparent background.
`faviconUrl`	`string`	`undefined`	URL to a custom favicon used in the popout chat window.
`poweredBy`	`boolean`	`true`	Show the "Powered by Lovina" footer. Set to `false` for full white-label.

Theme

Customize the widget's visual appearance. Only primaryColor is required -- all other colors are automatically generated using an algorithm that ensures WCAG AA contrast compliance (4.5:1 minimum ratio).

window.lovinaSettings = {
  theme: {
    primaryColor: '#6366F1',
  },
};

How Auto-Generation Works

When you set only primaryColor, the SDK converts your color to HSL, determines whether it is light or dark, and generates complementary background, text, bubble, and border colors -- all checked against WCAG AA contrast requirements.

Full Theme Options

Option	Type	Default	Description
`primaryColor`	`string`	`undefined`	Primary brand color for user bubbles, buttons, and accents.
`primaryTextColor`	`string`	auto	Text color on primary-colored surfaces.
`backgroundColor`	`string`	auto	Chat panel background color.
`agentBubbleColor`	`string`	auto	Background color of agent message bubbles.
`agentBubbleTextColor`	`string`	auto	Text color inside agent message bubbles.
`userBubbleColor`	`string`	auto	Background of user message bubbles. Defaults to `primaryColor`.
`userBubbleTextColor`	`string`	auto	Text color inside user message bubbles.
`textColor`	`string`	auto	Main body text color.
`secondaryTextColor`	`string`	auto	Secondary/muted text color (timestamps, hints).
`inputColor`	`string`	auto	Input field background color.
`borderColor`	`string`	auto	Border color for cards, inputs, and dividers.
`fontFamily`	`string`	system default	CSS font-family (e.g., `'Inter, sans-serif'`).
`fontSize`	`number`	`14`	Base font size in pixels.
`borderRadius`	`number`	`undefined`	Border radius in pixels for cards and panels.
`bubbleRadius`	`number`	`undefined`	Border radius in pixels for message bubbles.
`buttonRadius`	`number`	`undefined`	Border radius in pixels for buttons.
`bubbleSize`	`number`	`64`	Launcher bubble diameter in pixels.
`bubbleColor`	`string`	`primaryColor`	Launcher bubble background color.
`bubbleIconColor`	`string`	auto	Launcher bubble icon color.
`bubbleShadow`	`boolean`	`true`	Show a drop shadow on the launcher bubble.

Feature Flags

Feature flags control which widget capabilities are enabled. All default to sensible values. Override only the ones you need.

window.lovinaSettings = {
  features: {
    enable_file_upload: true,
    enable_emoji_picker: true,
    enable_sound_notification: true,
  },
};

Transport Flags

Flag	Default	Description
`enable_websocket`	`true`	Enable WebSocket transport (preferred, fastest).
`enable_sse`	`true`	Enable Server-Sent Events transport (fallback).
`enable_long_polling`	`true`	Enable long-polling transport (final fallback).

UI Flags

Flag	Default	Description
`enable_voice_input`	`true`	Show voice input button in the composer.
`enable_emoji_picker`	`false`	Show emoji picker button in the composer.
`enable_file_upload`	`true`	Allow file and image uploads.
`enable_typing_indicator`	`true`	Show typing indicator when the agent is composing.
`enable_read_receipts`	`true`	Show read receipt indicators on messages.
`enable_prechat_form`	`false`	Show a pre-chat form before starting a conversation.
`enable_end_conversation`	`true`	Allow the user to end/resolve the conversation.
`enable_popout_window`	`false`	Show a button to pop out chat into a standalone window.
`enable_sound_notification`	`true`	Play a sound when a new message arrives.

Display Flags

Flag	Default	Description
`enable_sidebar_mode`	`true`	Allow the widget to render in sidebar mode.
`enable_conversation_history`	`true`	Show list of past conversations.
`enable_new_conversation`	`true`	Allow starting a new conversation.
`enable_dark_mode`	`true`	Allow toggling dark mode within the widget.
`enable_unread_badge`	`true`	Show unread message count badge on the bubble.

Advanced Flags

Flag	Default	Description
`enable_campaigns`	`false`	Enable proactive campaign messages.
`enable_csat`	`false`	Enable customer satisfaction surveys.
`enable_analytics_events`	`true`	Emit analytics events for tracking widget usage.
`debug_mode`	`false`	Enable debug logging to the browser console.

Feature flags are merged in a 3-layer strategy: server defaults, SDK defaults, then your client overrides (highest priority).

Text Overrides

Override any default UI string by providing a nested object matching the translation key structure. Overrides take priority over locale-specific translations.

window.lovinaSettings = {
  texts: {
    welcome: {
      title: 'Welcome to Acme!',
      message: 'How can our team help you today?',
    },
    input: {
      placeholder: 'Type your question here...',
    },
    header: {
      title: 'Acme Help Desk',
    },
  },
};

See the Internationalization guide for the full list of translation keys.

Complete Example

window.lovinaSettings = {
  position: 'right',
  displayMode: 'popup',
  type: 'expanded',
  launcherTitle: 'Chat with us',
  colorScheme: 'auto',
  locale: 'en',
  branding: {
    brandName: 'Acme Support',
    logoUrl: 'https://example.com/logo.svg',
    poweredBy: false,
  },
  theme: {
    primaryColor: '#6366F1',
    fontFamily: 'Inter, system-ui, sans-serif',
    borderRadius: 16,
    bubbleSize: 60,
  },
  texts: {
    welcome: {
      title: 'Hi there!',
      message: 'How can we help?',
    },
  },
  features: {
    enable_file_upload: true,
    enable_emoji_picker: true,
    enable_sound_notification: true,
    debug_mode: false,
  },
};

Identity Verification (optional)​

Display Settings​

Appearance Settings​

Branding​

Theme​

How Auto-Generation Works​

Full Theme Options​

Feature Flags​

Transport Flags​

UI Flags​

Display Flags​

Advanced Flags​

Text Overrides​

Complete Example​