Chat SDK v2

A lightweight, iframe-based chat widget SDK built with vanilla JavaScript. This SDK allows you to easily integrate a chat widget into any website without dependencies on React or other frameworks.

Features

• 🚀 Zero Dependencies: Pure JavaScript, no React or other framework dependencies
• 📱 Responsive Design: Works seamlessly on desktop and mobile devices
• 🎨 Customizable: Configurable colors, positions, sizes, and styles
• 🔒 Secure: Uses iframe sandboxing for security
• 📦 Lightweight: Minimal bundle size
• 🎯 Shadow DOM: Prevents style conflicts with host website
• 📡 Message Passing: Built-in communication with iframe content
• 🎛️ Event System: Listen to widget events and iframe messages

Installation

NPM/Yarn

npm install chat-sdk-v2
# or
yarn add chat-sdk-v2

CDN

<script src="https://unpkg.com/chat-sdk-v2@latest/dist/chat-sdk-v2.umd.js"></script>

Quick Start

ES Modules

import { initChatSDK } from "chat-sdk-v2";

const chatWidget = initChatSDK({
  iframeUrl: "https://your-chat-app.com",
  position: "bottom-right",
  primaryColor: "#3B82F6",
});

UMD (Script Tag)

<script src="https://unpkg.com/chat-sdk-v2@latest/dist/chat-sdk-v2.umd.js"></script>
<script>
  const chatWidget = window.ChatSDK.init({
    iframeUrl: "https://your-chat-app.com",
    position: "bottom-right",
    primaryColor: "#3B82F6",
  });
</script>

CommonJS

const { initChatSDK } = require("chat-sdk-v2");

const chatWidget = initChatSDK({
  iframeUrl: "https://your-chat-app.com",
});

Configuration Options

const config = {
  iframeUrl: "https://your-chat-app.com", // Required: URL to load in iframe
  position: "bottom-right", // Position: 'bottom-right', 'bottom-left', 'top-right', 'top-left'
  primaryColor: "#3B82F6", // Primary color (chat button background)
  secondaryColor: "#10B981", // Secondary color (for custom styling)
  width: 400, // Widget width in pixels
  height: 600, // Widget height in pixels
  startOpen: false, // Whether to start with chat open
  customStyles: {
    // Custom CSS styles
    ".chat-widget-container": {
      "border-radius": "16px",
      "box-shadow": "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
    },
  },
};

const chatWidget = initChatSDK(config);

API Methods

// Open the chat widget
chatWidget.open();

// Close the chat widget
chatWidget.close();

// Toggle the chat widget
chatWidget.toggle();

// Check if chat is open
const isOpen = chatWidget.isOpen();

// Change iframe URL
chatWidget.setUrl("https://new-chat-url.com");

// Send message to iframe
chatWidget.postMessage({ type: "greeting", data: "Hello!" });

// Listen to messages from iframe
const unsubscribe = chatWidget.onMessage((message) => {
  console.log("Received from iframe:", message);
});

// Update configuration
chatWidget.updateConfig({
  primaryColor: "#FF6B6B",
  secondaryColor: "#4ECDC4",
});

// Get current configuration
const currentConfig = chatWidget.getConfig();

// Destroy the widget
chatWidget.destroy();

Event Handling

Listen to chat widget events:

// Chat opened event
window.addEventListener("chatSDKOpened", (event) => {
  console.log("Chat widget opened", event.detail);
});

// Chat closed event
window.addEventListener("chatSDKClosed", (event) => {
  console.log("Chat widget closed", event.detail);
});

// Iframe loaded event
window.addEventListener("chatSDKIframeLoaded", (event) => {
  console.log("Iframe loaded successfully", event.detail);
});

// Chat destroyed event
window.addEventListener("chatSDKDestroyed", (event) => {
  console.log("Chat widget destroyed", event.detail);
});

Message Communication

Sending Messages to Iframe

// Send structured data
chatWidget.postMessage({
  type: "user_info",
  data: {
    userId: "12345",
    name: "John Doe",
    email: "[email protected]",
  },
});

// Send simple message
chatWidget.postMessage("Hello from parent window!");

Receiving Messages from Iframe

const unsubscribe = chatWidget.onMessage((message) => {
  if (message.type === "chat_ready") {
    console.log("Chat is ready to receive messages");
  } else if (message.type === "new_message") {
    console.log("New chat message:", message.data);
  }
});

// Unsubscribe when no longer needed
unsubscribe();

Styling and Customization

Custom Colors

const chatWidget = initChatSDK({
  iframeUrl: "https://your-chat-app.com",
  primaryColor: "#FF6B6B", // Chat button color
  secondaryColor: "#4ECDC4", // Available for custom styling
});

Custom CSS Styles

const chatWidget = initChatSDK({
  iframeUrl: "https://your-chat-app.com",
  customStyles: {
    ".chat-widget-container": {
      "border-radius": "20px",
      "box-shadow": "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
      border: "2px solid #e2e8f0",
    },
    ".chat-toggle-button": {
      width: "70px",
      height: "70px",
    },
  },
});

Positioning

Choose from four predefined positions:

• bottom-right (default)
• bottom-left
• top-right
• top-left

Development

Setup

# Clone the repository
git clone <repository-url>
cd chat-sdk-v2

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Demo

Run npm run dev and visit http://localhost:5173 to see the interactive demo.

Browser Support

• Chrome/Edge 88+
• Firefox 78+
• Safari 14+
• Modern mobile browsers

Security

The iframe is sandboxed with the following permissions:

• allow-same-origin: Allows iframe to access same origin
• allow-scripts: Allows JavaScript execution
• allow-forms: Allows form submission
• allow-popups: Allows popups (for OAuth, etc.)
• allow-popups-to-escape-sandbox: Allows popups to escape sandbox

License

MIT License - see LICENSE file for details.