Blumessage React Chat Component

A React TypeScript chat widget component with floating button, theming, and Blumessage API integration. Features real-time messaging, conversation persistence, error handling, and a modern UI built with Tailwind CSS.

✨ Features

• 🎈 Floating Chat Widget - Appears as a button, expands to full chat
• 🎨 Light/Dark Themes - Built-in theme support
• 💾 Persistent Storage - Save conversations to localStorage or sessionStorage
• 🔄 Real-time Messaging - Instant API integration with Blumessage
• 📱 Responsive Design - Works on desktop and mobile
• 🎯 Flexible Icons - Supports various icon patterns
• ⚡ Error Handling - Comprehensive error callbacks
• 🔧 Highly Customizable - Extensive prop options

Installation

NPM Package (Recommended)

npm i @blumessage/react-chat

Browser Versions

Option 1: Standalone (Includes React)

For the simplest setup with everything included:

<!-- Load the Blumessage Chat component (includes React) -->
<script src="path/to/index.js"></script>

Option 2: External React (Smaller Bundle)

For when you already have React loaded:

<!-- Load React and ReactDOM from CDN -->
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- Load the Blumessage Chat component -->
<script src="path/to/blumessage-chat.browser.js"></script>

See BROWSER_USAGE.md for complete browser usage documentation.

Quick Start

Floating Chat Widget (Default)

import React from 'react';
import { BlumessageChat } from '@blumessage/react-chat';

function App() {
  return (
    <BlumessageChat 
      apiKey="your-blumessage-api-key"
    />
  );
}

Embedded Chat

import React from 'react';
import { BlumessageChat } from '@blumessage/react-chat';

function App() {
  return (
    <BlumessageChat 
      apiKey="your-blumessage-api-key"
      floating={false}
      width="400px"
      height="600px"
    />
  );
}

Complete Props Reference

| Prop | Type | Default | Description | |------|------|---------|-------------| | Required | | apiKey | string | - | Your Blumessage API key | | Display & Content | | name | string | "Blumessage AI" | Display name for the AI assistant | | subtitle | string | "Online • Instant responses" | Subtitle shown under the name | | placeholder | string | "Type your message..." | Input placeholder text | | theme | 'light' \| 'dark' | 'light' | Chat widget theme | | primaryColor | string | "linear-gradient(to right, #3b82f6,rgb(8, 98, 242))" | Primary color/gradient | | Layout & Sizing | | floating | boolean | true | Show as floating widget vs embedded | | width | string | '380px' (medium) | Custom width (overrides size) | | height | string | '500px' (medium) | Custom height (overrides size) | | size | 'small' \| 'medium' \| 'large' | 'medium' | Predefined size preset | | fullScreen | boolean | false | Force full screen mode | | Floating Widget Options | | buttonText | string | "Chat with us" | Text on floating button | | buttonPosition | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Button position | | buttonStyle | React.CSSProperties | - | Custom button styles | | defaultOpen | boolean | false | Start with chat open | | maximizeToggleButton | boolean | true | Show maximize/minimize button | | icon | string | 'message-circle' | Icon for button (flexible naming) | | Help Bubble Options | | showHelpBubble | boolean | true | Show help bubble above floating button | | helpBubbleMessage | string | "👋 If you need help chat with us" | Message text in help bubble | | helpBubbleIcon | string | 'hand' | Icon for help bubble (supports lucide-react icon names) | | helpBubbleShowAfter | number | 1 | Seconds to wait before showing bubble | | helpBubbleHideAfter | number | 5 | Seconds to wait before hiding bubble (0 = never hide) | | Messages & Data | | initialMessages | Message[] | [] | Pre-populate with messages | | conversationId | string | - | Continue specific conversation | | persistent | boolean | false | Use localStorage vs sessionStorage | | showTimestamps | boolean | false | Display timestamps: today="2:00 PM", older="17 July, 1:00 PM" | | typingText | string | "Agent is typing..." | Custom text shown while waiting for assistant response | | emptyStateText | string | "Start a conversation!" | Text shown when no messages are present | | markdown | boolean | true | Enable markdown rendering for messages | | disableAutoScroll | boolean | false | Disable automatic scrolling to bottom when new messages arrive | | Event Callbacks | | onUserMessage | (message: Message) => void | - | Called when user sends message | | onAssistantMessage | (message: Message) => void | - | Called when assistant responds | | onConversationIdChange | (id: string \| null) => void | - | Called when conversation ID changes | | onChatWidgetOpen | () => void | - | Called when floating chat opens | | onChatWidgetClosed | () => void | - | Called when floating chat closes | | onError | (error: string, context?: string) => void | - | Called on any error |

