@skywu/virtual-chat-sdk

JavaScript/TypeScript SDK for embedding a virtual chat widget into websites.
Supports floating/fullscreen modes, real-time messaging, virtual simulation, and multilingual UI.

Installation

npm install @skywu/virtual-chat-sdk
# or
yarn add @skywu/virtual-chat-sdk
# or
pnpm add @skywu/virtual-chat-sdk

Quick Start (ESM)

import { ChatSDK } from '@skywu/virtual-chat-sdk'

const chat = ChatSDK.init({
  container: '#chat-container',
  projectId: 'YOUR_PROJECT_ID',
  userId: 'user_123',
  username: 'Visitor',
  language: 'en',
  country: 'US',
  mode: 'floating',
  autoJoin: true,
  apiBaseUrl: 'https://YOUR_SERVER_DOMAIN',
  socketUrl: 'https://YOUR_SERVER_DOMAIN',
  floatingButton: {
    position: 'bottom-right',
    offset: { bottom: 20, right: 20 }
  }
})

Quick Start (UMD)

<div id="chat-container"></div>
<script src="https://YOUR_SERVER_DOMAIN/sdk/chat-sdk.umd.js"></script>
<script>
  const chat = ChatSDK.init({
    container: '#chat-container',
    projectId: 'YOUR_PROJECT_ID',
    userId: 'user_123',
    username: 'Visitor',
    language: 'en',
    country: 'US',
    mode: 'floating',
    autoJoin: true,
    apiBaseUrl: 'https://YOUR_SERVER_DOMAIN',
    socketUrl: 'https://YOUR_SERVER_DOMAIN'
  })
</script>

Configuration

Required

• container: string | HTMLElement
• projectId: string

Core Optional

• templateId?: string
• userId?: string
• username?: string
• language?: string
• country?: string
• theme?: 'light' | 'dark' | 'auto'
• uiTemplate?: 'whatsapp' | 'telegram'
• primaryColor?: string
• backgroundColor?: string
• apiBaseUrl?: string
• socketUrl?: string
• token?: string
• mode?: 'fullscreen' | 'floating'
• autoJoin?: boolean
• autoStart?: boolean

Floating Button

floatingButton?: {
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  offset?: { top?: number; right?: number; bottom?: number; left?: number }
  icon?: 'chat' | string
  zIndex?: number
}

UI / Performance

• showAvatars?: boolean
• showUsernames?: boolean
• allowInput?: boolean
• enableUserInput?: boolean
• initialRenderCount?: number
• lazyLoadBatchSize?: number
• groupMessages?: boolean
• groupTimeThresholdSec?: number

Callbacks

• onReady?: () => void
• onOpen?: () => void
• onClose?: () => void
• onJoin?: (data: { userId: string; username: string }) => void
• onMessage?: (message: ChatMessage) => void
• onUserMessage?: (message: ChatMessage) => void
• onError?: (error: Error) => void
• onLanguageChange?: (language: string) => void
• onThemeChange?: (theme: string) => void
• onSimulationStart?: () => void
• onSimulationEnd?: () => void

API Methods

chat.open()
chat.close()
chat.destroy()

chat.joinChat()
chat.leaveChat()
chat.sendMessage('Hello', 'text')

chat.startSimulation()
chat.pauseSimulation()
chat.resumeSimulation()
chat.stopSimulation()

await chat.setLanguage('zh')
chat.setTheme('dark')
chat.setUITemplate('telegram')
chat.setCustomColors({ primary: '#2481CC', background: '#FFFFFF' })
chat.setTemplate('template-id')

chat.isOpen()
chat.isJoined()
chat.getConfig()
chat.getMessages()

Events

chat.on('ready', () => {})
chat.on('open', () => {})
chat.on('close', () => {})
chat.on('message', (message) => {})
chat.on('error', (error) => {})
chat.off('message')

Display Modes

• floating (recommended): floating launcher button; no need to call open() manually.
• fullscreen: full chat UI mode; call open() when needed.

TypeScript

import { ChatSDK, ChatSDKConfig, ChatMessage } from '@skywu/virtual-chat-sdk'

const config: ChatSDKConfig = {
  container: '#chat-container',
  projectId: 'YOUR_PROJECT_ID',
  country: 'US',
  onMessage: (message: ChatMessage) => {
    console.log(message.content)
  }
}

const chat = ChatSDK.init(config)

Notes

• For third-party sites, always set apiBaseUrl and socketUrl.
• Make sure your server CORS allows your site origin.
• projectId comes from your admin project list.
• Call destroy() when unmounting in SPA frameworks.

License

MIT