Chat SDK v2

A modern, lightweight chat widget SDK that can be easily integrated into any website.

Features

• 🚀 Easy integration with just a few lines of code
• 🎨 Customizable appearance and positioning
• 👥 User and hospital information management
• 📱 Responsive design
• 🌐 Multi-language support
• 💬 Real-time messaging through iframe communication

Installation

npm install @your-org/chat-sdk-v2

Or include via CDN:

<script src="https://cdn.your-domain.com/chat-sdk-v2.js"></script>

Basic Usage

Initialize with Default Settings

import ChatSDK from "@your-org/chat-sdk-v2";

// Initialize with default settings
ChatSDK.init();

Initialize with Custom Configuration

import ChatSDK from "@your-org/chat-sdk-v2";

ChatSDK.init({
  position: "bottom-right",
  primaryColor: "#3B82F6",
  secondaryColor: "#10B981",
  startOpen: false,
  hospitalInfo: {
    hospitalId: "hospital-123",
    hospitalName: "스마트 병원",
    operatingHours: "09:00-18:00",
  },
  userInfo: {
    userName: "홍길동",
    userPhone: "010-1234-5678",
    userLanguage: "ko",
  },
});

API Methods

Core Methods

init(config?: ChatSDKConfig): boolean

Initialize the chat SDK with optional configuration.

const success = ChatSDK.init({
  position: "bottom-left",
  primaryColor: "#FF6B6B",
  hospitalInfo: {
    hospitalId: "my-hospital",
    hospitalName: "우리 병원",
    operatingHours: "24시간 운영",
  },
});

if (success) {
  console.log("Chat SDK initialized successfully");
}

open(): void

Open the chat widget.

ChatSDK.open();

close(): void

Close the chat widget.

ChatSDK.close();

toggle(): void

Toggle the chat widget open/closed state.

ChatSDK.toggle();

Information Management

setHospitalInfo(hospitalInfo: HospitalInfo): void

Update hospital information dynamically.

ChatSDK.setHospitalInfo({
  hospitalId: "new-hospital-id",
  hospitalName: "새로운 병원명",
  operatingHours: "08:00-20:00",
});

setUserInfo(userInfo: UserInfo): void

Update user information dynamically.

ChatSDK.setUserInfo({
  userName: "김철수",
  userPhone: "010-9876-5432",
  userLanguage: "en",
});

Utility Methods

isOpen(): boolean

Check if the chat widget is currently open.

if (ChatSDK.isOpen()) {
  console.log("Chat is currently open");
}

getConfig(): ChatSDKConfig | null

Get the current configuration.

const currentConfig = ChatSDK.getConfig();
console.log("Current config:", currentConfig);

updateConfig(newConfig: Partial<ChatSDKConfig>): void

Update configuration partially.

ChatSDK.updateConfig({
  primaryColor: "#FF5722",
  position: "top-right",
});

destroy(): void

Completely remove the chat widget from the page.

ChatSDK.destroy();

Configuration Options

ChatSDKConfig Interface

interface ChatSDKConfig {
  position?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
  primaryColor?: string;
  secondaryColor?: string;
  startOpen?: boolean;
  customStyles?: Record<string, Record<string, string>>;
  hospitalInfo?: HospitalInfo;
  userInfo?: UserInfo;
}

interface HospitalInfo {
  hospitalId: string;
  hospitalName: string;
  operatingHours: string;
}

interface UserInfo {
  userName?: string;
  userPhone?: string;
  userLanguage?: string;
}

Advanced Usage

Custom Styling

ChatSDK.init({
  customStyles: {
    ".chat-widget-container": {
      "border-radius": "20px",
      "box-shadow": "0 10px 30px rgba(0,0,0,0.3)",
    },
    ".chat-toggle-button": {
      background: "linear-gradient(45deg, #FF6B6B, #4ECDC4)",
    },
  },
});

Event Listening

The SDK dispatches custom events that you can listen to:

// Listen for when the chat opens
window.addEventListener("chatSDKOpened", (event) => {
  console.log("Chat opened with config:", event.detail.config);
});

// Listen for when the chat closes
window.addEventListener("chatSDKClosed", (event) => {
  console.log("Chat closed");
});

// Listen for when the iframe is loaded
window.addEventListener("chatSDKIframeLoaded", (event) => {
  console.log("Chat iframe loaded");
});

// Listen for when the SDK is destroyed
window.addEventListener("chatSDKDestroyed", (event) => {
  console.log("Chat SDK destroyed");
});

Dynamic User Management

// Example: Update user info after login
function handleUserLogin(userData) {
  ChatSDK.setUserInfo({
    userName: userData.name,
    userPhone: userData.phone,
    userLanguage: userData.preferredLanguage || "ko",
  });

  // Open chat after login
  ChatSDK.open();
}

// Example: Update hospital context
function switchHospital(hospitalData) {
  ChatSDK.setHospitalInfo({
    hospitalId: hospitalData.id,
    hospitalName: hospitalData.name,
    operatingHours: hospitalData.hours,
  });
}

Browser Support

• Chrome 70+
• Firefox 65+
• Safari 12+
• Edge 79+

Communication Protocol

The SDK communicates with the iframe using postMessage API. The following message types are supported:

Incoming Messages (Iframe → SDK)

// Iframe ready signal (required)
{
  type: "iframe_ready";
}

// Unread message count
{
  unreadMessagesTotalCount: number;
}

Outgoing Messages (SDK → Iframe)

// Hospital information (sent after iframe_ready)
{
  hospitalInfo: {
    hospitalId: string,
    hospitalName: string,
    operatingHours: string
  }
}

// User information (sent after iframe_ready)
{
  userInfo: {
    userName?: string,
    userPhone?: string,
    userLanguage?: string
  }
}

Implementation Notes

1. Initialization Flow:
   • SDK loads iframe
   • Iframe sends { type: "iframe_ready" } when fully loaded
   • SDK responds by sending hospital and user information
2. Dynamic Updates:
   • setHospitalInfo() and setUserInfo() send messages immediately
   • No need to wait for ready signal on subsequent updates

Troubleshooting

Common Issues

1. SDK not initializing: Make sure you're calling init() after the DOM is loaded.
2. Messages not being sent: Check if the iframe has fully loaded before sending messages.
3. Styling conflicts: Use the customStyles option to override default styles.

Debug Mode

// Enable debug logging
window.ChatSDKDebug = true;
ChatSDK.init();

Version

Current version: 2.0.0

License

MIT License