Advanced Usage Examples

Dark Theme with Callbacks

<BlumessageChat 
  apiKey="your-api-key"
  theme="dark"
  name="Support Bot"
  onUserMessage={(message) => console.log('User:', message.content)}
  onAssistantMessage={(message) => console.log('Bot:', message.content)}
  onError={(error, context) => console.error(`Error in ${context}:`, error)}
/>

Persistent Storage

<BlumessageChat 
  apiKey="your-api-key"
  persistent={true}  // Saves to localStorage instead of sessionStorage
  onConversationIdChange={(id) => {
    // Optionally save ID to your own storage
    if (id) localStorage.setItem('my-chat-id', id);
  }}
/>

Custom Styling & Size

<BlumessageChat 
  apiKey="your-api-key"
  size="large"
  primaryColor="linear-gradient(45deg, #ff6b6b, #4ecdc4)"
  buttonPosition="bottom-left"
  buttonText="Need Help?"
  icon="headphones"
  maximizeToggleButton={true}
/>

Embedded with Initial Messages

const initialMessages = [
  {
    id: '1',
    role: 'assistant' as const,
    content: 'Hello! How can I help you today?',
    timestamp: Date.now()
  }
];

<BlumessageChat 
  apiKey="your-api-key"
  floating={false}
  width="100%"
  height="500px"
  initialMessages={initialMessages}
  placeholder="Ask me anything..."
/>

Help Bubble Configuration

<BlumessageChat 
  apiKey="your-api-key"
  floating={true}
  showHelpBubble={true}
  helpBubbleMessage="👋 Need assistance? We're here to help!"
  helpBubbleIcon="hand"  // Use hand icon (default)
  helpBubbleShowAfter={3}  // Show after 3 seconds
  helpBubbleHideAfter={10} // Hide after 10 seconds
/>

Custom Help Bubble Icons

<BlumessageChat 
  apiKey="your-api-key"
  floating={true}
  showHelpBubble={true}
  helpBubbleIcon="star"  // Use star icon
  helpBubbleMessage="⭐ Rate our service!"
  helpBubbleShowAfter={2}
  helpBubbleHideAfter={8}
/>

<BlumessageChat 
  apiKey="your-api-key"
  floating={true}
  showHelpBubble={true}
  helpBubbleIcon="lightbulb"  // Use lightbulb icon
  helpBubbleMessage="💡 Got an idea? Let's discuss it!"
  helpBubbleShowAfter={1}
  helpBubbleHideAfter={0}  // Never hide
/>

<BlumessageChat 
  apiKey="your-api-key"
  floating={true}
  showHelpBubble={true}
  helpBubbleIcon="help-circle"  // Use help icon
  helpBubbleMessage="❓ Questions? We're here to help!"
  helpBubbleShowAfter={5}
  helpBubbleHideAfter={15}
/>

### Persistent Help Bubble (Never Hide)

