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.

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

window.tugiWidget.closeWidget()

Closes the widget dialog.

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

State Management Functions

window.tugiWidget.isInitialized()

Returns whether the widget has been initialized.

// 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.

// Wait for widget to be ready
window.tugiWidget.onWidgetReady()
  .then(() => {
    // Widget is now ready and safe to use
    window.tugiWidget.openWidget();
  })
  .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()`.

// 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.

// 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).

// 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.

// 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.

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.

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

tugi-widget-closed

Dispatched when the widget is closed.

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

tugi-widget-ready

Dispatched when the widget is ready and initialized.

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:

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.

// 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]