Floating Copilot Widget

A lightweight, highly configurable floating chat widget plugin for React websites with GitHub Copilot AI integration for intelligent message processing and API calling.

Features

✨ Easy Integration - Simply import and use the component 🎨 Fully Customizable - Configure colors, position, dimensions, and more 🖱️ Draggable & Resizable - Users can move and resize the widget 📱 Responsive - Adapts to mobile screens automatically ♿ Accessible - Keyboard shortcuts and semantic HTML 🎯 Feature Rich - Minimize, maximize, close buttons with callbacks 💬 Chat Interface - Built-in message display with auto-scroll ⚡ Performance - Lightweight with zero external dependencies 🤖 AI-Powered - GitHub Copilot integration for intent analysis 🔌 API Integrations - Easy framework to connect your own APIs 🎪 Smart Routing - Automatically call APIs based on user intent 📊 Custom Formatting - Format API responses beautifully

What's New in v1.5.0 🎉

• ✅ GitHub Copilot Integration - AI-powered intent analysis
• ✅ API Integration Framework - Simple interface to connect your APIs
• ✅ Pre-built Integrations - 7 example API integrations included
• ✅ Intent Analysis - Automatic parameter extraction from user messages
• ✅ Auto API Calling - Routes to correct API based on detected intent
• ✅ Interactive Parameter Collection - Asks for missing fields one by one
• ✅ Automatic API Execution - Triggers API call when all parameters are collected
• ✅ Beautiful UI - Fixed button visibility and improved text contrast (v1.4.4)
• ✅ Professional Bot Avatar - Custom SVG bot icon with gradient

Installation

npm install floating-copilot-widget
# or
yarn add floating-copilot-widget

Quick Start

Basic Usage

import React from 'react';
import FloatingCopilot from 'floating-copilot-widget';
import 'floating-copilot-widget/dist/FloatingCopilot.css';

function App() {
  return (
    <FloatingCopilot
      config={{
        title: 'Chat Assistant',
        position: 'bottom-right'
      }}
    />
  );
}

With Copilot Integration

import FloatingCopilot, { 
  createUserAPIIntegration 
} from 'floating-copilot-widget';

function App() {
  const apis = [
    createUserAPIIntegration('https://api.example.com')
  ];

  return (
    <FloatingCopilot
      config={{
        title: 'AI Assistant',
        copilot: {
          config: {
            githubToken: process.env.REACT_APP_GITHUB_TOKEN
          },
          apiIntegrations: apis,
          enabled: true
        }
      }}
    />
  );
}

With Interactive Parameter Collection

User flow:

User: "Create a customer"
Bot: "What is the customer's name?"
User: "John Doe"
Bot: "What is the email?"
User: "[email protected]"
Bot: "What is the phone?"
User: "123-456-7890"
Bot: ✓ "Customer created! ID: 12345"

Implementation:

import FloatingCopilot, { 
  createCustomAPIIntegration 
} from 'floating-copilot-widget';

function App() {
  const createCustomerAPI = createCustomAPIIntegration({
    id: 'create_customer',
    name: 'Create Customer',
    endpoint: 'https://api.example.com/customers',
    method: 'POST',
    intents: ['create_customer', 'add_customer', 'new_customer'],
    
    // Define required parameters - system will ask for these one by one
    requiredParameters: [
      {
        name: 'name',
        description: 'Full name of the customer',
        type: 'text',
        required: true,
        example: 'John Doe'
      },
      {
        name: 'email',
        description: 'Email address',
        type: 'email',
        required: true,
        example: '[email protected]'
      },
      {
        name: 'phone',
        description: 'Phone number',
        type: 'phone',
        required: true,
        example: '(555) 123-4567'
      }
    ],

    // Transform parameters into API request
    buildRequest: (params) => ({
      name: params.name,
      email: params.email,
      phone: params.phone
    }),

    // Format API response for display
    formatResponse: (data) => {
      return `✓ **Customer Created!**\n\n**ID:** ${data.id}\n**Name:** ${data.name}`;
    }
  });

  return (
    <FloatingCopilot
      config={{
        title: 'Smart Assistant',
        copilot: {
          config: {
            githubToken: process.env.REACT_APP_GITHUB_TOKEN
          },
          apiIntegrations: [createCustomerAPI],
          enabled: true
        }
      }}
    />
  );
}

Advanced Usage Guide

Interactive Parameter Collection - Complete Example

This is the most powerful feature. Define what parameters your API needs, and the system automatically asks for them one by one.

User Interaction Flow:

User:  "Create a customer"
Bot:   "What is the customer's name?"
User:  "John Doe"
Bot:   "What is the email?"
User:  "[email protected]"
Bot:   "What is the phone?"
User:  "555-123-4567"
Bot:   ✓ "Customer created! ID: 12345"

Implementation:

Step 1 - Define your API with required parameters:

import { createCustomAPIIntegration } from 'floating-copilot-widget';