```tsx
<BlumessageChat 
  apiKey="your-api-key"
  floating={true}
  showHelpBubble={true}
  helpBubbleMessage="💬 Questions? Click to chat with us!"
  helpBubbleShowAfter={2}  // Show after 2 seconds
  helpBubbleHideAfter={0}  // Never hide (0 = persistent)
/>

Chat with Timestamps

<BlumessageChat 
  apiKey="your-api-key"
  showTimestamps={true}  // Shows "2:00 PM" or "17 July, 1:00 PM"
  floating={false}
  initialMessages={[
    {
      id: '1',
      role: 'assistant' as const,
      content: 'Message from today',
      timestamp: Date.now() - (60 * 60 * 1000)  // Shows: "2:00 PM" (or "14:00")
    },
    {
      id: '2',
      role: 'user' as const,
      content: 'Message from yesterday',
      timestamp: Date.now() - (24 * 60 * 60 * 1000)  // Shows: "17 July, 1:00 PM"
    }
  ]}
/>

Custom Typing Indicator

<BlumessageChat 
  apiKey="your-api-key"
  typingText="Support agent is typing..."  // Custom loading message
  // Or use different text for different languages:
  // typingText="L'agent écrit..." // French
  // typingText="El agente está escribiendo..." // Spanish
/>

Custom Empty State Text

<BlumessageChat 
  apiKey="your-api-key"
  emptyStateText="Welcome! How can I help you today?"  // Custom empty state message
  // Or use different text for different contexts:
  // emptyStateText="Ask me anything about our products..."
  // emptyStateText="Ready to assist with your questions!"
/>

Disable Auto-Scroll

<BlumessageChat 
  apiKey="your-api-key"
  disableAutoScroll={true}  // Prevents automatic scrolling to bottom
  // Useful when you want users to maintain their scroll position
  // or when implementing custom scroll behavior
/>

Icon Options

The icon prop accepts any lucide-react icon name with flexible naming patterns. The component intelligently matches your input to the appropriate lucide-react icon:

// ✅ Any lucide-react icon works:
icon="message-circle"    // MessageCircle
icon="phone"             // Phone
icon="mail"              // Mail
icon="headphones"        // Headphones
icon="bot"               // Bot
icon="users"             // Users
icon="heart"             // Heart
icon="star"              // Star
icon="zap"               // Zap
icon="settings"          // Settings
icon="help-circle"       // HelpCircle
icon="info"              // Info
icon="alert-triangle"    // AlertTriangle

// ✅ Flexible naming patterns (case-insensitive, ignores hyphens/underscores):
icon="MessageCircle"     // → MessageCircle
icon="message_circle"    // → MessageCircle
icon="message circle"    // → MessageCircle
icon="chat"              // → MessageCircle (smart matching)
icon="messaging"         // → MessageCircle (smart matching)
icon="support"           // → Headphones (smart matching)
icon="email"             // → Mail (smart matching)
icon="call"              // → Phone (smart matching)

// ✅ Default fallback: MessageCircle (if no match found)
icon="unknown-icon"      // → MessageCircle

Browse all available icons at: lucide.dev/icons

Simply use the icon name from lucide-react, and the component will handle the rest!

Error Handling

The onError callback provides detailed error context:

<BlumessageChat 
  apiKey="your-api-key"
  onError={(error, context) => {
    switch(context) {
      case 'missing_api_key':
        // Handle missing API key
        break;
      case 'api_key_validation':
        // Handle invalid API key
        break;
      case 'network_error':
        // Handle network issues
        break;
      case 'conversation_history':
        // Handle history fetch errors
        break;
      case 'message_send':
        // Handle message sending errors
        break;
    }
  }}
/>

External Message Submission

The component supports external message submission through a ref, allowing parent components to programmatically send messages and control the chat widget.

Using the Ref

import React, { useRef } from 'react';
import { BlumessageChat, BlumessageChatRef } from '@blumessage/react-chat';

function App() {
  const chatRef = useRef<BlumessageChatRef>(null);

  const sendExternalMessage = async () => {
    if (chatRef.current) {
      await chatRef.current.sendMessage("Hello from external component!");
    }
  };

  const openChat = () => {
    chatRef.current?.openChat();
  };

  const closeChat = () => {
    chatRef.current?.closeChat();
  };

  const clearChat = () => {
    chatRef.current?.clearConversation();
  };

  const getMessages = () => {
    const messages = chatRef.current?.getMessages();
    console.log('Current messages:', messages);
  };

  const getToken = () => {
    const token = chatRef.current?.getToken();
    console.log('Current conversation token:', token);
  };

  return (
    <div>
      <button onClick={sendExternalMessage}>Send External Message</button>
      <button onClick={openChat}>Open Chat</button>
      <button onClick={closeChat}>Close Chat</button>
      <button onClick={clearChat}>Clear Chat</button>
      <button onClick={getMessages}>Get Messages</button>
      <button onClick={getToken}>Get Token</button>
      
      <BlumessageChat
        ref={chatRef}
        apiKey="your-api-key"
        floating={true}
      />
    </div>
  );
}

Available Ref Methods

| Method | Type | Description | |--------|------|-------------| | sendMessage(message: string) | Promise<void> | Send a message programmatically | | openChat() | void | Open the floating chat widget | | closeChat() | void | Close the floating chat widget | | clearConversation() | void | Clear all messages and reset conversation | | getMessages() | Message[] | Get current messages array | | getToken() | string \| null | Get current conversation token |

Complete Example with External Controls

import React, { useRef, useState } from 'react';
import { BlumessageChat, BlumessageChatRef } from '@blumessage/react-chat';

function App() {
  const [externalMessage, setExternalMessage] = useState('');
  const chatRef = useRef<BlumessageChatRef>(null);

  const handleSendExternalMessage = async () => {
    if (!externalMessage.trim() || !chatRef.current) return;
    
    try {
      await chatRef.current.sendMessage(externalMessage);
      setExternalMessage('');
      console.log('External message sent successfully');
    } catch (error) {
      console.error('Failed to send external message:', error);
    }
  };

  return (
    <div>
      <div style={{ marginBottom: '20px' }}>
        <input
          type="text"
          value={externalMessage}
          onChange={(e) => setExternalMessage(e.target.value)}
          placeholder="Type a message to send externally..."
          onKeyPress={(e) => e.key === 'Enter' && handleSendExternalMessage()}
        />
        <button onClick={handleSendExternalMessage}>Send</button>
        <button onClick={() => chatRef.current?.openChat()}>Open Chat</button>
        <button onClick={() => chatRef.current?.closeChat()}>Close Chat</button>
        <button onClick={() => chatRef.current?.clearConversation()}>Clear Chat</button>
      </div>
      
      <BlumessageChat
        ref={chatRef}
        apiKey="your-api-key"
        floating={true}
        onUserMessage={(message) => console.log('User message:', message)}
        onAssistantMessage={(message) => console.log('Assistant message:', message)}
      />
    </div>
  );
}

TypeScript Support

Full TypeScript definitions included:

import { BlumessageChat, Message, BlumessageChatProps, BlumessageChatRef } from '@blumessage/react-chat';

interface Message {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  timestamp: number;
}

interface BlumessageChatRef {
  sendMessage: (message: string) => Promise<void>;
  openChat: () => void;
  closeChat: () => void;
  clearConversation: () => void;
  getMessages: () => Message[];
  getToken: () => string | null;
}

Storage Behavior

• SessionStorage (default): Conversations persist until browser tab closes
• LocalStorage (persistent=true): Conversations persist across browser sessions
• Automatic cleanup: Invalid conversation IDs are automatically cleared
• History restoration: Previous conversations load automatically on component mount

Browser Support

• Modern browsers with ES2017+ support
• React 18+
• TypeScript 4.5+

Building

Standard Build (ES Modules)

npm run build

Browser Versions

Standalone (Includes React)

npm run build:commonjs

This creates dist/index.js which includes React and can be used directly in browsers.

External React (Smaller Bundle)

npm run build:browser

This creates dist/blumessage-chat.browser.js which requires React to be loaded separately.

License

UNLICENSED - For use only by customers with an active Blumessage subscription.

Support

For feature requests, technical support and assistance, please contact us at: [email protected]