@techhalo/chat

v1.0.34

Published

21 days ago

Techhalo Chat Widget

0High
0Medium
0Low

TechHalo - AI-Powered Embeddable Chat Widget

TechHalo is an intelligent, embeddable chat widget platform that provides AI-powered customer support and specialized technical assistance. Built with modern web technologies, it offers seamless integration into any website while delivering advanced conversational AI capabilities and specialized tools like the AI Part Finder for industrial applications.

🚀 Features

Core Chat Functionality

Real-time AI Conversations - Streaming responses with WebSocket communication
Session Management - Persistent chat history and conversation continuity
Markdown Support - Rich text formatting with code highlighting
Voice Integration - ElevenLabs voice synthesis support
YouTube Embedding - Automatic video link detection and embedding
Rating System - User feedback and response rating
Responsive Design - Mobile-first, adaptive UI

Advanced Features

AI Part Finder - Specialized tool for finding industrial parts and machinery components
Eligibility Check System - Healthcare insurance eligibility verification with multiple input methods
Progressive Search - Context-aware search with intelligent filtering
Schematics Integration - Visual part identification and documentation
Knowledge Base Integration - Project-specific information retrieval
Modal System - Flexible, customizable modal components for various use cases
Data Security - Automatic masking of sensitive information (SSN, credit cards, emails, phone numbers)
Multi-language Support - Internationalization ready
Custom Theming - Flexible styling and branding options

Enterprise Features

Project-based Configuration - Multi-tenant architecture
Governance Rules - Compliance and content moderation
Contextual Notifications - Smart user alerts and acknowledgments
Analytics Integration - Conversation tracking and insights
Custom Positioning - Flexible widget placement options

📦 Installation

NPM Installation

npm install techhalo

CDN Integration

<!-- Include the widget script -->
<script src="https://cdn.jsdelivr.net/npm/techhalo@latest/dist/halo-chat.umd.js"></script>

<!-- Add the widget to your page -->
<halo-chat project_id="your-project-id" position="bottom-right"></halo-chat>

Manual Installation

# Clone the repository
git clone https://github.com/your-org/techhalo.git
cd techhalo/techhaloembed

# Install dependencies
npm install
# or
pnpm install
# or
yarn install

🔧 Quick Start

Basic Integration

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <!-- Your website content -->
    
    <!-- TechHalo Chat Widget -->
    <halo-chat 
        project_id="3a3a382678" 
        position="bottom-right">
    </halo-chat>
    
    <script src="https://cdn.jsdelivr.net/npm/techhalo@latest/dist/halo-chat.umd.js"></script>
</body>
</html>

React Integration

import { useEffect } from 'react';

function App() {
    useEffect(() => {
        // Load the TechHalo script
        const script = document.createElement('script');
        script.src = 'https://cdn.jsdelivr.net/npm/techhalo@latest/dist/halo-chat.umd.js';
        script.async = true;
        document.body.appendChild(script);

        return () => {
            document.body.removeChild(script);
        };
    }, []);

    return (
        <div>
            {/* Your React app */}
            <halo-chat 
                project_id="your-project-id" 
                position="bottom-right" 
            />
        </div>
    );
}

Vue.js Integration

<template>
    <div>
        <!-- Your Vue app -->
        <halo-chat 
            :project_id="projectId" 
            position="bottom-right"
        />
    </div>
</template>

<script>
export default {
    data() {
        return {
            projectId: 'your-project-id'
        };
    },
    mounted() {
        const script = document.createElement('script');
        script.src = 'https://cdn.jsdelivr.net/npm/techhalo@latest/dist/halo-chat.umd.js';
        script.async = true;
        document.body.appendChild(script);
    }
};
</script>

⚙️ Configuration

Widget Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | projectId | string | required | Unique identifier for your project | | position | string | bottom-right | Widget position: bottom-right, bottom-left, top-right, top-left | | partFinder | boolean | false | Enable AI Part Finder functionality | | eligibilityCheck | boolean | false | Enable Eligibility Check system for healthcare applications | | theme | string | default | Theme variant: default, halo, boatbot, or custom theme name | | getToken | function | optional | Function that returns the current auth token (synchronous or async) | | environment | string | dev | API environment: dev, qa, or prod (determines which API base URL to use) | | workspace_id | string | 39 | Workspace identifier | | enable_phase2 | boolean | false | Enable phase 2 features |

Authentication Configuration

For eligibility check features, provide a function that returns the current authentication token. The widget will call this function:

On each API request to get a fresh token
Automatically on 401 errors (up to 3 retry attempts)
This allows your application to handle token refresh seamlessly

