Metapercept ChatBot Widget

A React component for integrating Metapercept's AI chatbot into your applications.

Installation

npm install metapercept-react-chatbot-widget

Quick Start

import React from "react";
import { ChatBotWidget } from "metapercept-react-chatbot-widget";
import "metapercept-react-chatbot-widget/style.css";

function App() {
  return (
    <div className="App">
      <ChatBotWidget
        title="My Assistant"
        primaryColor="#007bff"
        theme="light"
        welcomeMessage="Hello! How can I help you today?"
      />
    </div>
  );
}

export default App;

Usage Examples

Basic Usage (Testing)

import { ChatBotWidget } from "metapercept-react-chatbot-widget";
import "metapercept-react-chatbot-widget/style.css";

// Uses API key from package .env file
<ChatBotWidget
  title="My AI Assistant"
  primaryColor="#2563eb"
  welcomeMessage="Welcome! I'm here to help you."
/>

Production Usage with API Key

import { ChatBotWidget } from "metapercept-react-chatbot-widget";
import "metapercept-react-chatbot-widget/style.css";

function MyApp() {
  const apikey = process.env.REACT_APP_API_KEY;

  return (
    <ChatBotWidget
      apiKey={apikey}
      title="My AI Assistant"
      primaryColor="#2563eb"
      welcomeMessage="Welcome! I'm here to help you."
    />
  );
}

With Error Handling

import { ChatBotWidget } from "metapercept-react-chatbot-widget";
import "metapercept-react-chatbot-widget/style.css";

function MyApp() {
  const apikey = process.env.REACT_APP_API_KEY;

  const handleError = (
    error: any,
    validationErrors?: Record<string, string>
  ) => {
    console.error("ChatBot Error:", error);
    if (validationErrors) {
      console.error("Validation Errors:", validationErrors);
      // Handle validation errors in your app
    }
  };

  return (
    <ChatBotWidget
      apiKey={apikey}
      title="My AI Assistant"
      primaryColor="#2563eb"
      welcomeMessage="Welcome! I'm here to help you."
      onError={handleError}
    />
  );
}

With Custom Toast Notifications

import { ChatBotWidget } from "metapercept-react-chatbot-widget";
import "metapercept-react-chatbot-widget/style.css";

function MyApp() {
  const apikey = process.env.REACT_APP_API_KEY;

  return (
    <ChatBotWidget
      apiKey={apikey}
      title="My AI Assistant"
      primaryColor="#2563eb"
      // Toast customization
      toastPosition="bottom-left"
      toastDuration={8000}
      customToastStyles={{
        container: { zIndex: 99999 },
        toast: { 
          backgroundColor: '#1f2937',
          color: 'white',
          borderRadius: '12px'
        },
        title: { fontSize: '16px', fontWeight: 'bold' },
        message: { fontSize: '14px', opacity: 0.9 }
      }}
    />
  );
}

Disable Toast Notifications

<ChatBotWidget
  apiKey={apikey}
  title="My AI Assistant"
  disableToasts={true}
  onError={(error, validationErrors) => {
    // Handle errors with your own notification system
    if (validationErrors) {
      // Show your custom validation error UI
      showCustomErrorModal(validationErrors);
    }
  }}
/>

Customized Appearance

<ChatBotWidget
  apiKey={apikey}
  title="Support Chat"
  primaryColor="#2563eb"
  secondaryColor="#64748b"
  position="bottom-left"
  theme="dark"
  height="600px"
  width="450px"
  borderRadius="20px"
  placeholder="Ask me anything..."
/>

Company Branded

<ChatBotWidget
  apiKey={apikey}
  title="Acme Support"
  logo="/company-logo.png"
  primaryColor="#059669"
  welcomeMessage="Hi! Welcome to Acme support. How can we help?"
  showTypingIndicator={true}
/>

Fully Customized Design

