JavaScript API

After the SDK initializes, a global object window.$lovina is available for programmatic control. Wait for the lovina:ready event before calling these methods.

Properties

Property	Type	Description
baseUrl	string	Base URL of the Lovina backend.
websiteToken	string	Website token identifying this widget instance.
hasLoaded	boolean	Whether the widget iframe has finished loading.
isOpen	boolean	Whether the chat panel is currently open.
position	'left' | 'right'	Bubble position on the page.
locale	string	Active locale code (e.g., 'en', 'id').
darkMode	'light' | 'dark' | 'auto'	Active color scheme.
type	'standard' | 'expanded'	Bubble view type.
hideMessageBubble	boolean	Whether the launcher bubble is hidden.
launcherTitle	string	Text displayed on the expanded bubble.
displayMode	string	Widget display mode ('popup', 'sidebar', or 'fullscreen').

Methods

toggle(state?)

Open, close, or toggle the chat panel.

// Toggle open/close
window.$lovina.toggle();

// Force open
window.$lovina.toggle('open');

// Force close
window.$lovina.toggle('close');

toggleBubbleVisibility(visibility)

Show or hide the launcher bubble without affecting the chat panel state.

window.$lovina.toggleBubbleVisibility('hide');
window.$lovina.toggleBubbleVisibility('show');

setUser(identifier, user)

Identify the current user. Associates the chat session with a known user from your system.

window.$lovina.setUser('user-12345', {
  name: 'Jane Doe',
  email: 'jane@example.com',
  avatarUrl: 'https://example.com/jane.jpg',
  phoneNumber: '+6281234567890',
  companyName: 'Acme Corp',
});

For production deployments, include an HMAC-SHA256 hash to prevent user impersonation:

window.$lovina.setUser('user-12345', {
  name: 'Jane Doe',
  email: 'jane@example.com',
  identifierHash: 'HMAC_SHA256_HASH_HERE', // Generated server-side
});

tip

Call setUser as early as possible -- ideally right after the lovina:ready event fires. This ensures the conversation is linked to the correct user from the start.

setCustomAttributes(attrs)

Set custom attributes on the current contact. These are visible to agents and can be used for segmentation and routing.

window.$lovina.setCustomAttributes({
  plan: 'premium',
  signup_date: '2025-01-15',
  account_value: 5000,
});

deleteCustomAttribute(key)

Remove a single custom attribute from the current contact.

window.$lovina.deleteCustomAttribute('signup_date');

setConversationCustomAttributes(attrs)

Set custom attributes on the active conversation.

window.$lovina.setConversationCustomAttributes({
  order_id: 'ORD-789',
  priority: 'high',
});

deleteConversationCustomAttribute(key)

Remove a single custom attribute from the active conversation.

window.$lovina.deleteConversationCustomAttribute('order_id');

setLabel(label)

Add a label to the active conversation. Labels help agents categorize and filter conversations.

window.$lovina.setLabel('billing');

removeLabel(label)

Remove a label from the active conversation.

window.$lovina.removeLabel('billing');

setLocale(locale)

Change the widget locale at runtime. The UI updates immediately.

window.$lovina.setLocale('id');  // Switch to Indonesian
window.$lovina.setLocale('en');  // Switch to English

setColorScheme(mode)

Change the color scheme at runtime.

window.$lovina.setColorScheme('dark');
window.$lovina.setColorScheme('light');
window.$lovina.setColorScheme('auto'); // Follow OS preference

reset()

Reset the widget session, clearing user identity and conversation state. The widget returns to a fresh, anonymous state.

// Example: reset on user logout
function onUserLogout() {
  window.$lovina.reset();
}

popoutChatWindow()

Open the chat in a standalone browser window (400x640 pixels). Useful for users who want to continue chatting while navigating your site.

window.$lovina.popoutChatWindow();

destroy()

Fully destroy the SDK: removes all DOM elements, disconnects observers, clears cookies, and deletes window.$lovina.

window.$lovina.destroy();

warning

After calling destroy(), you must call window.lovinaChatSDK.run() again to reinitialize the widget.

Common Patterns

Initialize and Identify User

window.addEventListener('lovina:ready', function() {
  window.$lovina.setUser('user-123', {
    name: 'Jane Doe',
    email: 'jane@example.com',
  });
});

Open Chat from a Custom Button

<button onclick="window.$lovina.toggle('open')">
  Need help?
</button>

SPA Logout Flow

async function logout() {
  window.$lovina.reset();
  await authService.signOut();
  router.push('/login');
}

Lazy Initialization

If chat is not critical for every page, defer initialization until the user signals intent:

document.getElementById('help-btn').addEventListener('click', function() {
  if (!window.$lovina) {
    window.lovinaChatSDK.run({
      websiteToken: 'YOUR_TOKEN',
      baseUrl: 'https://chat.lovina.app',
    });
  }
  window.$lovina.toggle('open');
});