@ihoomanai/chat-widget

Universal chat support widget for any website. Uses secure Widget ID based initialization - no API keys exposed in client code.

Installation

npm install @ihoomanai/chat-widget
# or
yarn add @ihoomanai/chat-widget
# or
pnpm add @ihoomanai/chat-widget

Quick Start

ES Modules

import { IhoomanChat } from '@ihoomanai/chat-widget';

IhoomanChat.init({
  widgetId: 'wgt_your_widget_id', // Get this from your Ihooman dashboard
});

CommonJS

const { IhoomanChat } = require('@ihoomanai/chat-widget');

IhoomanChat.init({
  widgetId: 'wgt_your_widget_id',
});

CDN / Script Tag

<script src="https://cdn.ihooman.ai/widget/latest/chat.min.js"></script>
<script>
  IhoomanChat.init({
    widgetId: 'wgt_your_widget_id',
  });
</script>

Or with auto-initialization:

<script 
  src="https://cdn.ihooman.ai/widget/latest/chat.min.js"
  data-widget-id="wgt_your_widget_id"
></script>

Configuration Options

IhoomanChat.init({
  // Required
  widgetId: 'wgt_your_widget_id',
  
  // Optional
  serverUrl: 'https://api.ihooman.ai', // Custom server URL
  theme: 'light', // 'light' | 'dark'
  position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  title: 'Chat Support',
  subtitle: 'We typically reply within minutes',
  welcomeMessage: 'Hi there! 👋 How can we help you today?',
  placeholder: 'Type a message...',
  primaryColor: '#00aeff',
  gradientFrom: '#00aeff',
  gradientTo: '#0066ff',
  startOpen: false,
  persistSession: true,
  showTimestamps: true,
  showTypingIndicator: true,
  enableSounds: true,
  enableFileUpload: true,
  poweredBy: true,
  
  // Callbacks
  onReady: () => console.log('Widget ready'),
  onOpen: () => console.log('Widget opened'),
  onClose: () => console.log('Widget closed'),
  onMessage: (message) => console.log('Message:', message),
  onError: (error) => console.error('Error:', error),
});

API Methods

IhoomanChat.init(config)

Initialize the widget with configuration options. Returns a Promise that resolves when the widget is ready.

IhoomanChat.open()

Open the chat widget window.

IhoomanChat.close()

Close the chat widget window.

IhoomanChat.toggle()

Toggle the chat widget window open/closed.

IhoomanChat.destroy()

Destroy the widget and clean up all resources.

IhoomanChat.sendMessage(content)

Send a message programmatically.

IhoomanChat.sendMessage('Hello, I need help!');

IhoomanChat.setUser(user)

Set user information for personalization.

IhoomanChat.setUser({
  name: 'John Doe',
  email: '[email protected]',
  metadata: {
    plan: 'premium',
  },
});

IhoomanChat.clearHistory()

Clear chat history and start a new conversation.

IhoomanChat.on(event, callback)

Subscribe to widget events.

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

IhoomanChat.off(event, callback)

Unsubscribe from widget events.

IhoomanChat.getState()

Get the current widget state.

const state = IhoomanChat.getState();
console.log('Is open:', state.isOpen);
console.log('Messages:', state.messages);

Events

• ready - Widget is initialized and ready
• open - Widget window opened
• close - Widget window closed
• message - Message sent or received
• connected - WebSocket connected
• disconnected - WebSocket disconnected
• error - An error occurred

TypeScript Support

This package includes TypeScript type definitions. All types are exported:

import type {
  WidgetConfig,
  WidgetState,
  UserInfo,
  Message,
  WidgetEvent,
} from '@ihoomanai/chat-widget';

Security

This widget uses Widget ID based initialization, which means:

• ✅ No API keys are exposed in client-side code
• ✅ Domain validation ensures the widget only works on authorized domains
• ✅ All sensitive operations happen server-side
• ✅ Real-time WebSocket communication with automatic reconnection

Get your Widget ID from the Ihooman Dashboard.

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT © Ihooman AI