<ChatBotWidget
  apiKey={apikey}
  title="Custom Chat"
  // Typography
  fontFamily="'Inter', sans-serif"
  fontSize="15px"
  fontWeight="500"
  // Colors
  primaryColor="#6366f1"
  backgroundColor="#f8fafc"
  textColor="#1e293b"
  headerBackgroundColor="#4f46e5"
  headerTextColor="#ffffff"
  userMessageBackgroundColor="#6366f1"
  botMessageBackgroundColor="#ffffff"
  inputBackgroundColor="#ffffff"
  inputTextColor="#1e293b"
  inputBorderColor="#e2e8f0"
  // Spacing
  padding="20px"
  messagePadding="14px 18px"
  inputPadding="12px 16px"
  // Borders
  borderRadius="16px"
  messageBorderRadius="16px"
  inputBorderRadius="24px"
  borderWidth="2px"
  borderColor="#e2e8f0"
  // Shadows
  boxShadow="0 20px 25px -5px rgba(0, 0, 0, 0.1)"
  messageShadow="0 4px 6px -1px rgba(0, 0, 0, 0.1)"
  // Custom styles
  customStyles={{
    "--custom-gradient": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
  }}
  customClasses="my-custom-chat"
/>

Getting Your API Key

1. Start the Metapercept Chatbot backend server
2. Open the dashboard at http://localhost:8501
3. Navigate to API Key Management
4. Click Create New API Key
5. Fill in the details and copy your API key
6. Use the API key in your React application

Props

| Prop | Type | Default | Description | | ---------------------------- | ----------------------------- | ------------------------ | -------------------------------------- | | apiKey | string | From env | Your API key (optional if set in .env) | | title | string | "Metapercept Chat Bot" | Widget title | | logo | string | undefined | Logo URL | | primaryColor | string | "#007bff" | Primary theme color | | secondaryColor | string | "#6c757d" | Secondary theme color | | position | string | "bottom-right" | Widget position | | placeholder | string | "Type your message..." | Input placeholder text | | welcomeMessage | string | Auto-generated | Custom welcome message | | height | string | "500px" | Widget height | | width | string | "400px" | Widget width | | borderRadius | string | "12px" | Widget border radius | | showTypingIndicator | boolean | true | Show typing animation | | theme | "light" \| "dark" \| "auto" | "light" | Color theme | | onError | function | undefined | Error callback function | | fontFamily | string | inherit | Font family | | fontSize | string | 14px | Font size | | fontWeight | string | 400 | Font weight | | backgroundColor | string | Theme default | Background color | | textColor | string | Theme default | Text color | | headerBackgroundColor | string | primaryColor | Header background | | headerTextColor | string | white | Header text color | | messageBackgroundColor | string | Theme default | Messages area background | | userMessageBackgroundColor | string | primaryColor | User message background | | botMessageBackgroundColor | string | Theme default | Bot message background | | inputBackgroundColor | string | Theme default | Input background | | inputTextColor | string | Theme default | Input text color | | inputBorderColor | string | Theme default | Input border color | | padding | string | 16px | General padding | | messagePadding | string | 12px 16px | Message padding | | inputPadding | string | 10px 12px | Input padding | | borderColor | string | Theme default | Border color | | borderWidth | string | 1px | Border width | | messageBorderRadius | string | 12px | Message border radius | | inputBorderRadius | string | 20px | Input border radius | | boxShadow | string | Default shadow | Widget shadow | | messageShadow | string | Default shadow | Message shadow | | customStyles | React.CSSProperties | {} | Custom CSS properties | | customClasses | string | '' | Custom CSS classes | | enableEmailTranscript | boolean | true | Enable email transcript functionality | | autoSendTranscript | boolean | true | Auto-send transcript on inactivity | | inactivityTimeoutMinutes | number | 30 | Minutes before auto-sending transcript | | showEmailButton | boolean | true | Show manual email transcript button | | showEndChatButton | boolean | true | Show end chat & email button | | toastPosition | string | "top-right" | Toast notification position | | toastDuration | number | 5000 | Toast display duration (ms) | | disableToasts | boolean | false | Disable built-in toast notifications | | customToastStyles | object | {} | Custom styles for toast notifications |

API Configuration

Required Setup

You must provide:

1. API Base URL - Set VITE_API_URL in your project's .env
2. API Key - Pass via apiKey prop

Environment Variables

In your project's .env file:

# Required: Your Metapercept API base URL
VITE_API_URL=https://your-api-domain.com/api/v1

# Optional: API key (recommended to pass as prop instead)
REACT_APP_API_KEY=your-api-key-here

Priority Order

1. Passed apiKey prop - Recommended approach
2. Environment variable - Fallback only

Error Handling

Automatic Error Display

Validation errors are automatically displayed in the user info form with:

• Red border on invalid fields
• Error messages below each field
• User-friendly error text

Custom Error Handling

Use the onError callback for custom error handling:

