virtual-banker/docs/WIDGET_INTEGRATION.md

Widget Integration Guide

Quick Start

1. Include the Widget Script

Add the widget loader script to your HTML page:

<script src="https://cdn.example.com/virtual-banker/widget.js"
        data-tenant-id="your-tenant-id"
        data-user-id="user-123"
        data-auth-token="jwt-token"
        data-api-url="https://api.example.com"
        data-avatar-enabled="true"></script>
<div id="virtual-banker-widget"></div>

2. Configuration Options

Attribute	Required	Description
data-tenant-id	Yes	Tenant identifier
data-user-id	No	User identifier (for authenticated sessions)
data-auth-token	No	JWT token for authentication
data-api-url	No	API base URL (default: http://localhost:8081)
data-avatar-enabled	No	Enable/disable avatar (default: true)

Programmatic API

Methods

// Open widget
window.VirtualBankerWidgetAPI.open();

// Close widget
window.VirtualBankerWidgetAPI.close();

// Minimize widget
window.VirtualBankerWidgetAPI.minimize();

// Set context (page/route information)
window.VirtualBankerWidgetAPI.setContext({
  route: '/account',
  accountId: 'acc-123',
  productId: 'prod-456'
});

// Update authentication token
window.VirtualBankerWidgetAPI.setAuthToken('new-jwt-token');

PostMessage Events

Listen for widget events from the parent window:

window.addEventListener('message', (event) => {
  if (event.data.source === 'virtual-banker-widget') {
    switch (event.data.type) {
      case 'ready':
        console.log('Widget is ready');
        break;
      
      case 'session_started':
        console.log('Session ID:', event.data.payload.sessionId);
        break;
      
      case 'action_requested':
        console.log('Action:', event.data.payload.action);
        console.log('Params:', event.data.payload.params);
        // Handle action (e.g., open ticket, schedule appointment)
        break;
      
      case 'action_completed':
        console.log('Action completed:', event.data.payload);
        break;
      
      case 'handoff_to_human':
        console.log('Handoff reason:', event.data.payload.reason);
        // Show human agent interface
        break;
    }
  }
});

Sending Messages to Widget

Send commands to the widget from the parent window:

const widget = document.getElementById('virtual-banker-widget');
if (widget && widget.contentWindow) {
  widget.contentWindow.postMessage({
    type: 'open',
    source: 'virtual-banker-host'
  }, '*');
}

Available commands:

• open - Open the widget
• close - Close the widget
• minimize - Minimize the widget
• setContext - Update context
• setAuthToken - Update auth token

Styling

The widget can be styled via CSS:

#virtual-banker-widget {
  position: fixed;
  bottom: 20px;
  right: 20px;
  width: 400px;
  height: 600px;
  z-index: 9999;
  border-radius: 8px;
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
}

#virtual-banker-widget.minimized {
  height: 60px;
  width: 200px;
}

Theming

Theme can be configured per tenant via the backend API. The widget will automatically apply the theme from the session configuration.

Accessibility

The widget is built with accessibility in mind:

• Full keyboard navigation
• Screen reader support
• ARIA labels
• Captions always available
• Reduced motion support (respects OS preference)

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Mobile browsers (iOS Safari, Chrome Mobile)

Security

• Content Security Policy (CSP) compatible
• No direct secrets in browser
• Ephemeral session tokens only
• CORS configured for embedding