Aura Chat Widget Integration Guide

This guide explains how to install and use the Aura Chat Widget in your project.

🚀 1. Installation

Install the package via npm:

npm install aura-chat-widget

🛠️ 2. Frontend Usage

To add the chat to your React website, import the component and provide the configuration.

import { ChatWidget } from 'aura-chat-widget';

function App() {
  const chatConfig = {
    socketUrl: "https://your-chat-server.com", 
    projectId: "your-unique-project-id", // Mandatory for namespacing
    adminToken: "", // Leave empty for Visitor mode, provide JWT for Admin mode
    
    // OPTIONAL: Load "Outfit" font from Google Fonts (default: true)
    loadDefaultFonts: true,

    // OPTIONAL: Pass any custom data about the user
    metadata: {
      plan: "premium",
      source: "header_widget"
    },

    // LABEL CONFIGURATION (Text Overrides)
    labels: {
      inputPlaceholder: "Type a message...",
      adminPlaceholder: "Reply to user...",
      adminTitle: "Admin Panel",
      adminListHeader: "Active Conversations",
      adminEmpty: "No active users",
      typingText: "Typing...",
      onlineStatus: "Online",
    },

 
    // You can use Hex codes, RGB, or CSS Variables
    theme: {
      primary: "#4f46e5",
      secondary: "#818cf8",
      bg: "#ffffff",
      surface: "#ffffff",
      text: "#1f2937",
      headerText: "#ffffff",
      userBubble: "#4f46e5",
      userText: "#ffffff",
      botBubble: "#f3f4f6",
      botText: "#1f2937",
      border: "rgba(0, 0, 0, 0.1)",
      statusOnline: "#10b981",
      accent: "#4f46e5",
      textMuted: "#6b7280"
    }
  };

  return <ChatWidget config={chatConfig} />;
}

3. Full Theme Reference

You can customize every part of the widget's appearance. Here is the complete list of supported theme keys:

| Key | Description | | :--- | :--- | | primary | Main brand color (Launcher & Header) | | secondary | Accent branding color | | bg | Main chat window background | | surface | Card and input surface color | | surfaceLow | Slightly darker surface for depth | | surfaceLight | Slightly lighter surface for highlights | | text | Main body text color | | textMuted | Secondary/Timestamp text color | | headerText | Text color specifically for the primary header | | userBubble | Background color for the visitor's message | | userText | Text color for the visitor's message | | botBubble | Background color for the administrator's message | | botText | Text color for the administrator's message | | border | Color for separators and input borders | | statusOnline | Color for the "Online" indicator dot | | accent | Color for icons and small UI highlights |

4. Backend Requirements

The widget requires a Socket.io backend supporting version 4.x. Required events: user_join, user_message, message_to_user, admin_message_sync, typing.

5. Essential Tips

1. CORS: Your backend must whitelist your website's domain in its CORS settings.
2. CSS Variables: As shown in the example, the widget supports CSS Variables (e.g., var(--color-name)), allowing it to automatically sync with your existing website theme or Dark Mode.
3. Security: The adminToken should be fetched from your secure auth system and never hardcoded in production code.