@mounaji_npm/web-widget
v0.4.25
Published
Embeddable vanilla-JS chat widget with shared UI settings — CognitionDesk / Mounaji
Maintainers
luciloReadme
@mounaji_npm/web-widget
Embeddable vanilla-JS chat widget with Shadow DOM isolation. Works via <script> tag — no framework, no build step required. Also available as an ES module for framework integrations.
Used by the Mounaji/CognitionDesk platform to embed AI chat assistants on any website.
Install
npm install @mounaji_npm/web-widgetOr load via script tag (UMD build):
<script src="https://cdn.example.com/web-widget.umd.js"></script>Quick Start
Script tag (simplest)
<!DOCTYPE html>
<html>
<head><title>My Site</title></head>
<body>
<!-- Your site content -->
<script src="web-widget.umd.js"></script>
<script>
CognitionDesk.init({
apiKey: 'your-api-key',
assistantId: 'asst_xxx',
primaryColor: '#7C3AED',
welcomeMessage: 'Hi! How can I help?',
position: 'bottom-right',
});
</script>
</body>
</html>ES Module
import CognitionDeskWidget from '@mounaji_npm/web-widget';
const widget = new CognitionDeskWidget({
apiKey: 'your-api-key',
assistantId: 'asst_xxx',
primaryColor: '#7C3AED',
});
widget.mount(); // mounts to document.bodyConstructor Options
new CognitionDeskWidget({
// Required
apiKey: 'your-api-key',
// Assistant
assistantId: 'asst_xxx', // assistant ID
widgetId: 'wgt_xxx', // enables remote config fetch from dashboard
// Appearance
primaryColor: '#7C3AED', // main accent color
theme: 'dark', // 'light' | 'dark' | 'auto'
position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
offsetX: 0, // horizontal offset in px from the anchored edge
offsetY: 0, // vertical offset in px from the anchored edge
// Bot identity
botName: 'Aria',
botEmoji: '🤖',
botAvatar: 'https://cdn.example.com/bot.png',
avatarSize: 36, // avatar size in px
avatarCircle: false, // false = rounded-square avatar (remove circular contour)
avatarShowBackground: false, // removes translucent backdrop behind avatar
// Alternative grouped avatar settings (dashboard payload-friendly)
avatar: {
size: 36,
circle: false,
showBackground: false,
},
// UX
welcomeMessage: 'Hi! How can I help you today?',
placeholder: 'Type a message…',
openByDefault: false, // start open
streaming: true, // stream responses (default: true)
showPoweredBy: true, // show "Powered by Mounaji" footer
// File attachments
allowAttachments: false, // enable file upload button
fileUpload: {
allowedTypes: ['pdf', 'image'], // see FILE_TYPE_DESCRIPTORS
maxSizeMb: 10,
},
// Rate limiting (client-side guard)
rateLimiting: {
maxMessages: 50, // per session
maxPerMinute: 10,
},
// Override specific settings while still fetching remote config
overrideSettings: {
botName: 'My Bot', // keys listed here take precedence over dashboard config
},
// Custom backend URL (if self-hosting)
backendUrl: 'https://api.yourapp.com',
})Instance Methods
const widget = new CognitionDeskWidget({ apiKey: '...' });
widget.mount(container?) // Mount to element (default: document.body)
widget.open() // Open chat panel
widget.close() // Close chat panel
widget.toggle() // Toggle open/closed
widget.destroy() // Remove widget from DOM
widget.updateConfig(opts) // Update config at runtime (e.g. change primaryColor)Remote Config (Dashboard Integration)
When widgetId is set, the widget fetches its configuration from the Mounaji dashboard on initialization. This allows non-developers to customize the widget appearance without code changes.
new CognitionDeskWidget({
apiKey: 'your-api-key',
widgetId: 'wgt_xxx', // from the widget creator in the dashboard
});Use overrideSettings to lock specific values from code even when remote config is active:
new CognitionDeskWidget({
apiKey: 'your-api-key',
widgetId: 'wgt_xxx',
overrideSettings: {
assistantId: 'asst_custom', // always use this assistant regardless of dashboard config
primaryColor: '#FF5733', // always use this color
},
});File Attachments
Enable users to upload files during a chat session:
new CognitionDeskWidget({
apiKey: 'your-api-key',
assistantId: 'asst_xxx',
allowAttachments: true,
fileUpload: {
allowedTypes: ['pdf', 'image', 'word'], // see supported types below
maxSizeMb: 20,
},
});Supported file type IDs:
| ID | Formats | Description |
|---|---|---|
| image | JPEG, PNG, GIF, WebP, SVG | Image files |
| pdf | PDF | PDF documents |
| word | DOC, DOCX | Microsoft Word |
| excel | XLS, XLSX, CSV | Spreadsheets |
| powerpoint | PPT, PPTX | Presentations |
| text | TXT, MD, JSON | Plain text and code |
Named Exports (for Dashboard Tooling)
When building a widget configuration UI (e.g. in the Mounaji dashboard), import the schema and helpers:
import {
WIDGET_DEFAULTS, // default config values
WIDGET_SETTINGS_SCHEMA, // field definitions for config UI generation
FILE_TYPE_DESCRIPTORS, // file type metadata (id, label, mimeTypes, icon, color)
buildAcceptString, // (allowedTypeIds) => HTML accept string
isMimeTypeAllowed, // (mimeType, allowedTypeIds) => boolean
getFileTypeDescriptor, // (id) => FILE_TYPE_DESCRIPTORS entry
resolveWidgetConfig, // (rawConfig) => merged config with defaults
mergeServerConfig, // (localConfig, serverConfig, overrides) => final config
} from '@mounaji_npm/web-widget';Generate an <input> accept attribute:
import { buildAcceptString } from '@mounaji_npm/web-widget';
const accept = buildAcceptString(['pdf', 'image']);
// → "application/pdf,image/jpeg,image/png,image/gif,image/webp,image/svg+xml"Validate a file before upload:
import { isMimeTypeAllowed } from '@mounaji_npm/web-widget';
function onFileSelected(file) {
if (!isMimeTypeAllowed(file.type, ['pdf', 'image'])) {
alert('File type not allowed');
return;
}
uploadFile(file);
}React Wrapper Example
Wrap the vanilla widget in a React component for lifecycle management:
import { useEffect, useRef } from 'react';
import CognitionDeskWidget from '@mounaji_npm/web-widget';
export function ChatWidgetEmbed({ apiKey, assistantId, primaryColor }) {
const widgetRef = useRef(null);
useEffect(() => {
const widget = new CognitionDeskWidget({ apiKey, assistantId, primaryColor });
widget.mount();
widgetRef.current = widget;
return () => {
widgetRef.current?.destroy();
widgetRef.current = null;
};
}, [apiKey, assistantId]);
useEffect(() => {
widgetRef.current?.updateConfig({ primaryColor });
}, [primaryColor]);
return null; // widget renders itself outside the React tree
}Shadow DOM Isolation
The widget renders inside a Shadow DOM root, so:
- Its styles never bleed into your page
- Your page styles never bleed into the widget
- It works on any site regardless of CSS frameworks (Tailwind, Bootstrap, etc.)
- No class name conflicts
WordPress / CMS Integration
Paste into your theme's footer or a custom HTML block:
<script src="https://cdn.example.com/web-widget.umd.js"></script>
<script>
document.addEventListener('DOMContentLoaded', function () {
CognitionDesk.init({
apiKey: 'your-api-key',
assistantId: 'asst_xxx',
primaryColor: '#7C3AED',
});
});
</script>