Events

The Traise Widget emits events that allow you to respond to user actions, call status changes, message activity, and more.

Subscribing to Events

on(event, handler)

Adds an event listener for the specified event.

Parameters:

• event (string): Event name
• handler (function): Callback function

Returns: TraiseWidgetAPI (for chaining)

const { on } = window.TraiseWidget;

on('callStarted', (data) => {
  console.log('Call started:', data);
});

on('messageReceived', (data) => {
  console.log('New message from:', data.from);
});

on('error', (error) => {
  console.error('Widget error:', error);
});

off(event, handler)

Removes an event listener.

Parameters:

• event (string): Event name
• handler (function): The same handler function passed to on()

Returns: TraiseWidgetAPI (for chaining)

const { on, off } = window.TraiseWidget;

const errorHandler = (error) => {
  console.error('Error:', error);
};

// Subscribe
on('error', errorHandler);

// Later, unsubscribe
off('error', errorHandler);

Available Events

Widget Events

Event	Description	Data
widgetStatus	Widget status changed	{ status }
phoneStatus	Phone/voice status changed	{ status }
uiStateChanged	UI state changed (visible, screen, etc.)	{ state }
error	An error occurred	{ category, message, code?, details? }

Voice Events

Event	Description	Data
callStarted	Call initiated	{ phoneNumber, direction }
callConnected	Call connected	{ phoneNumber, direction }
callEnded	Call terminated	{ phoneNumber, duration }
callFailed	Call failed to connect	{ error }

SMS Events

Event	Description	Data
messageSent	Message sent successfully	{ phoneNumber, message }
messageReceived	New message received	{ from, message }
messageFailed	Message failed to send	{ error }
smsRoomJoined	Subscribed to SMS conversation	{ roomId }
smsRoomUpdate	SMS room data updated	{ room }

Client Events

Event	Description	Data
clientLoaded	Client information loaded	{ client }
clientInfoUpdated	Client information updated	{ client }
clientInfoRemoved	Client information cleared	-

WebSocket Events

Event	Description	Data
websocketConnected	WebSocket connected	-
websocketDisconnected	WebSocket disconnected	-
websocketReconnected	WebSocket reconnected after disconnect	-
websocketError	WebSocket connection error	{ error }

Error Event

The error event is emitted for all widget errors. The error object includes a category to help you handle different types of errors:

Error Codes

Errors include a code field for programmatic handling. See the Error Codes reference for the full list grouped by category.

on('error', (error) => {
  console.log(error.code);     // e.g., 'AUTH_001'
  console.log(error.category); // e.g., 'auth'
  console.log(error.message);  // Human-readable message
});

on('error', (error) => {
  switch (error.category) {
    case 'auth':
      // Authentication failed
      console.error('Auth error:', error.message);
      break;
    case 'voice':
      // Call-related error
      console.error('Voice error:', error.message);
      break;
    case 'sms':
      // Messaging error
      console.error('SMS error:', error.message);
      break;
    case 'network':
      // Network/connection error
      console.error('Network error:', error.message);
      break;
    case 'api':
      // API request error
      console.error('API error:', error.message);
      break;
  }
});

Error Object Structure

interface WidgetError {
  category: 'auth' | 'voice' | 'sms' | 'network' | 'api';
  message: string;
  code?: string;
  details?: any;
  timestamp: string;
}

Usage Examples

Tracking Call Activity

const { on } = window.TraiseWidget;

// Track call metrics
on('callStarted', (data) => {
  analytics.track('call_started', {
    phoneNumber: data.phoneNumber,
    direction: data.direction
  });
});

on('callEnded', (data) => {
  analytics.track('call_ended', {
    phoneNumber: data.phoneNumber,
    duration: data.duration
  });
});

on('callFailed', (error) => {
  analytics.track('call_failed', {
    error: error.message
  });
});

Handling New Messages

const { on } = window.TraiseWidget;

on('messageReceived', (data) => {
  // Show browser notification
  if (Notification.permission === 'granted') {
    new Notification('New Message', {
      body: `From: ${data.from}`,
      icon: '/notification-icon.png'
    });
  }

  // Play notification sound
  const audio = new Audio('/sounds/message.mp3');
  audio.play();
});

Best Practices

1. Always clean up listeners - Remove event listeners when components unmount to prevent memory leaks

2. Use named functions - When you need to remove listeners later, use named functions instead of inline arrows

3. Handle errors early - Set up error handlers immediately after initialization

4. Don't block event handlers - Keep event handlers fast; use async operations for heavy work

// Good - non-blocking
on('messageReceived', async (data) => {
  // Fire and forget
  saveToDatabase(data).catch(console.error);
});

// Avoid - blocking
on('messageReceived', async (data) => {
  await saveToDatabase(data); // Blocks other handlers
});

Next Steps

• API Reference - Complete API documentation
• Configuration - Widget configuration options