const createCustomerAPI = createCustomAPIIntegration({
  id: 'create_customer',
  name: 'Create Customer',
  endpoint: 'https://api.example.com/customers',
  method: 'POST',
  intents: ['create_customer', 'add_customer', 'new_customer'],
  
  // Define required parameters - system asks for each missing one
  requiredParameters: [
    {
      name: 'name',
      description: 'Full name of the customer',
      type: 'text',
      required: true,
      example: 'John Doe'
    },
    {
      name: 'email',
      description: 'Email address',
      type: 'email',
      required: true,
      example: '[email protected]'
    },
    {
      name: 'phone',
      description: 'Phone number',
      type: 'phone',
      required: true,
      example: '(555) 123-4567'
    },
    {
      name: 'address',
      description: 'Street address',
      type: 'text',
      required: false,  // Optional parameters
      example: '123 Main St'
    }
  ],
  
  // Transform collected parameters into API request
  buildRequest: (params) => ({
    name: params.name,
    email: params.email,
    phone: params.phone,
    address: params.address || ''
  }),
  
  // Format API response for beautiful display
  formatResponse: (data) => {
    return `✓ **Customer Created Successfully!**\n\n` +
      `**ID:** ${data.id}\n` +
      `**Name:** ${data.name}\n` +
      `**Email:** ${data.email}`;
  },
  
  // Optional: Control when API should be called
  shouldCall: (intent, params) => {
    return !!params.name && !!params.email && !!params.phone;
  }
});

Step 2 - Use in FloatingCopilot:

<FloatingCopilot
  config={{
    title: 'Smart Assistant',
    copilot: {
      config: {
        githubToken: process.env.REACT_APP_GITHUB_TOKEN
      },
      apiIntegrations: [createCustomerAPI],
      enabled: true
    }
  }}
/>

That's it! The system will:

1. Detect user intent (create_customer)
2. Ask for missing parameters one by one
3. Validate each parameter (email format, phone format, etc.)
4. When all required parameters are collected, automatically call your API
5. Display the formatted response

Custom API Integration

Create completely custom APIs:

import type { APIIntegration } from 'floating-copilot-widget';

const customAPI: APIIntegration = {
  id: 'my_api',
  name: 'My Custom API',
  endpoint: 'https://api.example.com/action',
  method: 'POST',
  intents: ['my_intent', 'alternative_intent'],
  
  requiredParameters: [
    {
      name: 'userId',
      description: 'The user ID',
      type: 'text',
      required: true,
      example: 'user_123'
    }
  ],
  
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  
  buildRequest: (params, context) => ({
    user_id: params.userId,
    context_data: context?.userData
  }),
  
  formatResponse: (data) => {
    return `Result: ${JSON.stringify(data, null, 2)}`;
  },
  
  shouldCall: (intent, params) => {
    return !!params.userId;
  }
};

Parameter Types and Validation

Supported parameter types with automatic validation:

requiredParameters: [
  {
    name: 'userEmail',
    type: 'email',      // ✓ Validates email format
    description: 'User email address',
    example: '[email protected]'
  },
  {
    name: 'phoneNumber',
    type: 'phone',      // ✓ Validates phone format
    description: 'User phone',
    example: '(555) 123-4567'
  },
  {
    name: 'quantity',
    type: 'number',     // ✓ Validates numeric input
    description: 'Order quantity',
    example: '5'
  },
  {
    name: 'startDate',
    type: 'date',       // ✓ Validates date format
    description: 'Start date',
    example: '2026-02-15'
  },
  {
    name: 'notes',
    type: 'text',       // ✓ Plain text (any value)
    description: 'Additional notes',
    example: 'Rush delivery'
  }
]

Pre-built Integrations

Use 7 pre-built templates:

import {
  createUserAPIIntegration,
  createSearchAPIIntegration,
  createAnalysisAPIIntegration,
  createActionAPIIntegration,
  createDatabaseAPIIntegration,
  createWeatherAPIIntegration,
  createCustomAPIIntegration
} from 'floating-copilot-widget';

const apis = [
  createUserAPIIntegration('https://api.example.com'),
  createSearchAPIIntegration('https://api.example.com'),
  // ... more
];

Direct Copilot Functions

For advanced use cases, call Copilot functions directly:

import {
  analyzeUserIntent,
  callAPI,
  generateParameterPromptOrCallAPI,
  areAllParametersCollected,
  validateParameter,
  getNextMissingParameter
} from 'floating-copilot-widget';

// Analyze user intent
const intent = await analyzeUserIntent(
  { userMessage: 'Create a customer' },
  config,
  apis
);

// Check if all parameters are collected
const complete = areAllParametersCollected(api, {
  name: 'John',
  email: '[email protected]'
});

// Validate individual parameter
const validation = validateParameter('email', userInput, {
  type: 'email'
});

// Get next parameter to ask for
const nextParam = getNextMissingParameter(api, {
  name: 'John'
});

// Get prompt or trigger API
const result = await generateParameterPromptOrCallAPI(
  api,
  { name: 'John', email: '[email protected]', phone: '555-1234' },
  'create_customer'
);

