@developer.notchatbot/webchat
Version:
A beautiful React chatbot widget with single-file bundle
509 lines (422 loc) • 17.9 kB
Markdown
```html
<div id="webchat-component"></div>
<script src="https://your-cdn.com/webchat-bundle.min.umd.cjs"></script>
<script>
WebChat.initialize({
title: "Customer Support",
placeholder: "Ask us anything...",
primaryColor: "#667eea"
});
</script>
```
The chatbot button will appear in the bottom-right corner of your page. CSS is automatically injected!
```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 allows you to integrate a complete chat system directly into any element of your web page, with full control over size, position, and style.
```html
<!-- Element to embed the chat -->
<div id="my-chat-embed"></div>
<!-- Load the script -->
<script src="path/to/webchat.js"></script>
<script>
EmbedChat.initialize({
elementId: "my-chat-embed",
apiKey: "your-api-key",
title: "Chat Assistant",
width: 400,
height: 500
});
</script>
```
```javascript
import { EmbedChatAPI } from './webchat';
const chatInstance = EmbedChatAPI.initialize({
elementId: "my-chat-embed",
apiKey: "your-api-key",
title: "Chat Assistant",
width: 400,
height: 500
});
```
```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
})
```
```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
})
```
```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)
})
```
```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
})
```
```javascript
EmbedChatAPI.initialize({
showHeader: true, // Show/hide header (default: true)
showFooter: true, // Show/hide footer (default: true if footerText is provided)
})
```
```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
}
})
```
```javascript
EmbedChatAPI.initialize({
customCSS: `
/* Your custom styles here */
background: linear-gradient(135deg,
}
`
})
```
```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
})
```
```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: `
background: linear-gradient(135deg,
border-radius: 20px !important;
}
`
})
```
| 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.
### WebChat Global Methods
```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
```
```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.
```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
```
---
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);
});
```
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.
```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.
```js
window.setWebChatPosition({
position: 'bottom-left',
marginBottom: 40,
marginSide: 30
});
```
```js
window.setWebChatPosition({
mobile: {
position: 'bottom-right',
marginBottom: 100,
marginSide: 20
}
});
```
```js
window.setWebChatPosition({
desktop: {
position: 'bottom-left',
marginBottom: 60,
marginSide: 40
}
});
```
```js
window.setWebChatPosition({
device: 'mobile',
marginBottom: 120,
marginSide: 15
});
```
You can dispatch events to change padding/margin or open/close the chat from anywhere in your app:
```js
window.dispatchEvent(new CustomEvent('openWebChatbot'));
window.dispatchEvent(new CustomEvent('closeWebChatbot'));
window.dispatchEvent(new CustomEvent('toggleWebChatbot'));
```
```js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { y: 100, x: 30 } }));
```
```js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'mobile', marginBottom: 120, marginSide: 20 } }));
```
```js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'desktop', marginBottom: 60, marginSide: 40 } }));
```
```js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: {
mobile: { marginBottom: 90, marginSide: 10 },
desktop: { marginBottom: 50, marginSide: 30 }
}}));
```
- **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.
You can inject hot CSS into the floating WebChat using the global API:
```js
// Change the header background color
window.injectWebChatCSS(`
background:
color:
}
`);
// Hide the floating button
window.injectWebChatCSS(`
// Change the chat window width
window.injectWebChatCSS(`
// Change the floating button color
window.injectWebChatCSS(`
// Remove all custom styles
window.removeWebChatCSS();
```
You can use these IDs to select and style specific parts of the widget:
- `
- `
- `
Example to change the header and button color:
```js
window.injectWebChatCSS(`
`);
```
You can combine these selectors to fully customize the widget.
---