@techhalo/chat

v2.0.23

Published

4 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 with specialized healthcare insurance eligibility verification capabilities. Built with Svelte 5 and modern web technologies, it offers seamless integration into any website while delivering advanced conversational AI capabilities and comprehensive benefits verification tools.

🚀 Features

Core Chat Functionality

Real-time AI Conversations - Streaming responses with WebSocket communication via LangChain
RAG Integration - Retrieval-Augmented Generation with intent detection for transactional vs. informational queries
Session Management - Persistent chat history and conversation continuity
Markdown Support - Rich text formatting with code highlighting (Highlight.js)
YouTube Embedding - Automatic video link detection and embedding
Rating System - User feedback and response rating with dislike form
Source Attribution - Citations and knowledge base references
Follow-up Suggestions - AI-generated contextual follow-up questions
Live Agent Handoff - Seamless transition to human support

Eligibility Verification System

A comprehensive healthcare insurance eligibility verification module:

Multiple Verification Methods
- Patient Name + Date of Birth
- Policy Number lookup
Treatment Reason Selection
- Dental Services
- Routine Wellness/Screening
- Accidental Injury
- Maternity
- Sickness
Provider Management - Store and manage provider information (name, facility, phone)
Real-time Validation - Input validation with visual feedback
Results Management - Sortable table with filtering and export capabilities
Decision Tree Workflow - Guided navigation through verification steps

Eligibility Details & Benefits Display

Comprehensive coverage information beyond basic eligibility:

Coverage Verification - Policy lookup via APL OSC Coverage API
Multi-Policy Handling - Support for patients with multiple policies
Treatment-Specific Filtering - Filter policies by treatment reason
Policy Tabs - Navigate between multiple policies easily

Dental Benefits

Dental Procedure Verification - Verify ADA procedure codes against policy coverage
Multi-Procedure Entry - Verify up to 5 procedure codes at once with tag chip UI
Dental Benefit Summary - Deductibles, annual/lifetime maximums, YTD usage, remaining benefits
Usage History Tracking - Track verified procedures with coverage status
Coverage Details - Benefit percentage, dental category, frequency limitations, waiting periods

Medical/Health Benefits

Health Benefit Maximums - Individual and family benefit maximums by category
Health Deductible Information - Individual and family deductibles with remaining amounts
Category-Specific Display - Wellness, Sickness, Accident, Maternity categories
Accordion UI - Expandable sections for detailed benefit information

Export Functionality

PDF Export - Professional PDF reports with APL branding and Gotham fonts
CSV Export - Data export for spreadsheets
Excel Export - Full Excel workbook export with ExcelJS

Analytics Integration

Pendo Analytics - Full Pendo SDK integration
- Event tracking with automatic retry
- Guides/Tours support
- Visitor and Account identification
- Environment-specific API keys (dev, qa, prod)
- Host or standalone initialization modes

Enterprise Features

Project-based Configuration - Multi-tenant architecture
Bearer Token Authentication - Secure API access with automatic token refresh
Environment Support - Development, QA, and Production API environments
Mock API Framework - Development and testing without backend dependencies

📦 Installation

NPM Installation

npm install @techhalo/chat

CDN Integration

<!-- Include the widget script -->
<script src="https://cdn.jsdelivr.net/npm/@techhalo/chat@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

🔧 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/chat@latest/dist/halo-chat.umd.js"></script>
</body>
</html>

React Integration

import { useEffect, useRef } from 'react';