<halo-chat 
    projectId="your-project-id" 
    position="bottom-right"
    getToken={() => yourAuthService.getToken()}
    environment="prod">
</halo-chat>

JavaScript Example:

const widget = document.querySelector('halo-chat');
widget.getToken = () => {
  // Return token synchronously
  return localStorage.getItem('auth_token');
};

Async Token Example:

widget.getToken = async () => {
  // Or return a promise for async token retrieval
  const response = await fetch('/api/auth/token');
  const data = await response.json();
  return data.token;
};

React Example:

<halo-chat 
  projectId="your-project-id"
  getToken={() => authService.getAccessToken()}
  environment="prod"
/>

Token Refresh Behavior

The widget calls getToken() before each API request
On 401 (Unauthorized), it automatically retries up to 3 times
Each retry calls getToken() again, allowing your app to provide a refreshed token
After 3 failed attempts, shows "Session expired" message

The environment parameter determines which API base URL will be used:

dev - Development environment (default)
qa - QA/staging environment
prod - Production environment

Configure the environment-specific URLs in your .env file:

VITE_EligibilityApiUrl_Dev=https://api-dev.example.com/api/
VITE_EligibilityApiUrl_QA=https://api-qa.example.com/api/
VITE_EligibilityApiUrl_Prod=https://api-prod.example.com/api/

Environment Configuration

The widget connects to the following endpoints by default:

export const environment = {
    production: true,
    baseUrl: "https://apistagingcanyon.pilgrim.team",
    socketUrl: "wss://aigateway.thehaloplatform.net/ws/core/chat",
    aiServerUrl: "https://aigateway.thehaloplatform.net",
    aiPartFinderUrl: "https://apipartfinder.pilgrim.team"
};

Custom Styling

The widget uses CSS custom properties for theming:

