@astermind/chatbot-template

@astermind/chatbot-template

Embeddable AI chatbot widget for AsterMind RAG - a drop-in chat UI that connects to your AsterMind backend with full agentic capabilities.

Table of Contents

• Architecture
• Features
• Installation
• Quick Start
• Configuration in Your Application
• Configuration Reference
• Theming
• React Hooks API
• Components API
• TypeScript Support
• Troubleshooting
• Browser Support
• License

Architecture

This package is the UI layer for the AsterMind Chatbot system. It provides pre-built React components and hooks for embedding a chatbot in your application.

Package Dependencies

Your Application
    │
    └── @astermind/chatbot-template (this package - UI components)
            │
            └── @astermind/cybernetic-chatbot-client (required - API client)

Important: @astermind/cybernetic-chatbot-client is automatically installed as a dependency. It provides:

• API Communication - Connects to your AsterMind backend
• Streaming Responses - SSE-based token-by-token message display
• Offline Fallback - Local RAG processing with IndexedDB cache
• Agentic Capabilities - DOM interactions (optional, tree-shakeable)

Where to Configure

All configuration is done in your application code, not in node_modules:

Configuration Method	Where to Set
React Props	In your component: <ChatbotWidget apiKey="..." />
Environment Variables	In your .env file
SSR Injection	In your server template
Global Object	In your HTML/JS before loading
Data Attributes	On your script tag

Features

Core Widget Features (this package)

• Embeddable Floating Chat Bubble - Position anywhere on the page (4 corners)
• React Components Library - 11 fully customizable components
• Vanilla JS Standalone Bundle - IIFE format with React bundled for non-React sites
• Full TypeScript Support - Complete type definitions exported
• Theming System - 20+ CSS custom properties for full visual customization

RAG & Backend Features (via cybernetic-chatbot-client)

• AsterMind Backend Integration - Connects to /api/external/chat endpoints
• Streaming Responses - SSE-based token-by-token message display
• Source Citations - Collapsible source references with confidence levels
• Session Management - Automatic sessionId handling across conversations
• Offline Fallback - Local RAG processing when backend is unavailable
• Connection Status - Automatic online/offline/connecting/error states

Agentic Capabilities (via cybernetic-chatbot-client)

When enabled, the chatbot can perform actions on your page:

• Navigation Actions - Navigate users to specific pages
• Form Filling - Auto-fill form fields with suggested values
• Element Clicking - Programmatically click buttons and links
• Modal Triggering - Open dialogs and modals
• Scrolling - Scroll to specific elements
• Element Highlighting - Draw attention to page elements
• Custom Action Handlers - Define your own action types

Agentic capabilities are tree-shakeable - they're only included in your bundle if you import and use them.

Installation

NPM (React Projects)

npm install @astermind/chatbot-template

This automatically installs @astermind/cybernetic-chatbot-client as a dependency.

Required imports — add both of these to your component file:

import { ChatbotWidget } from '@astermind/chatbot-template';
import '@astermind/chatbot-template/styles';  // Required — loads the chatbot CSS

Note: The styles import is required for the widget to render correctly. Without it, the chatbot will appear unstyled.

CDN (Vanilla JS)

Include both the stylesheet and the script in your HTML — the CSS is required for the widget to render correctly:

<!-- Required: Chatbot styles -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@astermind/chatbot-template/dist/astermind-chatbot.css">

<!-- Required: Chatbot widget (standalone bundle with React included) -->
<script src="https://cdn.jsdelivr.net/npm/@astermind/chatbot-template/dist/astermind-chatbot.min.js"></script>

Quick Start

React Usage

import { ChatbotWidget } from '@astermind/chatbot-template';
import '@astermind/chatbot-template/styles';

function App() {
  return (
    <ChatbotWidget
      apiUrl="https://your-api-url.com"
      apiKey="am_your-api-key"
      position="bottom-right"
      greeting="Hi! How can I help you today?"
    />
  );
}

Vanilla JS Usage

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@astermind/chatbot-template/dist/astermind-chatbot.css">
</head>
<body>
  <script src="https://cdn.jsdelivr.net/npm/@astermind/chatbot-template/dist/astermind-chatbot.min.js"></script>
  <script>
    AsterMindChatbot.init({
      apiUrl: 'https://your-api-url.com',
      apiKey: 'am_your-api-key',
      position: 'bottom-right',
      greeting: 'Hi! How can I help you today?'
    });
  </script>
</body>
</html>

Configuration in Your Application

All configuration is done in your application code. The chatbot-template reads configuration from several sources in your project.

React Applications

Option 1: Pass props directly

<ChatbotWidget
  apiUrl="https://api.astermind.ai"
  apiKey="am_your-api-key"
  position="bottom-right"
/>

Option 2: Use environment variables

Create a .env file in your project root:

# Vite projects
VITE_ASTERMIND_RAG_API_KEY=am_your_api_key
VITE_ASTERMIND_RAG_API_SERVER_URL=https://api.astermind.ai

# Create React App projects
REACT_APP_ASTERMIND_RAG_API_KEY=am_your_api_key
REACT_APP_ASTERMIND_RAG_API_SERVER_URL=https://api.astermind.ai

Then use the widget without explicit props:

<ChatbotWidget position="bottom-right" />

Vanilla JS Applications

Option 1: Pass config to init()

AsterMindChatbot.init({
  apiKey: 'am_your_api_key',
  apiUrl: 'https://api.astermind.ai',
  position: 'bottom-right'
});

Option 2: Global config object

<script>
  window.astermindConfig = {
    apiKey: 'am_your_api_key',
    apiUrl: 'https://api.astermind.ai'
  };
</script>
<script src="astermind-chatbot.min.js"></script>
<script>
  AsterMindChatbot.init();
</script>

Option 3: Script data attributes

<script
  src="astermind-chatbot.min.js"
  data-astermind-key="am_your_api_key"
  data-astermind-url="https://api.astermind.ai"
></script>

SSR / Server-Side Rendering

For Next.js, Nuxt, or other SSR frameworks:

<script>
  window.__ASTERMIND_CONFIG__ = {
    apiKey: '<%= process.env.ASTERMIND_RAG_API_KEY %>',
    apiUrl: '<%= process.env.ASTERMIND_RAG_API_SERVER_URL %>'
  };
</script>

Configuration Reference

Configuration Priority

The widget supports multiple configuration methods with this priority (highest to lowest):

• Props / init() config - Direct configuration passed to the component or init() function
• Environment variables - VITE_ASTERMIND_RAG_API_KEY, REACT_APP_ASTERMIND_RAG_API_KEY
• SSR-injected config - window.__ASTERMIND_CONFIG__
• Global object - window.astermindConfig
• Script data attributes - data-astermind-key, data-astermind-url

API Key and URL

Option	Type	Default	Description
apiKey	string	(from env)	Your AsterMind API key (starts with am_). Falls back to environment variables.
apiUrl	string	'https://api.astermind.ai'	Backend API URL. Falls back to environment variables.
throwOnMissingKey	boolean	true	Throw error if API key is missing. Set to false to log warning instead.

Widget Options

Option	Type	Default	Description
position	'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'	'bottom-right'	Widget position on screen
greeting	string	'Hi! How can I help you today?'	Initial greeting message
placeholder	string	'Type your message...'	Input placeholder text
headerTitle	string	'AsterMind'	Chat window header title
headerSubtitle	string	'AI Assistant'	Chat window header subtitle
defaultOpen	boolean	false	Start with chat window open
showPoweredBy	boolean	true	Show "Powered by AsterMind" badge
zIndex	number	9999	Z-index for the widget

Theme Options

Customize appearance via the theme object:

{
  theme: {
    primaryColor: '#4F46E5',
    primaryHover: '#4338CA',
    backgroundColor: '#ffffff',
    surfaceColor: '#f3f4f6',
    textColor: '#1f2937',
    textMuted: '#6b7280',
    borderColor: '#e5e7eb',
    userBubbleBackground: '#4F46E5',
    userBubbleText: '#ffffff',
    botBubbleBackground: '#f3f4f6',
    botBubbleText: '#1f2937',
    widgetWidth: '380px',
    widgetHeight: '75vh',      // Default: 75% of viewport height
    bubbleSize: '60px',
    borderRadius: '12px',
    fontFamily: "'Inter', system-ui, sans-serif",
    fontSize: '14px',
    shadow: '0 4px 20px rgba(0, 0, 0, 0.15)'
  }
}