if (result.apiResponse) {
  console.log('API called:', result.apiResponse.data);
} else {
  console.log('Ask user:', result.prompt);
}

GitHub Token Configuration

The widget automatically looks for your GitHub token in these locations (in order):

1. Explicit config: config.copilot.config.githubToken = 'ghp_...'
2. Environment variables:
   • GITHUB_TOKEN (Node.js)
   • VITE_GITHUB_TOKEN (Vite)
   • REACT_APP_GITHUB_TOKEN (Create React App)
3. Global variable: window.__GITHUB_TOKEN__

Recommended approach - Use environment variables:

# .env.local
REACT_APP_GITHUB_TOKEN=ghp_your_token_here

Then no need to pass it in config:

<FloatingCopilot
  config={{
    copilot: {
      config: {
        // Token loaded from environment automatically!
        model: 'gpt-4o'
      },
      // ... rest of config
    }
  }}
/>

To get a token:

1. Visit https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Select scopes:
   • copilot - for Copilot API access
   • read:user - for user data
4. Copy the token and save securely
5. Add to .env.local file

Configuration

Pass a config object to customize the widget:

<FloatingCopilot
  config={{
    // Positioning
    position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    
    // Dimensions
    width: 350,
    height: 500,
    
    // Features
    draggable: true,
    resizable: true,
    
    // Appearance
    title: 'Chat Assistant',
    placeholder: 'Type your message...',
    theme: {
      primaryColor: '#6366f1',
      backgroundColor: '#ffffff',
      textColor: '#1f2937',
      borderColor: '#e5e7eb',
    },
    
    // State
    minimized: false,
    maximized: false,
    
    // Controls
    showHeader: true,
    showMinimizeBtn: true,
    showMaximizeBtn: true,
    showCloseBtn: true,
    
    // Layering
    zIndex: 9999,
    
    // Copilot AI Configuration
    copilot: {
      config: {
        // Token auto-loaded from environment
        model: 'gpt-4o',           // GPT model to use
        maxTokens: 2000,           // Max response length
        temperature: 0.7           // Creativity (0-1)
      },
      apiIntegrations: [],         // Your custom APIs
      enabled: true,               // Enable/disable AI
      showIntentAnalysis: false    // Show detected intent
    },
    
    // Callbacks
    onMessage: (message) => console.log(message),
    onClose: () => {},
    onMinimize: () => {},
    onMaximize: () => {},
  }}
/>

Configuration

Position

• bottom-right (default)
• bottom-left
• top-right
• top-left

Theme Colors

Customize the appearance with your brand colors:

theme: {
  primaryColor: '#6366f1',      // Button, user message background
  backgroundColor: '#ffffff',   // Widget background
  textColor: '#1f2937',         // Text color
  borderColor: '#e5e7eb',       // Border color
}

Callbacks

// Called when user sends a message
onMessage: (message: string) => void

// Called when close button is clicked
onClose: () => void

// Called when minimize button is clicked
onMinimize: () => void

// Called when maximize button is clicked
onMaximize: () => void

Advanced Usage

Custom Message Handler

<FloatingCopilot
  config={{
    onMessage: async (message) => {
      // Send to your API
      const response = await fetch('/api/chat', {
        method: 'POST',
        body: JSON.stringify({ message }),
      });
      // Handle response...
    },
  }}
/>

Conditional Rendering

const [showChat, setShowChat] = useState(true);

return showChat ? (
  <FloatingCopilot
    config={{
      onClose: () => setShowChat(false),
    }}
  />
) : null;

Multiple Instances

<FloatingCopilot
  config={{
    position: 'bottom-right',
    title: 'Chat',
    zIndex: 9999,
  }}
/>

<FloatingCopilot
  config={{
    position: 'bottom-left',
    title: 'Support',
    zIndex: 9998,
  }}
/>

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Styling

The widget uses CSS variables for theming. You can override them globally:

:root {
  --primary-color: #6366f1;
  --bg-color: #ffffff;
  --text-color: #1f2937;
  --border-color: #e5e7eb;
}

TypeScript Support

Full TypeScript support with exported types:

import { FloatingCopilot, FloatingCopilotConfig } from 'floating-copilot-widget';

const config: FloatingCopilotConfig = {
  position: 'bottom-right',
  // ... type-safe configuration
};

<FloatingCopilot config={config} />

Documentation

• Quick Start: Read this README for basic setup
• Implementation Guide: See QUICK_IMPLEMENTATION_GUIDE.md for step-by-step parameter collection examples
• Full Documentation: See COPILOT_INTEGRATION.md for comprehensive API reference
• Setup Reference: See COPILOT_SETUP.md for feature details and best practices
• Working Examples: See examples/CopilotExample.tsx for 6 complete working examples

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues or questions, please open an issue on the GitHub repository.

Quick Links:

• GitHub Token Setup
• Copilot Documentation
• Report Issue