halo-chat {
    --halo-primary-color: #007acc;
    --halo-background-color: #ffffff;
    --halo-text-color: #333333;
    --halo-border-radius: 8px;
    --halo-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

🔨 Development

Prerequisites

Node.js 18+ and npm/pnpm/yarn
Modern browser with ES2020+ support

Development Setup

# Clone and install
git clone https://github.com/your-org/techhalo.git
cd techhalo/techhaloembed
pnpm install

# Start development server
pnpm dev

# The widget will be available at http://localhost:3000

Project Structure

techhaloembed/
├── src/
│   ├── chat-system/           # Core chat functionality
│   │   ├── chat-system.svelte # Main chat component with global styles
│   │   ├── chat-service.ts    # API communication
│   │   ├── chat-stream-service.ts # WebSocket handling
│   │   ├── project-service.ts # Project management
│   │   ├── conversation-service.ts # Conversation handling
│   │   ├── url-parser-service.ts # URL parsing utilities
│   │   └── rating.svelte      # Response rating component
│   ├── components/            # Reusable components
│   │   ├── AI_part_finder.svelte # Part finder tool
│   │   ├── EligibilityCheck.svelte # Healthcare eligibility system
│   │   ├── Modal.svelte       # Flexible modal component
│   │   ├── Loading.svelte     # Loading states
│   │   ├── Pills.svelte       # UI pill components
│   │   ├── ProgressiveSearch.svelte # Advanced search interface
│   │   ├── SystemDisplay.svelte # System information display
│   │   └── schematics.svelte  # Technical schematics viewer
│   ├── assets/               # Static assets
│   │   ├── images/           # Icons and graphics
│   │   └── json/             # Configuration files
│   ├── environment/          # Environment configuration
│   ├── store/               # State management
│   │   ├── step.ts          # Step-based workflow state
│   │   └── themeStore.ts    # Theme management
│   ├── themes/              # Theme configuration
│   │   └── themeStore.svelte # Theme switching component
│   ├── types/               # TypeScript definitions
│   │   └── halochat.d.ts    # Chat system type definitions
│   ├── utils/               # Utility functions
│   │   └── createConversationType.ts # Conversation utilities
│   └── plugins/             # Plugin integrations
│       └── halo-plugin-integration.ts # Plugin system
├── demo/                    # Demo implementation
├── dist/                    # Built files
└── test/                    # Test files
    ├── embed.html           # Basic embedding test
    └── plugin-integration-test.html # Plugin testing

Build Commands

# Development server
pnpm dev

# Build for production
pnpm build

# Build Svelte components only
pnpm build:svelte

# Type checking
pnpm check

# Preview production build
pnpm preview

Build Output

The build process generates:

dist/halo-chat.es.js - ES module for npm
dist/halo-chat.umd.js - UMD build for browsers
Source maps and TypeScript declarations

🤖 AI Part Finder

The AI Part Finder is a specialized feature for industrial and manufacturing applications:

Features

Model Selection - Choose from extensive equipment database
System Type Classification - Categorize parts by system type
Intelligent Search - AI-powered part identification
Schematics Integration - Visual part location and specifications
Progressive Filtering - Narrow down results step by step

Enabling Part Finder

<halo-chat 
    project_id="your-project-id" 
    position="bottom-right"
    partFinder="true">
</halo-chat>

Integration with External Systems

The Part Finder integrates with:

Equipment manufacturer databases
Parts catalogs and inventory systems
Schematic and documentation repositories
Pricing and availability APIs

🏥 Eligibility Check System

The Eligibility Check System is a specialized healthcare feature designed for insurance verification and patient eligibility management:

Features

Multiple Input Methods - Support for three verification approaches:
- Policy Number (9 digits) - Fastest verification method
- Patient Name + Date of Birth - Standard verification
- Patient Name + Last 4 SSN digits - Alternative verification
Smart Form Validation - Real-time input validation with visual feedback
Green Border Highlighting - Intelligent visual cues showing related fields
Requirement Pills - Dynamic status indicators for different verification methods
Results Management - Comprehensive table with sorting, filtering, and export capabilities
Data Persistence - Local storage for completed eligibility checks
CSV Export - Download eligibility results for record keeping
Confirmation Modals - Safety measures to prevent accidental data loss

Enabling Eligibility Check

<halo-chat 
    project_id="your-project-id" 
    position="bottom-right"
    eligibilityCheck="true">
</halo-chat>

Eligibility Check Workflow

Input Selection - Choose verification method based on available information
Data Entry - Fill required fields with smart validation
Real-time Feedback - Visual indicators guide the user through the process
Eligibility Verification - Submit for processing with loading states
Results Display - View detailed eligibility information
Data Management - Export, edit, or delete results as needed

Input Validation Rules

Policy Number: Exactly 9 digits, numeric only
Patient Name: Letters and spaces only, first and last name required
Date of Birth: Standard date format (YYYY-MM-DD)
SSN Last 4: Exactly 4 digits, numeric only

Security Features

Data Masking - Sensitive information is automatically protected
Local Storage Only - No sensitive data transmitted unnecessarily
Input Sanitization - All inputs are validated and sanitized
Session Isolation - Each session maintains separate data contexts

Integration with Chat System

The eligibility check system integrates seamlessly with the chat interface:

Natural Language Processing - Extract eligibility information from chat messages
Auto-population - Pre-fill forms from conversation context
Contextual Responses - AI provides guidance based on eligibility status
Workflow Integration - Smooth transitions between chat and eligibility tools

🪟 Modal System

TechHalo includes a comprehensive modal system for displaying content, forms, and interactive elements:

Modal Features

Flexible Positioning - Multiple positioning options (center, corners, custom)
Customizable Styling - Full control over appearance, colors, and dimensions
Animation Support - Smooth entrance and exit animations
Responsive Design - Mobile-friendly with adaptive layouts
Accessibility - ARIA compliance and keyboard navigation
Backdrop Control - Configurable backdrop behavior and styling
Close Button Options - Multiple close button positions and styles

Modal Usage

import Modal from './components/Modal.svelte';

// Basic modal implementation
<Modal 
    bind:isOpen={showModal}
    headerTitle="Eligibility Results"
    width="800px"
    height="600px"
>
    <div slot="header">
        <p>Additional header content</p>
    </div>
    
    <!-- Modal content -->
    <EligibilityCheck />
    
    <div slot="footer">
        <button on:click={closeModal}>Close</button>
        <button on:click={saveData}>Save</button>
    </div>
</Modal>

Modal Configuration Options

| Property | Type | Default | Description | |----------|------|---------|-------------| | isOpen | boolean | false | Controls modal visibility | | width | string | '600px' | Modal width | | height | string | 'auto' | Modal height | | maxWidth | string | '90vw' | Maximum width | | maxHeight | string | '90vh' | Maximum height | | position | string | 'center' | Modal position | | backgroundColor | string | '#ffffff' | Background color | | borderRadius | string | '12px' | Border radius | | boxShadow | string | '0 25px 50px -12px rgba(0, 0, 0, 0.25)' | Drop shadow | | backdropColor | string | 'rgba(0, 0, 0, 0.5)' | Backdrop color | | showCloseButton | boolean | true | Show close button | | closeButtonPosition | string | 'top-right' | Close button position | | animationDuration | string | '300ms' | Animation duration |

Global CSS Architecture

The modal system, along with other components, uses a global CSS architecture for better bundle compatibility:

CSS Organization

Global Styles - All component styles are centralized in chat-system.svelte
Unique Prefixes - Each component uses unique class prefixes to prevent conflicts:
- ChatModal_ - Modal system styles
- eligibilitycheck_ - Eligibility check component styles
Responsive Design - Mobile-first approach with comprehensive breakpoints
Theme Support - CSS custom properties for easy theming

Benefits of Global CSS

Bundle Compatibility - Styles are preserved during build process
Performance - Reduced CSS duplication and smaller bundle sizes
Maintainability - Centralized style management
Consistency - Unified design system across components

🔐 Security & Privacy

Data Protection

Sensitive Data Masking - Automatic detection and masking of:
- Credit card numbers
- Social Security Numbers
- Email addresses
- Phone numbers
Secure Communication - All data transmitted via HTTPS/WSS
Session Isolation - Each session is encrypted and isolated
GDPR Compliance - Built with privacy regulations in mind

Content Security

Input Sanitization - All user inputs are sanitized
XSS Prevention - Protection against cross-site scripting
CSRF Protection - Request validation and token verification

📡 API Integration

WebSocket Events

The widget communicates via WebSocket for real-time functionality:

// Message structure
interface Message {
    id: string;
    content: string;
    role: 'user' | 'assistant';
    timestamp: Date;
    isLoading?: boolean;
    streamStarted?: boolean;
    streamEnded?: boolean;
}

// Streaming message payload
interface SendMessagePayload {
    user_message: string;
    project_id: string;
    session_id?: string | number;
}

REST API Endpoints

GET /api/services/app/Projects/GetProjectForView - Project configuration
GET /api/services/app/Projects/GetAllRulesFromParents - Governance rules
GET /api/services/app/KnowledgeItems/GetKnowledgeItemsByProjectId - Knowledge base
GET /api/services/app/Acknowledgement/GetContextualNotifications - Notifications

🎨 Customization

Theme Customization

Create custom themes by extending the base theme:

.my-custom-theme {
    --halo-primary-color: #ff6b35;
    --halo-secondary-color: #f7931e;
    --halo-background-color: #fefefe;
    --halo-text-color: #2c3e50;
    --halo-border-color: #ecf0f1;
    --halo-border-radius: 12px;
    --halo-font-family: 'Inter', sans-serif;
}

Component Overrides

Customize specific components:

halo-chat::part(chat-container) {
    max-height: 600px;
    width: 400px;
}

halo-chat::part(message-bubble) {
    border-radius: 18px;
    padding: 12px 16px;
}

halo-chat::part(input-field) {
    border: 2px solid var(--halo-primary-color);
}

🧪 Testing

Unit Tests

# Run unit tests
npm run test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Integration Testing

# Run integration tests
npm run test:integration

# Run end-to-end tests
npm run test:e2e

Manual Testing

Use the demo files for manual testing:

demo/index.html - Basic integration demo
test/embed.html - Advanced feature testing

🚀 Deployment

CDN Deployment

# Build for production
pnpm build

# Deploy to CDN (example with AWS S3)
aws s3 cp dist/ s3://your-cdn-bucket/techhalo/ --recursive

NPM Publishing

# Prepare for publishing
pnpm prepack

# Publish to NPM
npm publish

Self-hosted Deployment

# Build the project
pnpm build

# Serve the dist files from your web server
# Make sure to serve with proper CORS headers

📊 Analytics & Monitoring

Built-in Analytics

The widget automatically tracks:

Conversation initiation and duration
User engagement metrics
Response satisfaction ratings
Feature usage statistics
Error rates and performance metrics

Custom Event Tracking

// Listen for custom events
document.addEventListener('halo-chat-event', (event) => {
    console.log('Chat event:', event.detail);
    // Send to your analytics service
});

// Eligibility check events
document.addEventListener('eligibility-check-completed', (event) => {
    console.log('Eligibility check result:', event.detail);
});

// Modal events
document.addEventListener('modal-opened', (event) => {
    console.log('Modal opened:', event.detail.modalType);
});

Advanced Integration Examples

Healthcare Application Integration

<!-- Healthcare provider website -->
<halo-chat 
    project_id="healthcare-provider-123"
    position="bottom-right"
    eligibilityCheck="true"
    theme="medical">
</halo-chat>

<script>
// Listen for eligibility results
document.addEventListener('eligibility-verified', (event) => {
    const { patientInfo, coverage } = event.detail;
    // Update patient record system
    updatePatientEligibility(patientInfo, coverage);
});
</script>

Industrial/Manufacturing Integration

<!-- Manufacturing company website -->
<halo-chat 
    project_id="manufacturing-corp-456"
    position="bottom-left"
    partFinder="true"
    theme="industrial">
</halo-chat>

<script>
// Listen for part finder results
document.addEventListener('part-found', (event) => {
    const { partNumber, specifications } = event.detail;
    // Update inventory or ordering system
    addToCart(partNumber, specifications);
});
</script>

Multi-Modal Application

<!-- Application using both features -->
<halo-chat 
    project_id="multi-service-789"
    position="bottom-right"
    partFinder="true"
    eligibilityCheck="true"
    theme="corporate">
</halo-chat>

🤝 Contributing

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Ensure all tests pass: pnpm test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Code Standards

Use TypeScript for all new code
Follow the existing code style (Prettier configuration)
Add unit tests for new functionality
Update documentation as needed
Ensure accessibility compliance

Issues and Bugs

Please report issues using the GitHub issue tracker:

Provide detailed reproduction steps
Include browser and version information
Add relevant error messages and logs

📝 Changelog

Version 0.0.0 (Current)

New Features

Eligibility Check System - Complete healthcare insurance verification system
- Multiple input methods (Policy, Name+DOB, Name+SSN)
- Real-time validation with visual feedback
- Smart form highlighting and requirement pills
- Results management with CSV export
- Data persistence and confirmation modals
Enhanced Modal System - Flexible, reusable modal component
- Customizable positioning and styling
- Animation support and responsive design
- ARIA accessibility compliance
- Multiple close button positions
Global CSS Architecture - Improved styling system
- Centralized styles for better bundle compatibility
- Unique class prefixes to prevent conflicts
- Performance optimizations
Advanced Chat Integration - Enhanced AI capabilities
- Natural language processing for form pre-population
- Context-aware responses based on user interactions
- Improved conversation flow management

Core Features

Core chat functionality with streaming responses
AI Part Finder integration for industrial applications
WebSocket real-time communication
Embeddable widget architecture
TypeScript support with comprehensive type definitions
Modern build tooling with Vite and Rollup
Responsive design with mobile optimization
Theme system with multiple built-in themes

Technical Improvements

Component-based architecture with Svelte 5
State management with reactive stores
Plugin system for extensibility
Comprehensive error handling and validation
Security enhancements with data masking
Performance optimizations and bundle size reduction

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Svelte 5 and Vite
UI components styled with TailwindCSS
AI integration powered by LangChain
Voice synthesis by ElevenLabs
Markdown parsing by Marked
Code highlighting by Highlight.js

📞 Support

For technical support and questions:

Documentation: [Link to docs]
Issues: GitHub Issues
Email: [email protected]
Discord: Community Server

TechHalo - Empowering intelligent conversations through AI-powered chat widgets.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

TechHalo - AI-Powered Embeddable Chat Widget

🚀 Features

Core Chat Functionality

Advanced Features

Enterprise Features

📦 Installation

NPM Installation

CDN Integration

Manual Installation

🔧 Quick Start

Basic Integration

React Integration

Vue.js Integration

⚙️ Configuration

Widget Attributes

Authentication Configuration

Token Refresh Behavior

Environment Configuration

Custom Styling

🔨 Development

Prerequisites

Development Setup

Project Structure

Build Commands

Build Output

🤖 AI Part Finder

Features

Enabling Part Finder

Integration with External Systems

🏥 Eligibility Check System

Features

Enabling Eligibility Check

Eligibility Check Workflow

Input Validation Rules

Security Features

Integration with Chat System

🪟 Modal System

Modal Features

Modal Usage

Modal Configuration Options

Global CSS Architecture

CSS Organization

Benefits of Global CSS

🔐 Security & Privacy

Data Protection

Content Security

📡 API Integration

WebSocket Events

REST API Endpoints

🎨 Customization

Theme Customization

Component Overrides

🧪 Testing

Unit Tests

Integration Testing

Manual Testing

🚀 Deployment

CDN Deployment

NPM Publishing

Self-hosted Deployment

📊 Analytics & Monitoring

Built-in Analytics

Custom Event Tracking

Advanced Integration Examples

Healthcare Application Integration

Industrial/Manufacturing Integration

Multi-Modal Application

🤝 Contributing

Development Workflow

Code Standards

Issues and Bugs

📝 Changelog

Version 0.0.0 (Current)

New Features