API Reference

The ChatCops singleton is exposed on window.ChatCops when using the IIFE bundle, or importable from the ESM bundle.

Methods

ChatCops.init(config)

Initialize the widget with a configuration object. Must be called before any other method if not using script tag auto-init.

// Popup mode (default)
ChatCops.init({
  apiUrl: 'https://your-api.com/chat',
  theme: { accent: '#6366f1' },
  branding: { name: 'My Bot' },
  welcomeMessage: 'Hello! How can I help?',
});

// Inline mode
ChatCops.init({
  apiUrl: 'https://your-api.com/chat',
  mode: 'inline',
  container: '#chat-container',
  branding: { name: 'My Bot' },
});

Calling init() again will destroy the previous instance and create a new one.

ChatCops.open()

Programmatically open the chat panel.

• Popup mode: Shows the panel and updates the FAB icon.
• Inline mode: Shows the panel (useful if you’ve previously called close()).

document.querySelector('#help-btn').addEventListener('click', () => {
  ChatCops.open();
});

ChatCops.close()

Close the chat panel.

• Popup mode: Hides the panel and resets the FAB icon.
• Inline mode: Hides the panel. Call open() to show it again.

ChatCops.close();

ChatCops.destroy()

Completely remove the widget from the DOM and clean up all event listeners.

• Popup mode: Removes FAB, panel, and welcome bubble from the page.
• Inline mode: Removes the widget from the container element.

ChatCops.destroy();

ChatCops.on(event, callback)

Subscribe to widget events.

ChatCops.on('message', (data) => {
  console.log('New message:', data);
});

ChatCops.off(event, callback)

Remove a specific event listener.

function onOpen() {
  console.log('Widget opened');
}

ChatCops.on('open', onOpen);
ChatCops.off('open', onOpen);

Auto-Initialization

When using the CDN script tag, the widget auto-initializes by reading data-* attributes:

Popup (default)

<script
  src="https://cdn.jsdelivr.net/npm/@chatcops/widget/dist/chatcops.min.js"
  data-api-url="https://your-api.com/chat"
  data-accent="#6366f1"
></script>

Inline

<div id="my-chat" style="width: 400px; height: 500px;"></div>
<script
  src="https://cdn.jsdelivr.net/npm/@chatcops/widget/dist/chatcops.min.js"
  data-api-url="https://your-api.com/chat"
  data-mode="inline"
  data-container="#my-chat"
></script>

The script tag approach is equivalent to calling ChatCops.init() with the corresponding config. You can still use the programmatic API after auto-init (e.g., ChatCops.open()).

ESM Usage

import ChatCops from '@chatcops/widget';

// Popup
ChatCops.init({ apiUrl: '/api/chat' });

// Inline with element reference
const el = document.getElementById('chat');
ChatCops.init({
  apiUrl: '/api/chat',
  mode: 'inline',
  container: el,
});

// Use methods as needed
ChatCops.on('message', (msg) => console.log(msg));

React / Framework Usage

For inline mode in React or other frameworks, pass the container element directly:

import { useEffect, useRef } from 'react';
import ChatCops from '@chatcops/widget';

function Chat() {
  const ref = useRef(null);

  useEffect(() => {
    if (!ref.current) return;
    ChatCops.init({
      apiUrl: '/api/chat',
      mode: 'inline',
      container: ref.current,
    });
    return () => ChatCops.destroy();
  }, []);

  return <div ref={ref} style={{ width: 400, height: 500 }} />;
}