Platform

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

Shell

npm install @cognitiondesk/widget

Add the component

App.jsx

JavaScript

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.

App.jsx

JavaScript

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

React

JavaScript

<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."
/>

Vanilla JS

JavaScript

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

API Keys

Generate and manage API keys for widget auth.

AI Assistants

Configure the assistant the widget talks to.

Chat API

Build a custom UI instead of using the widget.

Authentication

Full auth options — Firebase tokens and API keys.