@satek-vn/chatbot-widget
v0.0.6
Published
A widget chatbot can be integrated into any website, providing a seamless and interactive user experience. It is designed to be easily embedded and customizable, allowing businesses to engage with their customers effectively.
Downloads
872
Readme
@satek-vn/chatbot-widget
A powerful chatbot widget package that can be integrated into any website, providing a seamless and interactive user experience. It is designed to be easily embedded and customizable, allowing businesses to engage with their customers effectively.
📋 Table of Contents
Widget Section (English)
SDK Section (Advanced)
- SDK Guide
- SDK Initialization
- Authentication Management
- Receiver Management
- Member Management
- Chat Management
- Message Management
- Event System
Support & License
Features
- 🎨 Customizable UI (colors, title, ...)
- 📱 Responsive design - works on all devices
- ⚡ Lightweight and high performance
- 🔧 Easy to integrate into any website
- 💬 Support for advanced chat features
Installation
1. React Component (npm)
Step 1: Install package
npm install @satek-vn/chatbot-widgetStep 2: Import and use
import React from 'react';
import { ChatWidget } from '@satek-vn/chatbot-widget';
export default function App() {
return (
<ChatWidget
title="Hỗ trợ"
workspace="dev"
logoUrl="https://example.com/logo.png"
primaryColor="#6366f1"
auth={{
code: 'user_1002',
name: 'Nguyễn Văn A',
avatar: 'https://example.com/avatar.jpg',
phone: '0123456789',
email: '[email protected]',
}}
chatKey="your_chat_key_here"
features={{
attachments: ['image', 'video', 'file'],
communication: ['voice'],
chatModes: ['single', 'group'],
customizations: ['change-color', 'change-theme'],
}}
language="english"
initPosition={{
right: 20,
bottom: 20,
}}
/>
);
}Requirements
- React >= 18
- React DOM >= 18
- @reduxjs/toolkit >= 2.11.2
- react-redux >= 9.2.0
- wasm-media-encoders >= 0.7.0
Full example
import React from 'react';
import ReactDOM from 'react-dom/client';
import { ChatWidget } from '@satek-vn/chatbot-widget';
const container = document.getElementById('root');
if (container) {
ReactDOM.createRoot(container).render(
<React.StrictMode>
<ChatWidget
title="Hỗ trợ khách hàng"
workspace="production"
logoUrl="https://example.com/logo.png"
primaryColor="#6366f1"
auth={{
code: 'user_1002',
name: 'Nguyễn Văn A',
avatar: 'https://example.com/avatar.jpg',
phone: '0123456789',
email: '[email protected]',
}}
chatKey="your_chat_key_here"
features={{
attachments: ['image', 'video', 'audio', 'file', 'multiple'],
communication: ['voice'],
chatModes: ['single', 'group'],
customizations: ['change-color', 'change-theme'],
}}
language="english"
initPosition={{
right: 20,
bottom: 20,
}}
/>
</React.StrictMode>,
);
}2. UMD (Use in plain HTML)
Step 1: Add script tag
<script src="https://unpkg.com/@satek-vn/chatbot-widget/dist/chatbot-widget.umd.js"></script>Or use jsdelivr CDN:
<script src="https://cdn.jsdelivr.net/npm/@satek-vn/chatbot-widget/dist/chatbot-widget.umd.js"></script>Step 2: Initialize widget
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Your Website</title>
</head>
<body>
<h1>Welcome to our website</h1>
<script src="https://unpkg.com/@satek-vn/chatbot-widget/dist/chatbot-widget.umd.js"></script>
<script>
ChatbotWidget.init({
title: 'Customer Support',
workspace: 'production',
logoUrl: 'https://example.com/logo.png',
primaryColor: '#6366f1',
auth: {
code: 'user_1001',
name: 'Nguyễn Văn A',
avatar: 'https://example.com/avatar.jpg',
phone: '0123456789',
email: '[email protected]',
},
chatKey: 'your_chat_key_here',
features: {
attachments: ['image', 'video', 'audio', 'file', 'multiple'],
communication: ['voice'],
chatModes: ['single', 'group'],
customizations: ['change-color', 'change-theme'],
},
language: 'english',
initPosition: {
right: 20,
bottom: 20,
},
});
</script>
</body>
</html>Widget Usage
Props / Options
| Name | Type | Required | Description |
| ------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| title | string | ✅ | Title of the chat widget |
| workspace | string | ✅ | Workspace identifier for multi-workspace support. Max 50 chars, supports lowercase, numbers, symbols (_), (-), (.) |
| logoUrl | string | ❌ | URL of the logo image to display in the widget header |
| primaryColor | string | ❌ | Primary color (hex format). Default: #6366f1 |
| chatKey | string | ✅ | Authentication key to connect to backend |
| auth | object | ✅ | User authentication information |
| auth.code | string | ✅ | Unique user identifier |
| auth.name | string | ✅ | User name |
| auth.avatar | string | ✅ | URL of user avatar image |
| auth.phone | string | ❌ | User phone number |
| auth.email | string | ✅ | User email address |
| features | object | ❌ | Feature configuration object with properties: attachments, communication, chatModes, customizations |
| features.attachments | array | ❌ | Allowed file types for upload: 'image', 'video', 'audio', 'file', 'multiple'. If not provided, no file upload allowed |
| features.communication | array | ❌ | Communication features: 'voice' for voice recording and audio messages. Default: [] |
| features.chatModes | array | ❌ | Supported chat modes: 'single' for one-to-one chat, 'group' for group chat. Default: ['single'] |
| features.customizations | array | ❌ | User customization options: 'change-color' to allow color customization, 'change-theme' to allow theme switching. Default: [] |
| language | string | ❌ | Initial language setting: 'english' or 'vietnamese'. If not provided, user can toggle language via UI button. Default: 'vietnamese' |
| initPosition | object | ❌ | Initial position of the widget. Object with right (distance from right edge) and bottom (distance from bottom edge) in pixels |
Configuration example
{
title: 'Customer Support',
workspace: 'production',
logoUrl: 'https://example.com/logo.png',
primaryColor: '#FF6B6B',
auth: {
code: 'customer_123',
name: 'John Doe',
avatar: 'https://example.com/images/avatar.jpg',
phone: '+1 (555) 123-4567',
email: '[email protected]',
},
chatKey: 'secure_key_abc123xyz',
features: {
attachments: ['image', 'video', 'file', 'multiple'],
communication: ['voice'],
chatModes: ['single', 'group'],
customizations: ['change-color', 'change-theme'],
},
language: 'english',
initPosition: {
right: 20,
bottom: 20,
},
}Configuration
Customization
Change primary color
You can customize the primary color of the widget using the primaryColor prop:
React:
<ChatWidget
primaryColor="#FF6B6B"
// ... other props
/>UMD:
ChatbotWidget.init({
primaryColor: '#FF6B6B',
// ... other options
});Change title
React:
<ChatWidget
title="Customer Service"
// ... other props
/>UMD:
ChatbotWidget.init({
title: 'Customer Service',
// ... other options
});Change logo
You can customize the logo displayed in the widget header using the logoUrl prop:
React:
<ChatWidget
logoUrl="https://example.com/logo.png"
// ... other props
/>UMD:
ChatbotWidget.init({
logoUrl: 'https://example.com/logo.png',
// ... other options
});Configure supported attachments
Specify which file types users can upload:
React:
<ChatWidget
features={{
attachments: ['image', 'video', 'audio', 'file', 'multiple'],
}}
// ... other props
/>UMD:
ChatbotWidget.init({
features: {
attachments: ['image', 'video', 'audio', 'file', 'multiple'],
},
// ... other options
});Supported attachment types:
'image'- Image files (jpg, png, etc.)'video'- Video files'audio'- Audio files'file'- General documents'multiple'- Allow selecting multiple files at once
Configure communication features
Enable audio and video communication capabilities:
React:
<ChatWidget
features={{
communication: ['voice'],
}}
// ... other props
/>UMD:
ChatbotWidget.init({
features: {
communication: ['voice'],
},
// ... other options
});Supported communication features:
'voice'- Voice recording and sending audio messages
Configure chat modes
Enable single-to-single or group chat capabilities:
React:
<ChatWidget
features={{
chatModes: ['single', 'group'],
}}
// ... other props
/>UMD:
ChatbotWidget.init({
features: {
chatModes: ['single', 'group'],
},
// ... other options
});Supported chat modes:
'single'- One-to-one direct messaging'group'- Group chat with multiple participants
Allow color change
Enable users to change the widget's color and theme using customization features:
React:
<ChatWidget
features={{
customizations: ['change-color', 'change-theme'],
}}
// ... other props
/>UMD:
ChatbotWidget.init({
features: {
customizations: ['change-color', 'change-theme'],
},
// ... other options
});Configure language support
You can set the initial language for the widget using the language prop:
React:
<ChatWidget
language="vietnamese"
// ... other props
/>UMD:
ChatbotWidget.init({
language: 'vietnamese',
// ... other options
});Language behavior:
- When
languageis provided: The widget will use the specified language (either'english'or'vietnamese') and the user can toggle to another language via the UI button - When
languageis not provided: The widget defaults to Vietnamese, and users can toggle between English and Vietnamese using the language switcher button in the interface
Supported languages:
'english'- English interface'vietnamese'- Vietnamese interface
Troubleshooting
Widget not displaying
- Check if
chatKeyis correct - Make sure all dependencies are installed
- Check the browser console for any errors
Dependencies error
If you encounter dependency errors when using React component:
npm install @reduxjs/toolkit react-redux wasm-media-encodersWidget cannot communicate with server
- Check
chatKeyand backend configuration - Make sure CORS is properly configured on the server
🔌 Advanced: Core SDK API (SDK Documentation)
Bridge Note: The Chatbot Widget is a pre-built, user-friendly interface built on top of the Core SDK. If you're using the Widget component, you don't need to interact with the SDK directly. This section is for advanced users who want to build a custom UI or integrate chat functionality into their own applications using the SDK's lower-level API.
SDK Usage Guide
This documentation provides detailed instructions on how to use the Chat SDK functions for real-time chat applications.
SDK Table of Contents
- SDK Initialization
- Authentication Management
- Receiver Management
- Member Management
- Chat Management
- Message Management
- Event System
SDK Initialization
Step 1: Import SDK
<script src="https://chat.satek.vn/sdk/1.0.js?key=[API KEY]"></script>Step 2: Create instance and configure
// Create SDK instance
const chatSDK = new initSChat();
// Create SDK instance with workspace. Max 50 chars. Supports lowercase, numbers, and symbols (_), (-), (.).
const chatSDK = new initSChat('dev');
// Configure if needed
chatSDK.setConfig({
// Custom configuration
});Authentication Management
setAuth(data) - Login/Create Account
Create or login a member account.
Parameters:
data(Object): Member informationcode(String, required): Unique identifier codename(String, required): Member nameavatar(String, optional): Avatar image URLphone(String, optional): Phone numberemail(String, optional): Email address
Returns: Promise returning member object
Example:
await chatSDK.setAuth({
code: 'user_1001',
name: 'John Doe',
avatar: 'https://example.com/avatar.jpg',
phone: '0123456789',
email: '[email protected]',
});Note:
- This function also automatically connects to the realtime server
- Loads unread message count from server
- Calling this function initializes the realtime connection
getAuth() - Get Current Account Information
Get logged-in member information.
Returns: Member object or null
Example:
const currentUser = chatSDK.getAuth();
console.log(currentUser);clearAuth() - Logout
Clear current authentication information.
Example:
chatSDK.clearAuth();Receiver Management
setReceiver(data) - Set Receiver
Create receiver account (typically used for 1-1 chat).
Parameters:
data(Object): Receiver information (same assetAuth)
Returns: Promise returning receiver object
Example:
await chatSDK.setReceiver({
code: 'user_1002',
name: 'Jane Doe',
avatar: 'https://example.com/avatar2.jpg',
});getReceiver() - Get Receiver Information
Returns: Receiver object or null
Example:
const receiver = chatSDK.getReceiver();
console.log(receiver);clearReceiver() - Clear Receiver Information
Example:
chatSDK.clearReceiver();Member Management
getMembers(chatId, limit, page, include) - Get Member List
Get list of members in a chat or all members.
Parameters:
chatId(Number, optional): Chat ID. If null, get all memberslimit(Number, optional): Number of records (default: 0 = all)page(Number, optional): Page number (default: 1)include(String, optional): Additional fields to retrieve
Returns: Promise returning member list
Example:
// Get all members
const allMembers = await chatSDK.getMembers();
// Get members of a chat
const chatMembers = await chatSDK.getMembers(123, 50, 1);
// Pagination
const page1Members = await chatSDK.getMembers(123, 10, 1);
const page2Members = await chatSDK.getMembers(123, 10, 2);addMember(chatId, memberId) - Add Member to Group
Invite another member to the group chat.
Parameters:
chatId(Number, required): Chat IDmemberId(Number, required): Member ID to add
Returns: Promise returning result
Example:
await chatSDK.addMember(123, 456);removeMember(chatId, memberId) - Remove Member from Group
Remove a member from the group or member leaves the group.
Parameters:
chatId(Number, required): Chat IDmemberId(Number, required): Member ID to remove
Returns: Promise returning result
Example:
await chatSDK.removeMember(123, 456);Note: If you remove yourself from the group, the group will be completely deleted
Chat Management
getChats(limit, page) - Get Chat List
Get list of chats for the current member.
Parameters:
limit(Number, optional): Number of items (default: 0 = all)page(Number, optional): Page number (default: 1)
Returns: Promise returning chat list
Example:
// Get all chats
const chats = await chatSDK.getChats();
// Pagination: 20 chats per page
const page1 = await chatSDK.getChats(20, 1);
const page2 = await chatSDK.getChats(20, 2);findChatByReceiver(receiverId) - Find Chat with Receiver
Find 1-1 chat with a specific person.
Parameters:
receiverId(Number, required): Receiver ID
Returns: Promise returning chat object or null
Example:
const existChat = await chatSDK.findChatByReceiver(456);
if (existChat) {
console.log('Chat already exists');
} else {
console.log('No chat with this person yet');
}addChat(receiverId, content) - Create 1-1 Chat
Create a new chat with someone (or get existing chat if already exists).
Parameters:
receiverId(Number, required): Receiver IDcontent(String, optional): First message (if needed)
Returns: Promise returning chat object
Example:
// Create new chat
const chat1 = await chatSDK.addChat(456);
// Create chat with first message
const chat2 = await chatSDK.addChat(456, 'Hello!');addGroup(memberIds, name, avatar) - Create Group Chat
Create a new group chat.
Parameters:
memberIds(Array, required): List of member IDs (at least 2 other members)name(String, required): Group nameavatar(String|File, optional): New avatar URL or File
Returns: Promise returning group object
Example:
// Create simple group
const group = await chatSDK.addGroup([456, 789], 'Project A Group');
// Create group with avatar
const groupWithAvatar = await chatSDK.addGroup(
[456, 789],
'Project B Group',
'https://example.com/group.jpg',
);updateGroup(chatId, name, avatar) - Update Group Information
Update group name and avatar.
Parameters:
chatId(Number, required): Group IDname(String, required): New group nameavatar(String|File, optional): New avatar URL or File
Returns: Promise returning updated group object
Example:
// Update name only
await chatSDK.updateGroup(123, 'New Group Name');
// Update both name and avatar
await chatSDK.updateGroup(
123,
'New Group Name',
'https://example.com/new-avatar.jpg',
);removeChat(chatId) - Delete Chat
Delete a chat (1-1 chat or group).
Parameters:
chatId(Number, required): Chat ID
Returns: Promise returning result
Example:
await chatSDK.removeChat(123);readChat(chatId) - Mark Chat as Read
Mark a chat as read.
Parameters:
chatId(Number, required): Chat ID
Returns: Promise returning result
Example:
await chatSDK.readChat(123);unreadChat(chatId) - Mark Chat as Unread
Mark a chat as unread.
Parameters:
chatId(Number, required): Chat ID
Returns: Promise returning result
Example:
await chatSDK.unreadChat(123);Message Management
getMessages(chatId, limit, page) - Get Message List
Get list of messages in a chat (supports pagination for loading history).
Parameters:
chatId(Number, required): Chat IDlimit(Number, optional): Number of messages (default: 20)page(Number, optional): Page number (default: 1)
Returns: Promise returning message list
Example:
// Get last 20 messages
const messages = await chatSDK.getMessages(123);
// Get 50 messages
const moreMessages = await chatSDK.getMessages(123, 50);
// Load history: page 2
const oldMessages = await chatSDK.getMessages(123, 20, 2);addMessage(chatId, content, files, replyId) - Send Message
Send a message with content, files, or reply to another message.
Parameters:
chatId(Number, required): Chat IDcontent(String, optional): Message content (required if no files)files(FileList|File[], optional): List of files to sendreplyId(Number, optional): Message ID to reply to
Returns: Promise returning sent message object
Example:
// Send text message
await chatSDK.addMessage(123, 'Hello!');
// Send message with file
const fileInput = document.querySelector('input[type=file]');
const files = fileInput.files;
await chatSDK.addMessage(123, 'Check this file', files);
// Reply to another message
await chatSDK.addMessage(123, 'Agreed!', null, 456);
// Send file only (no content)
await chatSDK.addMessage(123, null, files);actionMessage(chatId, messageId, action) - Interact with Message
Perform interactions with messages like like, love, revoke, remove.
Parameters:
chatId(Number, required): Chat IDmessageId(Number, required): Message IDaction(String, required): Interaction typelike: Like messagelove: Love messagerevoke: Revoke message (delete for everyone)remove: Remove message (disable only on your device)
Returns: Promise returning result
Example:
// Like message
await chatSDK.actionMessage(123, 456, 'like');
// Love message
await chatSDK.actionMessage(123, 456, 'love');
// Revoke message
await chatSDK.actionMessage(123, 456, 'revoke');
// Remove message
await chatSDK.actionMessage(123, 456, 'remove');Event System
SDK uses an event system to notify real-time changes.
List of Events
chatSDK.EVENTS = {
chats_created: 'chats.created', // New chat created
chats_updated: 'chats.updated', // Chat updated
chats_deleted: 'chats.deleted', // Chat deleted
chats_member: 'chats.member', // Member joined/left group
chats_action: 'chats.action', // Mark read/unread
chats_message: 'chats.message', // New message or action
members_connect: 'members.connect', // Member connected (online)
members_disconnect: 'members.disconnect', // Member disconnected (offline)
new_message: 'new_message', // Unread message count updated
};addEventListener(event, listener) - Register Event
Listen to a real-time event.
Parameters:
event(String, required): Event name (fromEVENTS)listener(Function, required): Callback function executed when event occurs
Example:
// Listen for new messages
chatSDK.addEventListener(chatSDK.EVENTS.chats_message, (data) => {
console.log('New message:', data.message);
console.log('Chat:', data.chat);
console.log('Type:', data.type);
});
// Listen for new chats
chatSDK.addEventListener(chatSDK.EVENTS.chats_created, (data) => {
console.log('New chat:', data.chat);
});
// Listen for chat updates
chatSDK.addEventListener(chatSDK.EVENTS.chats_updated, (data) => {
console.log('Updated chat:', data.chat);
});
// Listen for chat deletion
chatSDK.addEventListener(chatSDK.EVENTS.chats_deleted, (data) => {
console.log('Deleted chat ID:', data.chat_id);
});
// Listen for member join/leave
chatSDK.addEventListener(chatSDK.EVENTS.chats_member, (data) => {
if (data.type === 'join') {
console.log('New member:', data.member);
} else if (data.type === 'leave') {
console.log('Member left: ID', data.member_id);
}
});
// Listen for read/unread actions
chatSDK.addEventListener(chatSDK.EVENTS.chats_action, (data) => {
console.log('Action type:', data.type);
console.log('Chat:', data.chat);
});
// Listen for member online/offline status
chatSDK.addEventListener(chatSDK.EVENTS.members_connect, (data) => {
console.log('Member connected - Socket ID:', data.socketId);
console.log('Timestamp:', data.timestamp);
});
chatSDK.addEventListener(chatSDK.EVENTS.members_disconnect, (data) => {
console.log('Member disconnected - Socket ID:', data.socketId);
});
// Listen for unread message count
chatSDK.addEventListener(chatSDK.EVENTS.new_message, (data) => {
console.log('Unread messages:', data.new);
});removeEventListener(event, listener) - Unregister Event
Stop listening to an event.
Parameters:
event(String, required): Event namelistener(Function, optional): Callback function to remove. If null, remove all listeners
Example:
// Define listener function
const messageListener = (data) => {
console.log('Message:', data.message);
};
// Register
chatSDK.addEventListener(chatSDK.EVENTS.chats_message, messageListener);
// Unregister specific function
chatSDK.removeEventListener(chatSDK.EVENTS.chats_message, messageListener);
// Remove all listeners for the event
chatSDK.removeEventListener(chatSDK.EVENTS.chats_message);setConfig(config) - Set Configuration
Set custom configuration options for SDK.
Parameters:
config(Object): Configuration options
Example:
chatSDK.setConfig({
debugMode: true,
maxRetries: 3,
});runEvent(name, data) - Push Custom Event
Push an event to all listeners (usually used for debugging or custom logic).
Parameters:
name(String, required): Event namedata(Object): Event data
Example:
chatSDK.runEvent(chatSDK.EVENTS.new_message, { new: 5 });Important Notes
- Realtime Connection: The
setAuth()function automatically connects realtime, no additional call needed - Promise-based: All API functions (except events) return Promise, use
async/await - Event Listeners: Multiple listeners can be registered for a single event
Support
For any feedback or support, please contact us via email: [email protected] or phone: 024.66.88.33.55.
License
MIT
Author
Satek Team