const handleError = (error: any, validationErrors?: Record<string, string>) => {
  // Log errors
  console.error("ChatBot Error:", error);

  // Handle validation errors
  if (validationErrors) {
    Object.entries(validationErrors).forEach(([field, message]) => {
      console.error(`${field}: ${message}`);
    });

    // Send to analytics, show notifications, etc.
    analytics.track("chatbot_validation_error", validationErrors);
  }
};

<ChatBotWidget apiKey={apikey} onError={handleError} />;

Error Types

• Validation Errors: Invalid user input (email format, phone length, etc.)
• Network Errors: Connection issues
• Authentication Errors: Invalid API key

Toast Notifications

The widget includes built-in toast notifications for error handling and user feedback.

Built-in Toast Features

• ✅ Automatic Error Display: Shows validation errors, network issues, and API errors
• ✅ Multiple Types: Success, error, warning, and info notifications
• ✅ Customizable Position: Top-right, top-left, bottom-right, bottom-left
• ✅ Custom Styling: Override colors, fonts, spacing, and more
• ✅ Auto-dismiss: Configurable duration with manual close option
• ✅ Responsive: Adapts to mobile screens

Toast Customization

<ChatBotWidget
  apiKey={apikey}
  // Position: "top-right" | "top-left" | "bottom-right" | "bottom-left"
  toastPosition="bottom-left"
  
  // Duration in milliseconds (0 = no auto-dismiss)
  toastDuration={8000}
  
  // Custom styles for different parts
  customToastStyles={{
    container: {
      zIndex: 99999,
      maxWidth: '500px'
    },
    toast: {
      backgroundColor: '#1f2937',
      color: 'white',
      borderRadius: '12px',
      boxShadow: '0 10px 40px rgba(0, 0, 0, 0.3)'
    },
    title: {
      fontSize: '16px',
      fontWeight: 'bold',
      color: '#ffffff'
    },
    message: {
      fontSize: '14px',
      opacity: 0.9,
      lineHeight: '1.5'
    }
  }}
/>

Disable Built-in Toasts

If you prefer to use your own notification system:

<ChatBotWidget
  apiKey={apikey}
  disableToasts={true}
  onError={(error, validationErrors) => {
    // Use your own notification system
    if (validationErrors) {
      yourNotificationSystem.showErrors(validationErrors);
    } else {
      yourNotificationSystem.showError(error.message);
    }
  }}
/>

Toast Types

• Error: Red border, error icon - for validation and API errors
• Success: Green border, check icon - for successful operations
• Warning: Orange border, warning icon - for warnings
• Info: Blue border, info icon - for informational messages

API Key Management

API keys are managed through the backend dashboard, not in this package. The dashboard provides:

• ✅ Create API keys with custom expiration dates
• ✅ Regenerate existing keys
• ✅ Update key details and descriptions
• ✅ Deactivate keys
• ✅ Monitor key usage and last used timestamps

Security Notes

• Never commit API keys to version control
• Use environment variables for API keys in production
• Package .env is only for testing/development
• Regularly rotate your API keys
• Monitor API key usage in the dashboard
• Deactivate unused keys

Email Transcript Feature

The chatbot automatically sends email transcripts to users when they become inactive or when manually requested.

Automatic Transcript Sending

<ChatBotWidget
  apiKey={apikey}
  enableEmailTranscript={true}
  autoSendTranscript={true}
  inactivityTimeoutMinutes={30}
/>

Manual Transcript Controls

<ChatBotWidget
  apiKey={apikey}
  enableEmailTranscript={true}
  showEmailButton={true}
  showEndChatButton={true}
/>

Disable Email Transcript

<ChatBotWidget
  apiKey={apikey}
  enableEmailTranscript={false}
/>

How It Works

1. User Information: When users fill the initial form, their email is stored
2. Auto-Send: After 30 minutes of inactivity, transcript is automatically emailed
3. Manual Send: Users can click "Email Transcript" button anytime
4. End Chat: Users can click "End & Email" to end session and get transcript
5. Page Exit: Transcript is sent when user closes/leaves the page

Email Transcript Features

• ✅ HTML formatted emails with conversation styling
• ✅ Plain text attachment for accessibility
• ✅ User information included in transcript
• ✅ Automatic sending on inactivity
• ✅ Manual sending via button
• ✅ Session end with transcript
• ✅ Page exit detection

Support

For issues and support, please contact the Metapercept team.