carmen-chatbot-widget
v1.0.12
Published
AI Chatbot Widget
Readme
🤖 Carmen Chatbot Widget
The official embeddable chatbot widget for Carmen Enterprise System. Easily integrate a smart AI support assistant into any web application with just a few lines of code. Supports multi-tenant knowledge bases, custom LLM models, and rich media rendering.
✨ Features
- ⚡ Framework Agnostic: Works seamlessly with React, Vue, Angular, Next.js, or Vanilla JS.
- 🏢 Multi-Tenant (BU) Support: Separates chat history, logs, and RAG knowledge base by Business Unit (e.g., HR, Account, Sales).
- 🧠 Model Selection: Ability to specify which LLM model to use (e.g., GPT-4o, Claude-3.5) directly from the frontend configuration.
- 💾 Persistent Sessions: Automatically manages user sessions and loads chat history.
- 🎥 Rich Media Support: Renders Markdown formatting and automatically embeds YouTube videos from links.
- 💬 Interactive UI: Includes typing animations, copy-to-clipboard tools, suggested questions, and feedback buttons (👍/👎).
📦 Installation
Install via NPM:
npm install carmen-chatbot-widget
# or
yarn add carmen-chatbot-widget
🚀 Usage
1. Using with React / Next.js
Import and initialize the widget inside a useEffect hook.
import { useEffect } from 'react';
import { CarmenBot } from 'carmen-chatbot-widget';
function App() {
useEffect(() => {
// Initialize the widget
new CarmenBot({
bu: "HR", // (Required) Business Unit ID
user: "John Doe", // (Optional) User Display Name
title: "HR Assistant 👩💼", // (Optional) Widget Header Title
model: "openai/gpt-4o-mini" // (Optional) Specify the AI Model to use
});
}, []);
return (
<div className="App">
<h1>Welcome to Carmen Enterprise</h1>
</div>
);
}
export default App;
2. Using with Vanilla HTML / JavaScript
You can use it directly in a script tag if your project supports ES Modules.
<!DOCTYPE html>
<html lang="en">
<body>
<h1>My Website</h1>
<script type="module">
import { CarmenBot } from './node_modules/carmen-chatbot-widget/src/index.js';
// Or point to your build file / CDN if available
new CarmenBot({
bu: "hotel-seaside",
user: "Guest User",
title: "Hotel Concierge",
model: "anthropic/claude-3-haiku"
});
</script>
</body>
</html>
⚙️ Configuration Options
Pass these options to the new CarmenBot(config) constructor.
⚙️ Configuration Options
Pass these options to the new CarmenBot(config) constructor.
| Parameter | Type | Default | Example | Description |
| :--- | :--- | :--- | :--- | :--- |
| bu | string | "global" | "HR", "Sales", "Hotel-A" | Important: The Business Unit ID. This isolates chat history, token usage logs, and the RAG knowledge base. |
| user | string | "Guest" | "John Doe", "Manager" | The display name of the user shown in the chat interface and recorded in logs (if enabled). |
| model | string | null | "openai/gpt-4o", "anthropic/claude-3-haiku" | (New) Specifies the LLM model ID. If omitted, the system uses the default "Active" model from the database. |
| title | string | "Carmen AI" | "HR Support 👩💼", "Concierge" | Custom title text displayed in the widget's header bar. |
| apiUrl | string | (Production URL) | "http://localhost:8000" | Overrides the backend API URL. Essential for local development or custom deployments. |
| theme | string | null | "dark", "blue" | (Optional) Theme key passed to the backend/frontend for custom styling logic. |
| prompt_extend | string | null | "Answer in Thai only", "Be concise" | (Optional) Additional system instructions injected into the AI context to control behavior. |
🛠️ Development
If you want to modify the source code locally:
- Clone the repository.
- Install dependencies:
npm install
- Link package locally for testing:
# In this package folder
npm link
# In your test project folder
npm link carmen-chatbot-widget