You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 4-6.RSVP β†’
Socket
Book a DemoInstallSign in
Socket

@blumessage/react-chat

Package Overview
Dependencies
Maintainers
1
Versions
20
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@blumessage/react-chat

A React TypeScript chat widget component with floating button, theming, and Blumessage API integration

1.3.0
latest
npmnpm
Version published
Weekly downloads
9
-87.14%
Maintainers
1
Weekly downloads
Β 
Created
Source

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 i @blumessage/react-chat

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

PropTypeDefaultDescription
Required
apiKeystring-Your Blumessage API key
Display & Content
namestring"Blumessage AI"Display name for the AI assistant
subtitlestring"Online β€’ Instant responses"Subtitle shown under the name
placeholderstring"Type your message..."Input placeholder text
theme'light' | 'dark''light'Chat widget theme
primaryColorstring"linear-gradient(to right, #3b82f6,rgb(8, 98, 242))"Primary color/gradient
Layout & Sizing
floatingbooleantrueShow as floating widget vs embedded
widthstring'380px' (medium)Custom width (overrides size)
heightstring'500px' (medium)Custom height (overrides size)
size'small' | 'medium' | 'large''medium'Predefined size preset
fullScreenbooleanfalseForce full screen mode
Floating Widget Options
buttonTextstring"Chat with us"Text on floating button
buttonPosition'bottom-right' | 'bottom-left' | 'top-right' | 'top-left''bottom-right'Button position
buttonStyleReact.CSSProperties-Custom button styles
defaultOpenbooleanfalseStart with chat open
maximizeToggleButtonbooleantrueShow maximize/minimize button
iconstring'message-circle'Icon for button (flexible naming)
Messages & Data
initialMessagesMessage[][]Pre-populate with messages
conversationIdstring-Continue specific conversation
persistentbooleanfalseUse localStorage vs sessionStorage
showTimestampsbooleanfalseDisplay timestamps: today="2:00 PM", older="17 July, 1:00 PM"
typingTextstring"Agent is typing..."Custom text shown while waiting for assistant response
emptyStateTextstring"Start a conversation!"Text shown when no messages are present
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..."
/>

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!"
/>

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

MethodTypeDescription
sendMessage(message: string)Promise<void>Send a message programmatically
openChat()voidOpen the floating chat widget
closeChat()voidClose the floating chat widget
clearConversation()voidClear all messages and reset conversation
getMessages()Message[]Get current messages array
getToken()string | nullGet 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+

License

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

Support

For feature requests, technical support and assistance, please contact us at: contact@blumessage.com

Keywords

react

FAQs

Package last updated on 18 Jul 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts