@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.

$3

``
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)

$3

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

| Configuration Method | Where to Set |
|---------------------|--------------|
| React Props | In your component: |
| 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

$3

- 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

$3

- 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

$3

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

$3

`bash
npm install @astermind/chatbot-template
`

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

$3

`html


`

---

Quick Start

$3

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

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

$3

`html










`

---

Configuration in Your Application

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

$3

Option 1: Pass props directly
`tsx
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:

`env


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:
`tsx

`

$3

Option 1: Pass config to init()
`javascript
AsterMindChatbot.init({
apiKey: 'am_your_api_key',
apiUrl: 'https://api.astermind.ai',
position: 'bottom-right'
});
`

Option 2: Global config object
`html



`

Option 3: Script data attributes
`html
src="astermind-chatbot.min.js"
data-astermind-key="am_your_api_key"
data-astermind-url="https://api.astermind.ai"
>
`

$3

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

`html

`

---

Configuration Reference

$3

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

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

$3

| 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. |

$3

| 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 |

$3

Customize appearance via the theme object:

`javascript
{
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)'
}
}
`

$3

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

`javascript
{
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();
}
}
}
}
`

$3

Configure offline behavior:

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

$3

| 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

$3

Override CSS variables in your stylesheet for quick customization:

`css
: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;
}
`

$3

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

$3

Direct API client access for custom implementations:

`tsx
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);
};
}
`

$3

Chat state management:

`tsx
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();
}
`

$3

Theme customization hook:

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

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

return

;
}
`

$3

Auto-scroll behavior for message lists:

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

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

return (



);
}
`

---

Components API

All components are exported for custom compositions:

`tsx
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:

`typescript
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

$3

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

$3

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

$3

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

$3

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

$3

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

---

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.