AI-Powered Support Chatbot Widget

This project provides an embeddable AI-powered support chatbot widget integrated into a Next.js application. It features an LLM-based agentic chatbot with function calling capabilities, a modern UI, and customizable options.

Table of Contents

1. Features
2. Installation
3. Usage
   • For Next.js Websites
4. Customization
5. Function Calling
6. API Reference
7. UI Components
8. Styling
9. Accessibility
10. Troubleshooting

Features

• LLM-based AI chatbot for intelligent responses
• Function calling capabilities for extended functionality
• Modern, responsive UI with dark mode support
• Customizable appearance and behavior
• Accessibility features including keyboard navigation and screen reader support
• File attachment and emoji support (placeholder functionality)
• Smooth animations and transitions

Installation

1. Install the package via npm:

   npm install ai-powered-chatbot-widget   ```
   

2. If you're using a bundler, make sure to install the peer dependencies:

   npm install react react-dom @radix-ui/react-avatar @radix-ui/react-scroll-area @radix-ui/react-tooltip lucide-react next-themes   ```
   

Usage

For Next.js Websites

1. Set Up Environment Variables:

   Add your API key to .env.local:

   NEXT_PUBLIC_CHATBOT_API_KEY=your-api-key-here   ```
   

2. Import and Embed the Chatbot Widget:

   The widget is integrated into app/layout.tsx as shown in the Integration Guide.

Customization

You can customize the appearance and behavior of the chatbot by modifying the props passed to the ChatbotWidget:

• apiKey (required): Your API key for authentication.
• theme (optional): 'light' or 'dark' to match your website's theme. Can be dynamic based on your application's theme state.
• language (optional): The language code for the chatbot's responses. Default is 'en'.
• fallback (optional): An email address for fallback support.
• availableFunctions (optional): An object containing functions that can be called by the chatbot.
• backendUrl (optional): Your backend server URL handling chatbot requests.

Function Calling

The chatbot supports function calling, allowing it to perform actions or retrieve information. To use this feature:

1. Define your functions in the availableFunctions object when initializing the chatbot.
2. Each function should be asynchronous and accept an args parameter.
3. The chatbot will automatically detect when to call these functions based on the conversation context.

Example:

const availableFunctions = {
  getWeather: async (args) => {
    // Implement weather fetching logic
    return { temperature: 22, condition: 'Sunny' }
  },
  bookAppointment: async (args) => {
    // Implement appointment booking logic
    return { success: true, appointmentId: '12345' }
  }
}

API Reference

ChatbotWidget

interface ChatbotWidgetProps {
  apiKey: string;
  theme?: 'light' | 'dark';
  language?: string;
  fallback?: string;
  availableFunctions?: Record<string, Function>;
  backendUrl?: string;
}

class ChatbotWidget {
  constructor(props: ChatbotWidgetProps);
  mount(elementId?: string): void;
}

• constructor(props): Creates a new instance of the ChatbotWidget.
• mount(elementId?): Mounts the chatbot widget to the DOM. If elementId is not provided, it creates a new div element and appends it to the body.

UI Components

The chatbot widget uses the following UI components:

• Button: For actions like sending messages and toggling the chat window.
• Input: For the message input field.
• ScrollArea: For scrollable message history.
• Avatar: To display user and bot avatars.
• Card: The main container for the chat window.
• Tooltip: For providing additional context on hover.

These components are built using Radix UI primitives and styled with Tailwind CSS.

Styling

The widget uses Tailwind CSS for styling. You can customize the appearance by modifying the Tailwind configuration or overriding classes in your own CSS.

Customizing the Theme

Modify the following Tailwind CSS variables in your CSS files to customize the theme:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;
  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.5rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --card: 222.2 84% 4.9%;
  --card-foreground: 210 40% 98%;
  --popover: 222.2 84% 4.9%;
  --popover-foreground: 210 40% 98%;
  --primary: 210 40% 98%;
  --primary-foreground: 222.2 47.4% 11.2%;
  --secondary: 217.2 32.6% 17.5%;
  --secondary-foreground: 210 40% 98%;
  --muted: 217.2 32.6% 17.5%;
  --muted-foreground: 215 20.2% 65.1%;
  --accent: 217.2 32.6% 17.5%;
  --accent-foreground: 210 40% 98%;
  --destructive: 0 62.8% 30.6%;
  --destructive-foreground: 210 40% 98%;
  --border: 217.2 32.6% 17.5%;
  --input: 217.2 32.6% 17.5%;
  --ring: 212.7 26.8% 83.9%;
}

Accessibility

The chatbot widget is designed with accessibility in mind:

• ARIA Labels: Proper ARIA labels are used for all interactive elements.
• Keyboard Navigation: The chat window is navigable via keyboard.
• Color Contrast: Color contrast ratios meet WCAG 2.1 AA standards.
• Screen Reader Support: Screen reader announcements for new messages and status changes.

Troubleshooting

1. Widget Not Appearing:

   • Ensure that the script is loaded correctly and that you're calling the mount() method after the DOM is fully loaded.
   • Verify that the ChatbotWidget component is correctly imported and used within layout.tsx.

2. Styling Conflicts:

   • If the widget's styling conflicts with your website, ensure that the chatbot-widget-isolation class is applied to the root <div> of the widget.
   • Confirm that the Tailwind important flag is correctly set in tailwind.config.js.

3. Console Errors:

   • Check the browser console for any error messages. Ensure that you're using a valid API key and that all required props are provided.

4. Function Calling Not Working:

   • Make sure that your functions are properly defined in the availableFunctions object and that they return a Promise or are async functions.

For more help, please contact our support team at [email protected] or open an issue on our GitHub repository.

Embedding the Chatbot Widget in Next.js

To ensure that the Chatbot Widget's design remains consistent and isolated from external styles or CSS, follow these guidelines when embedding the widget into your Next.js application:

1. Use the Provided Mount Method in layout.tsx:

   The widget is already integrated into layout.tsx as shown above. Ensure that it's placed within the ThemeProvider to handle theme changes effectively.

2. Avoid Global CSS Conflicts:

   • Ensure that the container (.chatbot-widget-isolation) does not have any global styles that might interfere with the widget's appearance.
   • The widget uses a high z-index and scoped classes to prevent external styles from affecting it, but it's best to embed it in a neutral container.

3. Do Not Nest the Widget Within Styled Components:

   • Avoid placing the widget inside elements that have their own CSS frameworks or styles that could cascade down and override the widget's styles.

4. Ensure No CSS Resets Affect the Widget Container:

   • While the widget is designed to isolate its styles, using global CSS resets on the widget container might interfere with its appearance. Use a dedicated, neutral container for mounting the widget.

5. Optional: Using an <iframe> for Complete Isolation:

   • If you require absolute isolation from the host page's styles, consider embedding the widget within an <iframe>. This approach ensures that no styles from the parent page can affect the widget.

   <iframe src="path/to/chatbot-widget.html" style="border:none; width:400px; height:600px;"></iframe>

   • Note: Using an <iframe> might require additional setup to handle communication between the parent page and the widget.

By following these guidelines, you can ensure that the Chatbot Widget maintains its intended design and functionality without being affected by external styles or CSS rules.

10. Final Verification

After completing the integration:

1. Run the Development Server:

   npm run dev

2. Navigate to Your Application:

   Open your browser and navigate to http://localhost:3000 (or your configured port) to see the Chatbot Widget in action.

3. Test Functionality and Styling:

   • Open the chatbot by clicking the widget button.
   • Send messages to ensure that responses are as expected.
   • Toggle between light and dark modes (if implemented) to verify theme responsiveness.
   • Ensure that the widget's styling remains isolated and consistent across different pages and screen sizes.

11. Potentially Relevant Imported Files

If further adjustments are needed to maintain the widget's isolation, consider reviewing the following files:

• src/components/ui/button.tsx: Verify button variants and sizes align with the updated design.
• src/components/ui/input.tsx: Ensure input fields have adequate padding and focus styles.
• src/components/ui/avatar.tsx: Confirm avatar sizes and fallback styles match the new design.
• tailwind.config.js: Ensure the important flag is correctly set and that content paths include all relevant directories.

12. Recap of Changes

src/components/ChatBotWidget.tsx

• Applied the chatbot-widget-isolation class to the root <div> to ensure style isolation.
• Ensured all components and elements within the widget use scoped classes.
• Maintained high z-index to prevent layering issues.

src/styles/tailwind.css

• Enhanced isolation styles with all: unset for comprehensive style resets.
• Scoped scrollbar and element reset styles within .chatbot-widget-isolation.
• Added fade-in animations scoped within the isolation container.

README.md

• Updated embedding instructions to cater specifically to Next.js integration.
• Emphasized the importance of isolation and provided clear guidelines.

By meticulously following these steps and ensuring that all configurations are correctly set, your Chatbot Widget should integrate seamlessly into your Next.js project, maintaining its intended design and functionality without interference from external styles or CSS rules.

Feel free to reach out if you encounter any issues or need further assistance!