JavaScript API

Complete reference for programmatically controlling the Infinity Widget and handling events.

Getting Widget Reference

// Get widget element
const widget = document.querySelector('infinity-widget');

// Or by ID
const widget = document.getElementById('my-widget');

// Wait for widget to be ready
await customElements.whenDefined('infinity-widget');

Methods

Message Management

// Send a message programmatically
widget.sendMessage('Hello from JavaScript!');

// Clear all messages
widget.clearMessages();

// Get current message history
const messages = widget.getMessages();

Connection Management

// Connect to WebSocket server
widget.connect();

// Disconnect from server
widget.disconnect();

// Check connection status
const isConnected = widget.isConnected();

Theme & Appearance

// Set theme programmatically
widget.setTheme('dark'); // 'light', 'dark', 'auto'

// Toggle theme
widget.toggleTheme();

// Get current theme
const currentTheme = widget.getTheme();

Floating Mode

// Toggle floating mode
widget.toggleFloatingMode();

// Minimize widget (floating mode only)
widget.minimize();

// Expand widget (floating mode only)
widget.expand();

// Check if minimized
const isMinimized = widget.isMinimized();

Language & Internationalization

// Set language
widget.setLanguage('es'); // ISO 639-1 language code

// Get current language
const currentLang = widget.getLanguage();

// Get available languages
const languages = widget.getAvailableLanguages();

State Management

// Get widget state
const state = widget.getState();

// Check if widget is disabled
const isDisabled = widget.isDisabled();

// Enable/disable widget
widget.setDisabled(true);
widget.setDisabled(false);

Events

The widget dispatches custom events for various interactions:

Connection Events

// Widget connected to server
widget.addEventListener('infinity-widget-connected', (event) => {
  console.log('Connected:', event.detail.url);
});

// Widget disconnected from server
widget.addEventListener('infinity-widget-disconnected', (event) => {
  console.log('Disconnected:', event.detail.reason);
});

// Connection error
widget.addEventListener('infinity-widget-connection-error', (event) => {
  console.log('Connection error:', event.detail.error);
});

Message Events

// Message sent by user
widget.addEventListener('infinity-widget-message-sent', (event) => {
  console.log('User sent:', event.detail.message);
  console.log('Timestamp:', event.detail.timestamp);
});

// Message received from bot
widget.addEventListener('infinity-widget-message-received', (event) => {
  console.log('Bot replied:', event.detail.message);
  console.log('Message ID:', event.detail.id);
});

// Chat cleared
widget.addEventListener('infinity-widget-chat-cleared', (event) => {
  console.log('Chat history cleared');
});

Theme Events

// Theme changed
widget.addEventListener('theme-changed', (event) => {
  console.log('Theme changed to:', event.detail.theme);
});

// System theme changed (auto mode)
widget.addEventListener('system-theme-changed', (event) => {
  console.log('System theme:', event.detail.theme);
});

Language Events

// Language changed
widget.addEventListener('infinity-widget-language-changed', (event) => {
  console.log('Language changed to:', event.detail.language);
  console.log('Previous language:', event.detail.previousLanguage);
});

UI Events

// Widget minimized (floating mode)
widget.addEventListener('infinity-widget-minimized', (event) => {
  console.log('Widget minimized');
});

// Widget expanded (floating mode)
widget.addEventListener('infinity-widget-expanded', (event) => {
  console.log('Widget expanded');
});

// Input focus/blur
widget.addEventListener('infinity-widget-input-focus', (event) => {
  console.log('Input focused');
});

widget.addEventListener('infinity-widget-input-blur', (event) => {
  console.log('Input blurred');
});

Advanced Usage

Custom Message Handling

// Intercept outgoing messages
widget.addEventListener('infinity-widget-message-sent', (event) => {
  const message = event.detail.message;
  
  // Add custom processing
  if (message.includes('/help')) {
    // Show custom help dialog
    showCustomHelp();
  }
});

// Process incoming messages
widget.addEventListener('infinity-widget-message-received', (event) => {
  const message = event.detail.message;
  
  // Custom message processing
  if (message.includes('special-command')) {
    // Trigger custom action
    handleSpecialCommand(message);
  }
});

Dynamic Configuration

// Update configuration dynamically
widget.setAttribute('theme', 'dark');
widget.setAttribute('welcome-message', 'New welcome message');

// React to attribute changes
const observer = new MutationObserver((mutations) => {
  mutations.forEach((mutation) => {
    if (mutation.type === 'attributes') {
      console.log(`Attribute ${mutation.attributeName} changed`);
    }
  });
});

observer.observe(widget, { 
  attributes: true, 
  attributeFilter: ['theme', 'language', 'disabled'] 
});

Error Handling

// Global error handling
widget.addEventListener('infinity-widget-error', (event) => {
  console.error('Widget error:', event.detail.error);
  console.error('Error type:', event.detail.type);
  
  // Handle different error types
  switch (event.detail.type) {
    case 'connection':
      showConnectionError();
      break;
    case 'validation':
      showValidationError(event.detail.message);
      break;
    default:
      showGenericError();
  }
});

TypeScript Support

The widget includes TypeScript definitions:

interface InfinityWidget extends HTMLElement {
  sendMessage(message: string): void;
  clearMessages(): void;
  getMessages(): Message[];
  connect(): void;
  disconnect(): void;
  isConnected(): boolean;
  setTheme(theme: 'light' | 'dark' | 'auto'): void;
  getTheme(): string;
  setLanguage(language: string): void;
  getLanguage(): string;
}

interface MessageEvent extends CustomEvent {
  detail: {
    message: string;
    timestamp: number;
    id?: string;
  };
}