Overview

The Tugi Widget exposes public API functions that allow clients to:

- Open and close the widget

- Check notification state

- Subscribe to notification changes in real-time

- Control default button visibility through configuration

‍

Available API Functions

Widget Control Functions

window.tugiWidget.openWidget()

Opens the widget dialog and clears any notification state.

javascript
// Open the widget
window.tugiWidget.openWidget();

window.tugiWidget.closeWidget()

Closes the widget dialog.

javascript
// Close the widget
window.tugiWidget.closeWidget();

State Management Functions

window.tugiWidget.isInitialized()

Returns whether the widget has been initialized.

javascript
// Check if widget is ready
if (window.tugiWidget.isInitialized()) {   
	// Safe to use widget functions   
	window.tugiWidget.openWidget();
    }

window.tugiWidget.onWidgetReady()

Returns a Promise that resolves when the widget is initialized. This is useful for waiting for the widget to be ready before interacting with it.

javascript
// Wait for widget to be ready
window.tugiWidget.onWidgetReady().then(() => {   
	// Widget is now ready and safe to use   
    window.tugiWidget.openWidget();   
    console.log('Widget is ready!');
    }).catch(error => {   
    	console.error('Widget failed to initialize:', error);
        });

window.tugiWidget.waitForWidgetReady()

Async function that waits for the widget to be ready. This is a convenience wrapper around `onWidgetReady()`.

javascript
// Using async/await
async function setupWidget() {   
	try {       
    	await window.tugiWidget.waitForWidgetReady();       
        // Widget is now ready       
        window.tugiWidget.openWidget();   
    } catch (error) {       
        console.error('Failed to wait for widget:', error);   
    }
}

window.tugiWidget.getWebSocketConnectionState()

Returns the current WebSocket connection state.

javascript
// Check connection status
const isConnected = window.tugiWidget.getWebSocketConnectionState();if (isConnected) {   
	console.log('Widget is connected and ready');
}

Notification Functions

window.tugiWidget.hasNotification()

Returns the current notification state (boolean).

javascript
// Check if there's a notification
const hasNotification = window.tugiWidget.hasNotification();
if (hasNotification) {   
	// Show notification indicator   
    showNotificationBadge();
}

window.tugiWidget.onNotificationChange(callback)

Subscribes to notification state changes. Returns an unsubscribe function for cleanup.

javascript
// Subscribe to notification changes
const unsubscribe = window.tugiWidget.onNotificationChange((hasNotification) => {   
	if (hasNotification) {       
    	// Show notification indicator       
        showNotificationBadge();       
        console.log('New message received!');   
    } else {       
    	// Hide notification indicator       
        hideNotificationBadge();       
        console.log('No new messages');
    }
});‍

// Later, cleanup the listener
unsubscribe();

‍

The widget also dispatches a `tugi-widget-notification` CustomEvent for each notification change, so you can alternatively use standard DOM event listeners.

Custom Events

The widget dispatches standard DOM events for better web compatibility:

tugi-widget-notification

Dispatched when notification state changes.

javascript
document.addEventListener('tugi-widget-notification', (event) => {
	const hasNotification = event.detail.hasNotification;   
    if (hasNotification) {       
    	showNotificationBadge();   
    } else {       
    	hideNotificationBadge();   
    }
});

tugi-widget-opened

Dispatched when the widget is opened.

javascript
document.addEventListener('tugi-widget-opened', () => {   
	console.log('Widget opened');
});

tugi-widget-closed

Dispatched when the widget is closed.

javascript
document.addEventListener('tugi-widget-closed', () => {   
	console.log('Widget closed');
});

tugi-widget-ready

Dispatched when the widget is ready and initialized.

javascript
document.addEventListener('tugi-widget-ready', () => {   
	console.log('Widget is ready!');   
    // Safe to interact with widget now   
    window.tugiWidget.openWidget();
});

Configuration Options

Hiding the Default Button

You can hide the default button when initializing the widget by setting `showDefaultFloatingButton: false` in the configuration:

javascript
window.tugiWidget.initialize({   
	jwtFn: () => Promise.resolve('your-jwt-token'),
    tenantId: 'your-tenant-id',   
    brandId: 'your-brand-id',   
    brandName: 'Your Brand',   
    customize: {
    showDefaultFloatingButton: false, // This will hide the default button
    // ... other customization options
    }
});

Error Handling

The API functions are designed to be safe and will not throw errors if called before the widget is initialized. However, it's recommended to ensure the widget is properly initialized before calling these functions.

javascript
// Safe way to call API functions
if (window.tugiWidget && window.tugiWidget.isInitialized())
	{window.tugiWidget.openWidget();
    }‍
// Safe way to setup notification listener
if (window.tugiWidget && typeof window.tugiWidget.onNotificationChange === 'function') {   
const unsubscribe = window.tugiWidget.onNotificationChange((hasNotification) => {
		// Handle notification change
    // Cleanup when done
    unsubscribe();
}

Best Practices

1. **Use `onNotificationChange()` or CustomEvents instead of polling** - Both provide real-time updates
2. **Always cleanup listeners** - Use the returned unsubscribe function or `removeEventListener()` to prevent memory leaks
3. **Check initialization state** - Use `isInitialized()` before calling widget functions
4. **Monitor connection state** - Use `getWebSocketConnectionState()` to ensure the widget is connected
5. **Initialize with `showDefaultFloatingButton: false`** if you plan to use custom triggers
6. **Clear notifications when widget opens** - The widget automatically clears notifications when opened

‍

API Reference Summary

‍

‍

The notification system automatically updates when new messages are received via WebSocket, providing real-time feedback to your users! 🚀

‍

Last Updated: [2025-10-04]