A beautiful React chatbot widget with single-file bundle
npm install @developer.notchatbot/webchathtml
`
$3
The chatbot button will appear in the bottom-right corner of your page. CSS is automatically injected!
⚙️ Configuration Options
`typescript
interface WebChatConfig {
title?: string; // Chat window title
placeholder?: string; // Input placeholder text
primaryColor?: string; // Primary theme color
apiKey?: string; // Your chatbot UID (required for API)
position?: 'bottom-right' | 'bottom-left'; // Widget position
initialMessage?: string; // Custom initial bot message
closeButtonIcon?: 'default' | 'text' | 'custom'; // Close button type
closeButtonText?: string; // Text for close button (when type is 'text')
closeButtonCustomIcon?: string; // Custom icon SVG or URL (when type is 'custom')
marginBottom?: number; // Distance from bottom edge in pixels (default: 16)
marginSide?: number; // Distance from left/right edge in pixels (default: 16)
mobile?: WebChatPositionConfig; // Mobile-specific position settings
desktop?: WebChatPositionConfig; // Desktop-specific position settings
}
interface WebChatPositionConfig {
position?: 'bottom-right' | 'bottom-left';
marginBottom?: number;
marginSide?: number;
}
`
Example:
`js
WebChat.initialize({
title: "Chat Assistant",
placeholder: "Type your message...",
primaryColor: "#007bff",
apiKey: "your-chatbot-uid", // Chatbot UID from admin panel
position: "bottom-right",
initialMessage: "Hi! 👋 I'm your virtual assistant. How can I help you today?",
closeButtonIcon: "default", // or "text" or "custom"
marginBottom: 20, // Distance from bottom edge (default: 16px)
marginSide: 20, // Distance from side edge (default: 16px)
// Device-specific overrides
mobile: {
position: "bottom-left",
marginBottom: 80,
marginSide: 15
},
desktop: {
position: "bottom-right",
marginBottom: 30,
marginSide: 30
}
});
`
💬 EmbedChat - Embedded Chat
EmbedChat allows you to integrate a complete chat system directly into any element of your web page, with full control over size, position, and style.
📦 Installation and Basic Usage
$3
`html
`
$3
`javascript
import { EmbedChatAPI } from './webchat';
const chatInstance = EmbedChatAPI.initialize({
elementId: "my-chat-embed",
apiKey: "your-api-key",
title: "Chat Assistant",
width: 400,
height: 500
});
`
⚙️ Complete Configuration
$3
`javascript
EmbedChatAPI.initialize({
// REQUIRED
elementId: "my-chat-embed", // ID of the HTML element to embed the chat
apiKey: "your-api-key", // API key of the service
})
`
$3
`javascript
EmbedChatAPI.initialize({
// Texts and content
title: "Chat Assistant", // Title shown in the header
placeholder: "Type your message...", // Input placeholder text
initialMessage: "Hello! 👋 I'm your chat assistant. How can I help you today?", // First message from the bot
footerText: "Powered by NotChatBot", // Footer text (optional)
avatar: "https://example.com/avatar.jpg", // Bot avatar URL
})
`
$3
`javascript
EmbedChatAPI.initialize({
// Main dimensions
width: 400, // Width: number (px) or string ("100%", "50vw")
height: 500, // Height: number (px) or string ("100%", "80vh")
// Size limits
maxWidth: 600, // Maximum width
maxHeight: "90vh", // Maximum height (accepts CSS units)
minWidth: 280, // Minimum width (default: 280px)
minHeight: 300, // Minimum height (default: 300px)
})
`
$3
`javascript
EmbedChatAPI.initialize({
// Colors
primaryColor: "#3b82f6", // Primary color (header, buttons, etc.)
textColor: "#333333", // Message text color
bubbleUserColor: "#3b82f6", // User message bubble background
chatBackground: "#ffffff", // Chat background color
footerColor: "#f3f4f6", // Footer background color
// Borders
borderRadius: 12, // Border radius: number (px) or string
border: "2px solid #3b82f6", // Custom border (CSS border)
boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
chatTransparent: false, // If true, chat background is transparent
})
`
$3
`javascript
EmbedChatAPI.initialize({
showHeader: true, // Show/hide header (default: true)
showFooter: true, // Show/hide footer (default: true if footerText is provided)
})
`
$3
`javascript
EmbedChatAPI.initialize({
input: {
backgroundColor: "#ffffff", // Input area background color
inputBorder: "2px solid #e5e7eb", // Input field border
inputBorderRadius: "8px", // Input border radius
iconColor: "#3b82f6" // Send icon color
}
})
`
$3
`javascript
EmbedChatAPI.initialize({
customCSS:
})
`
$3
`javascript
EmbedChatAPI.initialize({
elementId: "mi-chat",
// Main sizes
width: 400, // Number (px) or string ("100%", "50vw")
height: 500, // Number (px) or string ("100%", "80vh")
// Size limits
maxWidth: 600, // Maximum size
maxHeight: "90vh", // Can use CSS units
minWidth: 280, // Minimum size
minHeight: 300,
// More
width: "100%", // Occupies the entire width of the container
height: "50vh", // 50% of the window height
maxWidth: "500px", // Maximum 500px
})
`
$3
`javascript
EmbedChatAPI.initialize({
elementId: "mi-chat",
// Borders and effects
borderRadius: 12, // Border radius in px
border: "2px solid #3b82f6", // Custom border
boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
// Section control
showHeader: true, // Show/hide header (default: true)
showFooter: true, // Show/hide footer (default: true if footerText is provided)
// 🆕 Custom CSS
customCSS:
})
`
📋 Complete Property Reference
$3
| Property | Type | Required | Default | Description |
|-----------|------|-----------|---------|-------------|
| elementId | string | ✅ | - | ID of the HTML element where the chat will be mounted |
| apiKey | string | ✅ | - | API key for the chat service |
| title | string | ❌ | "Chat" | Title shown in the chat header |
| placeholder | string | ❌ | "Type your message..." | Input field placeholder text |
| primaryColor | string | ❌ | "#3b82f6" | Primary color (header, buttons, links) |
| avatar | string | ❌ | - | Bot avatar URL (optional) |
| initialMessage | string | ❌ | - | First message shown by the bot |
| footerText | string | ❌ | - | Footer text (if provided, it is shown) |
| width | string \| number | ❌ | "100%" | Chat width (px or CSS units) |
| height | string \| number | ❌ | 400 | Chat height (px or CSS units) |
| maxWidth | string \| number | ❌ | "100%" | Maximum chat width |
| maxHeight | string \| number | ❌ | "100vh" | Maximum chat height |
| minWidth | string \| number | ❌ | 280 | Minimum chat width |
| minHeight | string \| number | ❌ | 300 | Minimum chat height |
| showHeader | boolean | ❌ | true | Show/hide the header |
| showFooter | boolean | ❌ | true | Show/hide the footer (if footerText is provided) |
| borderRadius | string \| number | ❌ | 12 | Container border radius |
| border | string | ❌ | "1px solid #e5e7eb" | Container border (CSS border) |
| boxShadow | string | ❌ | "0 10px 25px..." | Container shadow |
| chatTransparent | boolean | ❌ | false | If true, chat background is transparent |
| chatBackground | string | ❌ | "#ffffff" | Chat background color |
| textColor | string | ❌ | - | Message text color |
| bubbleUserColor | string | ❌ | - | User message bubble background color |
| footerColor | string | ❌ | - | Footer background color |
| input | EmbedChatInputConfig | ❌ | - | Input-specific configuration |
| customCSS | string | ❌ | - | Custom CSS for the chat |
---
🛠️ Dynamic Control via API and Events
WebChat exposes a global API and custom events to dynamically control the position, padding, and visibility of the widget from anywhere in your app or from the browser console.
$3
`js
window.openWebChat(); // Open the floating chat
window.closeWebChat(); // Close the floating chat
window.toggleWebChat(); // Toggle open/close
window.unmountWebChat(); // Unmount the floating chat
window.mountWebChat(); // Mount the floating chat if it was unmounted
window.hideWebChat(); // Hide the chat (display: none)
window.showWebChat(); // Show the chat if it was hidden
window.injectWebChatCSS(css); // Inject custom CSS into the shadow DOM
window.removeWebChatCSS(); // Remove custom CSS
window.setWebChatPosition(obj); // Change position/padding dynamically
`
$3
`js
window.unmountEmbedChat(elementId); // Unmount the EmbedChat instance for the given elementId
window.mountEmbedChat(elementId); // Mount the EmbedChat instance again (with the last used config)
`
- window.unmountEmbedChat(elementId): Unmounts the EmbedChat instance from the specified element. The last configuration is saved.
- window.mountEmbedChat(elementId): Remounts the EmbedChat instance in the specified element using the last configuration used for that element. If no config was previously used, a warning is shown in the console.
#### Example
`js
window.unmountEmbedChat('embed-small'); // Unmounts the chat from the element with id 'embed-small'
window.mountEmbedChat('embed-small'); // Remounts the chat in the same element with the last config
`
---
$3
We emit custom browser events so you can capture interactions and feed them into Google Tag Manager, Google Analytics, Meta Pixel, or any other analytics tool.
| Widget | Event name | Fired when | detail payload |
|--------|------------|------------|------------------|
| WebChat | notchatbot-webchat-open | The floating chat is opened | { conversationId } |
| WebChat | notchatbot-webchat-closed | The floating chat is closed | { conversationId } |
| WebChat | notchatbot-webchat-message-sent | The user sends one or more messages | { messages: Message[] } |
| WebChat | notchatbot-webchat-message-received | A message is received from the server | { message: Message, role: 'assistant' \| 'employee' } |
| EmbedChat | notchatbot-embedchat-message-sent | The user sends a message | { message: Message } |
| EmbedChat | notchatbot-embedchat-message-received | A message is received | { message: Message, role: 'assistant' \| 'employee' } |
Message follows the same interface used internally by the widget (id, text, sender, timestamp, etc.).
#### Quick example
`js
window.addEventListener('notchatbot-webchat-open', e => console.log('WebChat opened', e.detail));
window.addEventListener('notchatbot-webchat-closed', e => console.log('WebChat closed', e.detail));
window.addEventListener('notchatbot-webchat-message-sent', e => console.log('Sent', e.detail.messages));
window.addEventListener('notchatbot-webchat-message-received', e => {
const { role, message } = e.detail;
console.log('Received', role, message);
});
`
#### Google Tag Manager / Google Analytics (GA4)
Push data directly to the dataLayer and create a trigger in GTM:
`js
window.addEventListener('notchatbot-webchat-message-sent', e => {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: 'webchat_message_sent',
messages: e.detail.messages,
conversationId: e.detail.messages[0]?.conversationId || null
});
});
`
Then in GTM, add a Custom Event trigger called webchat_message_sent and link it to a GA4 event tag.
#### Meta / Facebook Pixel
`js
window.addEventListener('notchatbot-webchat-open', () => {
if (window.fbq) {
fbq('trackCustom', 'WebChatOpened');
}
});
window.addEventListener('notchatbot-webchat-message-received', e => {
if (window.fbq) {
fbq('trackCustom', 'WebChatMessageReceived', {
role: e.detail.role
});
}
});
`
These events make it easy to measure engagement and conversions driven by the chat widget without modifying its source code.
$3
#### 1. Change position and margin globally (flat)
`js
window.setWebChatPosition({
position: 'bottom-left',
marginBottom: 40,
marginSide: 30
});
`
#### 2. Change only for mobile
`js
window.setWebChatPosition({
mobile: {
position: 'bottom-right',
marginBottom: 100,
marginSide: 20
}
});
`
#### 3. Change only for desktop
`js
window.setWebChatPosition({
desktop: {
position: 'bottom-left',
marginBottom: 60,
marginSide: 40
}
});
`
#### 4. Change using device format
`js
window.setWebChatPosition({
device: 'mobile',
marginBottom: 120,
marginSide: 15
});
`
$3
You can dispatch events to change padding/margin or open/close the chat from anywhere in your app:
#### 1. Open, close, or toggle the floating WebChat
`js
window.dispatchEvent(new CustomEvent('openWebChatbot'));
window.dispatchEvent(new CustomEvent('closeWebChatbot'));
window.dispatchEvent(new CustomEvent('toggleWebChatbot'));
`
#### 2. Change padding for both devices (flat)
`js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { y: 100, x: 30 } }));
`
#### 3. Change only for mobile
`js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'mobile', marginBottom: 120, marginSide: 20 } }));
`
#### 4. Change only for desktop
`js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'desktop', marginBottom: 60, marginSide: 40 } }));
`
#### 5. Change using nested object
`js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: {
mobile: { marginBottom: 90, marginSide: 10 },
desktop: { marginBottom: 50, marginSide: 30 }
}}));
`
$3
- Flat: { marginBottom, marginSide, position } (applies to both if no override in mobile/desktop)
- By device: { device: 'mobile'|'desktop', marginBottom, marginSide }
- Nested: { mobile: { ... }, desktop: { ... } }
- Alias: { y, x } (y → marginBottom, x → marginSide)
You can combine these formats as needed.
$3
You can inject hot CSS into the floating WebChat using the global API:
`js
// Change the header background color
window.injectWebChatCSS(
);
// Hide the floating button
window.injectWebChatCSS(#notchatbot-webchat-button { display: none !important; });
// Change the chat window width
window.injectWebChatCSS(#notchatbot-webchat-window { width: 500px !important; });
// Change the floating button color
window.injectWebChatCSS(#notchatbot-webchat-button { background: #f59e0b !important; });
// Remove all custom styles
window.removeWebChatCSS();
`
#### Internal element IDs for WebChat
You can use these IDs to select and style specific parts of the widget:
- #notchatbot-webchat-button — Floating chat button
- #notchatbot-webchat-header — Chat window header
- #notchatbot-webchat-window — Main chat window
Example to change the header and button color:
`js
window.injectWebChatCSS(
);
``