function App() {
    const widgetRef = useRef(null);

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

        // Configure token provider after script loads
        script.onload = () => {
            if (widgetRef.current) {
                widgetRef.current.getToken = () => authService.getAccessToken();
            }
        };

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

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

Vue.js Integration

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

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

⚙️ Configuration

Widget Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | project_id | string | required | Unique identifier for your project (encrypted) | | workspace_id | string | "39" | Workspace identifier (encrypted) | | position | string | "bottom-right" | Widget position: bottom-right, bottom-left, top-right, top-left | | getToken | function | optional | Function that returns the current auth token (sync or async) | | environment | string | "dev" | API environment: dev, qa, or prod | | pendoVisitor | object | optional | Pendo visitor data for analytics | | pendoAccount | object | optional | Pendo account data for analytics | | pendoMode | string | "auto" | Pendo initialization mode: auto, host, standalone |

Authentication Configuration

For eligibility and coverage features, provide a function that returns the current authentication token:

<halo-chat 
    project_id="your-project-id" 
    position="bottom-right"
    environment="prod">
</halo-chat>

<script>
const widget = document.querySelector('halo-chat');
widget.getToken = async () => {
    // Return token - can be sync or async
    const response = await fetch('/api/auth/token');
    const data = await response.json();
    return data.token;
};
</script>

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

Pendo Analytics Configuration

Configure Pendo for analytics tracking and in-app guides:

const widget = document.querySelector('halo-chat');

// Set visitor and account information
widget.pendoVisitor = {
    id: 'user-123',
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe'
};

widget.pendoAccount = {
    id: 'account-456',
    accountName: 'Acme Corp'
};

// Pendo modes:
// - 'auto': Wait for host to initialize, fallback to standalone (default)
// - 'host': Assume host app initializes Pendo, only update identity
// - 'standalone': Always initialize Pendo independently
widget.pendoMode = 'auto';

Environment Configuration

Configure environment-specific URLs in your .env file:

# API Base URLs
VITE_BaseUrl=https://api.example.com
VITE_SocketUrl=wss://aigateway.example.com/ws/core/chat
VITE_AiServerUrl=https://aigateway.example.com

# RAG API
VITE_RagApiUrl=https://rag-api.example.com

# Eligibility API URLs (environment-specific)
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/

# Pendo Configuration
# Pendo SDK and analytics are always enabled when API keys are configured.
# This setting controls only the in-app guides (Help buttons, Show Me buttons).
# When disabled, guide-related UI elements will be hidden but analytics still work.
VITE_PENDO_GUIDES_ENABLED=true

# Pendo API Keys (environment-specific)
VITE_PENDO_API_KEY_DEV=your-dev-api-key
VITE_PENDO_API_KEY_QA=your-qa-api-key
VITE_PENDO_API_KEY_PROD=your-prod-api-key

🔨 Development

Prerequisites

Node.js 18+ and npm/pnpm
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

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

# Run tests
pnpm test
pnpm test:ui        # With UI
pnpm test:coverage  # With coverage report

Build Output

dist/halo-chat.es.js - ES module for npm
dist/halo-chat.umd.js - UMD build for browsers
dist/halochat.d.ts - TypeScript declarations

🏗️ Architecture

TechHalo follows a modern, layered architecture pattern with clear separation of concerns:

src/lib/
├── types/          # TypeScript type definitions
├── constants/      # Static configuration, endpoints, enums
├── utils/          # Pure utility functions (date, formatting, scroll)
├── services/       # API calls and external integrations
│   ├── chat/       # Chat and streaming services
│   ├── eligibility/    # Eligibility verification
│   ├── coverage/       # Coverage check service
│   ├── dental/         # Dental procedure verification
│   ├── dental-benefit-summary/  # Dental benefits API
│   ├── health-benefit-maximums/ # Health benefits API
│   ├── health-deductible-info/  # Health deductibles API
│   ├── rag/            # RAG knowledge base queries
│   ├── pendo/          # Analytics integration
│   └── ...
├── state/          # Pure state transformation functions
├── stores/         # Svelte stores (reactive state)
├── controllers/    # Orchestration and business logic
├── composables/    # Reusable composition functions
├── actions/        # Svelte actions (DOM behaviors)
│   ├── clickOutside.ts
│   ├── focusTrap.ts
│   ├── autoResize.ts
│   └── tooltip.ts
└── components/     # Svelte components
    ├── chat/       # Chat UI components
    ├── eligibility/    # Eligibility verification components
    └── ui/         # Reusable UI primitives

Key Architectural Patterns

Service Factory Pattern - Services support mock/real switching via factory functions
Store-based State - Svelte stores for reactive state management
Controller Layer - Business logic separated from components
Composables - Reusable reactive logic (validation, effects)
Actions - Reusable DOM behaviors (clickOutside, focusTrap)

Import Patterns

Use the $lib alias for clean, maintainable imports:

import { chatStore } from '$lib/stores';
import { eligibilityService } from '$lib/services/eligibility';
import { formatDate } from '$lib/utils';
import type { EligibilityEntry } from '$lib/types';

🧪 Mock API Framework

TechHalo includes a comprehensive mock API framework for development and testing:

Quick Start with Mocks

Enable mocks in your .env file:

VITE_USE_MOCKS=on                    # Enable mock mode
VITE_MOCK_DELAY_MS=300               # Simulate network delay
VITE_MOCK_LOG_REQUESTS=true          # Log mock activity

# Per-service toggles
VITE_MOCK_ELIGIBILITY=on             # Mock eligibility API

Use services normally - they automatically switch between mock and real:

import { eligibilityService } from '$lib/services/eligibility';

// Automatically uses mock when VITE_USE_MOCKS=on
const result = await eligibilityService.checkEligibility(request);

View API documentation with Swagger:

npm run mocks:swagger
# Open http://localhost:3333/docs

Mock Features

Rule-Based Scenarios - Define complex trigger rules for different responses
JSON Schema Validation - Ensure mock responses match real API contracts
Network Delay Simulation - Realistic timing with configurable delays
Swagger Documentation - Auto-generated API docs from OpenAPI specs
Environment Control - Granular control per service or globally

For detailed documentation, see src/mocks/README.md.

🧩 UI Components

Modal System

A highly customizable modal component with extensive options:

import Modal from '$lib/components/ui/Modal.svelte';

// Features:
// - Backdrop click to close (configurable)
// - Escape key to close (configurable)
// - Close button with positioning options
// - "Show Me" guide button integration
// - Download button option
// - Flexible sizing and positioning
// - Custom styling (colors, borders, shadows, blur)
// - Header, body, and footer slots
// - Responsive design

Other UI Components

AppTable - Sortable, filterable data table
Toast - Notification system
Accordion / AccordionList - Expandable content sections
MenuDropdown - Action menus
MultiSelectDropdown - Multi-selection with chips
ConfirmationModal - Confirmation dialogs
ActionButton - Styled action buttons
DatePicker - Date selection (via @svelte-plugins/datepicker)

📡 API Integration

Services Overview

| Service | Description | |---------|-------------| | ChatService | WebSocket-based chat communication | | ChatStreamService | Streaming message handling | | RagService | RAG queries with intent detection | | EligibilityService | Patient eligibility verification | | CoverageService | Policy and benefits lookup | | DentalService | Dental procedure verification | | DentalBenefitSummaryService | Dental deductibles and maximums | | HealthBenefitMaximumsService | Medical benefit maximums | | HealthDeductibleInfoService | Medical deductible information | | PendoService | Analytics tracking and guides |

WebSocket Events

// 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;
}

