Metapercept ChatBot Widget

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

Installation

``bash
npm install metapercept-react-chatbot-widget
`

Quick Start

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

function App() {
return (


);
}

export default App;
`

Usage Examples

$3

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

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

$3

`tsx
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 (
apiKey={apikey}
title="My AI Assistant"
primaryColor="#2563eb"
welcomeMessage="Welcome! I'm here to help you."
/>
);
}
`

$3

`tsx
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
) => {
console.error("ChatBot Error:", error);
if (validationErrors) {
console.error("Validation Errors:", validationErrors);
// Handle validation errors in your app
}
};

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

$3

`tsx
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 (
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 }
}}
/>
);
}
`

$3

`tsx
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);
}
}}
/>
`

$3

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

$3

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

$3

`tsx
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

$3

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

$3

In your project's .env file:

`bash


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
`

$3

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

Error Handling

$3

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

$3

Use the onError callback for custom error handling:

`tsx
const handleError = (error: any, validationErrors?: Record) => {
// 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);
}
};

;
`

$3

- 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.

$3

- ✅ 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

$3

`tsx
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'
}
}}
/>
`

$3

If you prefer to use your own notification system:

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

$3

- 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.

$3

`tsx
apiKey={apikey}
enableEmailTranscript={true}
autoSendTranscript={true}
inactivityTimeoutMinutes={30}
/>
`

$3

`tsx
apiKey={apikey}
enableEmailTranscript={true}
showEmailButton={true}
showEndChatButton={true}
/>
`

$3

`tsx
apiKey={apikey}
enableEmailTranscript={false}
/>
``

$3

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

$3

- ✅ 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.