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',
  darkMode: 'auto',
  locale: 'en',
  branding: { /* ... */ },
  theme: { /* ... */ },
  texts: { /* ... */ },
  features: { /* ... */ },
};

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
darkMode	'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.
colorScheme	'light' | 'dark' | 'auto'	undefined	Color scheme override for this widget instance.

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	false	Show voice input button in the composer.
enable_emoji_picker	true	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	false	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	false	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',
  darkMode: '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,
  },
};