Web Widget
Embed a CognitionDesk AI chat widget into any website or app using the @cognitiondesk/widget package. Authenticate with an API key — no Firebase token required on the client.
Prerequisites
- A CognitionDesk account with at least one AI assistant configured
- An API key — generate one in Settings → API Keys
- A deployed widget — create one in Platforms → Web Widget to get a Widget ID
Installation
Install the package
npm install @cognitiondesk/widgetAdd the component
import { CognitionDeskWidget } from '@cognitiondesk/widget/react';
// Minimal — loads all config from the platform using widgetId
export default function App() {
return (
<>
<YourApp />
<CognitionDeskWidget
apiKey="YOUR_API_KEY"
widgetId="YOUR_WIDGET_ID"
/>
</>
);
}The widget fetches its full configuration from the platform automatically using the widgetId.
Programmatic control (optional)
Pass a ref to call open(), close(), toggle(), and clearHistory() from parent components.
import { useRef } from 'react';
import { CognitionDeskWidget } from '@cognitiondesk/widget/react';
export default function App() {
const widgetRef = useRef(null);
return (
<>
<button onClick={() => widgetRef.current?.open()}>
Open chat
</button>
<CognitionDeskWidget
ref={widgetRef}
apiKey="YOUR_API_KEY"
widgetId="YOUR_WIDGET_ID"
/>
</>
);
}Rate limiting
Control how many messages a single visitor can send — prevents abuse and excessive API usage. Limits are enforced both client-side (instant feedback) and server-side (cannot be bypassed).
When using a widgetId, rate limiting settings are pulled from the platform and take precedence over any props you pass. Configure them in the Web Widget creator under the Rate Limiting section.
| Prop (React) | Default | Description |
|---|---|---|
| maxMessagesPerSession | 0 | Max total messages per visitor session. 0 = unlimited |
| maxMessagesPerMinute | 0 | Max messages per minute per visitor. 0 = unlimited |
| limitReachedMessage | "You've reached the message limit…" | Shown when the session cap is hit |
| rateLimitMessage | "You're sending messages too quickly…" | Shown when the per-minute cap is hit |
<CognitionDeskWidget
apiKey="YOUR_API_KEY"
assistantId="YOUR_ASSISTANT_ID"
maxMessagesPerSession={50}
maxMessagesPerMinute={10}
limitReachedMessage="You've used all your messages for this session."
rateLimitMessage="Slow down — please wait a moment."
/>const widget = new CognitionDeskWidget({
apiKey: 'YOUR_API_KEY',
assistantId: 'YOUR_ASSISTANT_ID',
rateLimiting: {
enabled: true,
maxMessagesPerSession: 50,
maxMessagesPerMinute: 10,
limitReachedMessage: "You've used all your messages for this session.",
rateLimitMessage: "Slow down — please wait a moment.",
},
});Widget methods
Available on the class instance (vanilla JS) or via ref (React).
| Method | Description |
|---|---|
| mount(el?) | Mount to DOM. Pass an element or defaults to document.body. Returns a Promise when widgetId is set. |
| open() | Open the chat panel |
| close() | Close the chat panel |
| toggle() | Toggle open / closed |
| clearHistory() | Reset the conversation history |
| unmount() | Remove from DOM and clean up all listeners |