Skip to main content

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​

PropertyTypeDescription
baseUrlstringOrigin the widget is served from -- not the API host it calls.
websiteTokenstringWebsite token identifying this widget instance and the agent it's bound to.
hasLoadedbooleanWhether the widget iframe has finished loading.
isOpenbooleanWhether the chat panel is currently open.
position'left' | 'right'Bubble position on the page.
localestringActive locale code (e.g., 'en', 'id').
colorScheme'light' | 'dark' | 'auto'Active color scheme.
type'standard' | 'expanded'Bubble view type.
hideMessageBubblebooleanWhether the launcher bubble is hidden.
launcherTitlestringText displayed on the expanded bubble.
displayModestringWidget 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",
	customAttributes: {
		plan: "premium",
	},
});

To cryptographically verify the session's user, also pass identity to run() -- see Identity Verification.

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

The popout window opens immediately (to preserve the click gesture) and is verified once it has loaded. If origin verification is enabled in strict/required mode on your account and that verification is explicitly rejected, the visitor will see a message asking them to return to the site. Other failures (for example, no verification could be obtained) let the popout open, but it may not become interactive.

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.ailovina.com",
		});
	}
	window.$lovina.toggle("open");
});