RAG Service

The RAG service supports two modes:

/query - Direct knowledge base queries
/process - Intent-aware processing with transactional routing

import { RagService } from '$lib/services/rag';

const ragService = new RagService();

// Intent detection
const response = await ragService.process("check my eligibility");
if (response.query_type === 'transactional') {
    // Handle based on detected_intent: "Eligibility", "Claim Status", "File Claim"
} else {
    // Display informational response
    const chatPayload = ragService.transformProcessResponseToChatPayload(response);
}

🎨 Customization

Theme Customization

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

Component Overrides

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

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

🧪 Testing

# Run unit tests
pnpm test

# Run tests with UI
pnpm test:ui

# Run tests with coverage
pnpm test:coverage

# Run mock-specific tests
pnpm test:mocks

Manual Testing

demo/index.html - Basic integration demo
test/embed.html - Advanced feature testing
test/plugin-integration-test.html - Plugin 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

📊 Analytics Events

Built-in Pendo Events

The widget tracks key user interactions:

Widget open/close
Chat message sent/received
Eligibility check initiated/completed
Coverage details viewed
Export actions (PDF, CSV, Excel)

Custom Event Tracking

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

document.addEventListener('coverage-details-viewed', (event) => {
    console.log('Coverage viewed:', event.detail);
});

📝 Changelog

Version 2.0.3 (Current)

Core Features

AI-powered chat with LangChain streaming
RAG integration with intent detection
WebSocket real-time communication
Custom web element architecture (halo-chat)
Svelte 5 with runes for reactivity

Eligibility System

Complete eligibility verification workflow
Treatment reason selection (Dental, Wellness, Accident, Sickness, Maternity)
Provider information management
Real-time API integration with token authentication

Benefits & Coverage

Comprehensive coverage display with multi-policy support
Dental procedure verification with ADA codes
Dental benefit summary (deductibles, maximums, usage tracking)
Health benefit maximums and deductible APIs
Medical/Wellness/Accident/Maternity coverage display

Export Capabilities

PDF export with professional formatting (jsPDF, Gotham fonts)
CSV export for data analysis
Excel export with formatted workbooks (ExcelJS)

Analytics

Pendo SDK integration
Event tracking with retry logic
Guide/Tour support
Environment-specific configuration

Developer Experience

Mock API framework for development
Swagger documentation
Comprehensive TypeScript types
Layered architecture with clear separation

🤝 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
Add unit tests for new functionality
Update documentation as needed

📄 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
Markdown parsing by Marked
Code highlighting by Highlight.js
PDF generation by jsPDF
Excel export by ExcelJS
Date picker by @svelte-plugins/datepicker
Reactive streams by RxJS

📞 Support

For technical support and questions:

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

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