Agent Configuration

Enable agentic capabilities (powered by cybernetic-chatbot-client):

{
  agent: {
    enabled: true,
    confidenceThreshold: 0.8,
    siteMap: [
      { path: '/products', name: 'Products', description: 'View products' },
      { path: '/contact', name: 'Contact', description: 'Contact us' }
    ],
    customActions: {
      openModal: async (params) => {
        document.getElementById(params.modalId).showModal();
      }
    }
  }
}

Fallback Configuration

Configure offline behavior:

{
  fallback: {
    enabled: true,
    message: 'Working in offline mode. Some features may be limited.'
  }
}

Event Callbacks

Callback	Parameters	Description
onReady	()	Called when widget is ready
onMessage	(message: ChatMessage)	Called on each message sent/received
onAction	(action: AgentAction)	Called when an agentic action occurs
onError	(error: Error)	Called when an error occurs
onToggle	(isOpen: boolean)	Called when widget opens/closes

Theming

CSS Variables

Override CSS variables in your stylesheet for quick customization:

:root {
  --astermind-primary: #10B981;
  --astermind-primary-hover: #059669;
  --astermind-background: #ffffff;
  --astermind-surface: #f3f4f6;
  --astermind-text: #1f2937;
  --astermind-text-muted: #6b7280;
  --astermind-border: #e5e7eb;
  --astermind-user-bubble-bg: #10B981;
  --astermind-user-bubble-text: #ffffff;
  --astermind-bot-bubble-bg: #f3f4f6;
  --astermind-bot-bubble-text: #1f2937;
  --astermind-widget-width: 400px;
  --astermind-widget-height: 75vh;  /* Default: 75% of viewport height (accepts px, vh, %) */
  --astermind-bubble-size: 64px;
  --astermind-border-radius: 16px;
  --astermind-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
  --astermind-font-family: 'Inter', system-ui, sans-serif;
  --astermind-font-size: 14px;
}

CSS Classes

All elements use the astermind- prefix:

Class	Element
.astermind-chatbot	Main container
.astermind-bubble	Floating trigger button
.astermind-window	Chat window
.astermind-header	Window header
.astermind-messages	Message list container
.astermind-message	Individual message
.astermind-message--user	User message modifier
.astermind-message--bot	Bot message modifier
.astermind-input	Input area
.astermind-status	Status indicator
.astermind-action-card	Action confirmation card
.astermind-sources	Source citations container

React Hooks API

useCybernetic

Direct API client access for custom implementations:

import { useCybernetic } from '@astermind/chatbot-template';

function MyComponent() {
  const {
    sendMessage,        // Send a message (non-streaming)
    sendMessageStream,  // Send a message (streaming)
    connectionStatus,   // 'online' | 'offline' | 'connecting' | 'error'
    isProcessing,       // Whether a request is in progress
    lastError,          // Last error that occurred
    sessionId,          // Current session ID
    clearSession,       // Clear the current session
    syncCache,          // Sync cache for offline use
    client              // Underlying CyberneticClient instance
  } = useCybernetic({
    apiUrl: 'https://api.example.com',
    apiKey: 'am_your-api-key'
  });

  const handleSend = async () => {
    const response = await sendMessage('Hello!');
    console.log(response.reply, response.sources);
  };
}

useChat

Chat state management:

import { useChat } from '@astermind/chatbot-template';

function MyComponent() {
  const {
    messages,          // Array of chat messages
    addMessage,        // Add a new message
    updateMessage,     // Update an existing message
    clearMessages,     // Clear all messages
    pendingAction,     // Currently pending agent action
    setPendingAction   // Set pending action
  } = useChat();
}

useTheme

Theme customization hook:

import { useTheme } from '@astermind/chatbot-template';

function MyComponent() {
  const { theme, cssVariables } = useTheme({
    primaryColor: '#10B981',
    borderRadius: '16px'
  });

  return <div style={cssVariables}>...</div>;
}

useScrollToBottom

Auto-scroll behavior for message lists:

import { useScrollToBottom } from '@astermind/chatbot-template';

function MessageList({ messages }) {
  const { containerRef, scrollToBottom } = useScrollToBottom();

  return (
    <div ref={containerRef}>
      {messages.map(msg => <Message key={msg.id} {...msg} />)}
    </div>
  );
}

Components API

All components are exported for custom compositions:

import {
  ChatbotWidget,    // Main widget (includes bubble + window)
  ChatBubble,       // Floating trigger button
  ChatWindow,       // Chat window container
  ChatHeader,       // Window header with title/subtitle
  ChatInput,        // Message input with send button
  MessageList,      // Scrollable message container
  MessageBubble,    // Individual message bubble
  ActionCard,       // Agentic action confirmation card
  SourceCitation,   // Source reference component
  StatusIndicator,  // Connection status display
  TypingIndicator   // Typing/loading animation
} from '@astermind/chatbot-template';

TypeScript Support

Full TypeScript support with exported types:

import type {
  // Template-specific types
  AsterMindChatbotProps,
  ChatbotTheme,
  ChatMessage,
  AgentAction,
  ChatState,
  WidgetPosition,
  AgentConfig,
  FallbackConfig,
  SiteMapEntry,
  VanillaInitConfig,
  SendOptions,

  // Re-exported from @astermind/cybernetic-chatbot-client
  CyberneticConfig,
  CyberneticResponse,
  CyberneticError,
  Source,
  ConnectionStatus,
  ConfidenceLevel,
  StreamCallbacks,
  AskOptions,
  CachedDocument,
  CacheStatus,
  AgenticConfig
} from '@astermind/chatbot-template';

// CyberneticClient class is also re-exported for advanced usage
import { CyberneticClient } from '@astermind/chatbot-template';

Troubleshooting

Widget not appearing

• Ensure styles are imported: import '@astermind/chatbot-template/styles'
• Check that apiUrl and apiKey are provided
• Verify the widget container has position: relative or is in the document flow

Connection errors

• Check that your apiUrl is correct and accessible
• Verify your API key is valid and has the correct permissions
• Check browser console for CORS errors - ensure your backend allows the origin

Streaming not working

• Verify your backend supports the /api/external/chat/stream endpoint
• Check that SSE is not being blocked by proxies or firewalls
• Ensure Content-Type: text/event-stream header is set on responses

Actions not executing

• Confirm agent.enabled is set to true
• Check that actions meet the confidenceThreshold
• Verify custom action handlers are properly defined

Styles not applying

• Ensure the CSS file is loaded before the JS
• Check for CSS specificity conflicts with your existing styles
• Use !important or increase specificity if needed

White text on white background (Dark Mode / CSS Framework conflicts)

If you're using Tailwind CSS, Bootstrap, or any CSS framework that applies global dark mode styles (e.g. body { color: white } or dark:text-gray-100), those styles can bleed into the chatbot widget through CSS inheritance. This commonly causes the chat input textarea to show white text on a white background.

Fix: Add these overrides in your app's CSS (after importing the chatbot styles):

/* Isolate chatbot widget from host page dark mode */
.astermind-window {
  color: var(--astermind-text, #1f2937);
  background: var(--astermind-background, #ffffff);
}

.astermind-input__textarea {
  color: var(--astermind-text, #1f2937) !important;
  background-color: var(--astermind-background, #ffffff) !important;
}

.astermind-input__textarea::placeholder {
  color: var(--astermind-text-muted, #6b7280) !important;
}

The !important is needed on the textarea because CSS frameworks often set color: inherit on form elements, which inherits from the host page's dark mode text color. The .astermind-window rule establishes the widget's own color context.

If you're using custom theme colors, the CSS variables will be set by the theme prop and the overrides above will automatically use your custom values.

Browser Support

Browser	Version
Chrome	80+
Firefox	75+
Safari	13+
Edge	80+

The standalone bundle includes necessary polyfills for broader compatibility.

Build Outputs

File	Format	Description
astermind-chatbot.esm.js	ESM	ES Module for bundlers (tree-shakeable)
astermind-chatbot.umd.js	UMD	Universal Module Definition
astermind-chatbot.min.js	IIFE	Standalone bundle with React included
astermind-chatbot.css	CSS	Compiled and minified styles

License

MIT License - see LICENSE for details.

Built with care by the AsterMind team.