@warriorteam/zalo-personal

v1.3.0

Published

a month ago

Unofficial Zalo Personal API for JavaScript - A powerful library for interacting with Zalo personal accounts with URL attachment support, auto-reply, product catalog, and business features

Downloads

Zalo Personal SDK v1.3.0 🚀

[!NOTE] Đây là SDK không chính thức cho tài khoản Zalo cá nhân. Nó hoạt động bằng cách mô phỏng trình duyệt để tương tác với Zalo Web, cung cấp giao diện JavaScript/TypeScript toàn diện cho việc nhắn tin cá nhân trên Zalo.

[!WARNING] Sử dụng SDK này có thể khiến tài khoản của bạn bị khóa hoặc cấm. Chúng tôi không chịu trách nhiệm về bất kỳ vấn đề nào có thể xảy ra. Sử dụng với trách nhiệm của riêng bạn.

[!IMPORTANT] 🎉 Version 1.3.0 - Business & E-commerce Features Now Available! Complete auto-reply system, product catalog management, and enhanced business capabilities. See what's new

Mục Lục

Cài Đặt

npm install zalo-personal-sdk
# hoặc
yarn add zalo-personal-sdk
# hoặc
bun install zalo-personal-sdk

🚀 What's New in v1.3.0

💼 Zalo Business Features

Auto Reply System

Tự động trả lời tin nhắn cho khách hàng một cách thông minh:

import { AutoReplyScope } from '@warriorteam/zalo-personal';

// Tạo auto-reply cho giờ nghỉ
await api.createAutoReply({
    content: "Cảm ơn bạn đã liên hệ! Chúng tôi sẽ trả lời vào giờ hành chính (8:00-17:00).",
    isEnable: true,
    startTime: getTodayAt(17), // 5 PM
    endTime: getTomorrowAt(8), // 8 AM next day
    scope: AutoReplyScope.Everyone
});

// Auto-reply cho người lạ
await api.createAutoReply({
    content: "Chào mừng bạn! Đừng quên theo dõi chúng tôi để nhận ưu đãi nhé! 🎉",
    scope: AutoReplyScope.Stranger,
    isEnable: true
});

Features:

✅ Multiple reply scopes (Everyone, Strangers, Specific Friends, Friends Except)
✅ Time-based scheduling
✅ Content management
✅ Enable/disable controls
✅ CRUD operations

Product Catalog Management

Quản lý sản phẩm và bán hàng trực tiếp trên Zalo:

// Thêm sản phẩm mới
await api.createProductCatalog({
    catalogId: "main_catalog",
    productName: "Áo Thun Premium",
    price: "299000",
    description: "Chất liệu cao cấp, form dáng chuẩn",
    product_photos: [
        await api.uploadProductPhoto({ file: "front.jpg" }),
        await api.uploadProductPhoto({ file: "back.jpg" })
    ]
});

// Lấy danh sách sản phẩm
const products = await api.getProductCatalogList({
    catalogId: "main_catalog",
    limit: 20,
    page: 0
});

Features:

✅ Complete product management (CRUD)
✅ Photo upload (up to 5 photos per product)
✅ Pagination support
✅ Currency and pricing management
✅ Product organization

🛠️ Technical Improvements

Enhanced Type Safety: New TypeScript models and enums
Better Error Handling: Comprehensive error messages
Backward Compatible: Zero breaking changes
Performance Optimizations: Faster API responses
Documentation: Complete API reference with examples

📚 New Models & Types

// Business Models
AutoReplyItem           // Auto-reply configuration
ProductCatalogItem     // Product information
AutoReplyScope          // Reply targeting options
BusinessCategory        // Business type classifications

// API Response Types
CreateAutoReplyResponse
CreateProductCatalogResponse
// ... và nhiều hơn nữa

🔄 Easy Migration

No breaking changes! Upgrade with a single command:

npm install @warriorteam/[email protected]

All existing code continues to work exactly as before.

Tài Liệu Hướng Dẫn

SDK này cung cấp API toàn diện để tương tác với tài khoản Zalo cá nhân một cách lập trình.

📚 Tài Liệu Chi Tiết

🏗️ Kiến Trúc Hệ Thống - Phân tích chi tiết cấu trúc và design patterns
🔐 Hướng Dẫn Xác Thực - Đăng nhập bằng Cookie và QR Code
💬 API Gửi Tin Nhắn - Gửi tin nhắn, file đính kèm, sticker
👥 Quản Lý Bạn Bè - Tìm kiếm, kết bạn, quản lý danh sách bạn bè
👨‍👩‍👧‍👦 Quản Lý Nhóm - Tạo nhóm, quản lý thành viên, cài đặt nhóm
🎧 Lắng Nghe Sự Kiện - Listener, xử lý sự kiện real-time
📋 Tham Khảo Types - Tài liệu đầy đủ về tất cả types

🚀 Hướng Dẫn Nhanh

📖 Hướng Dẫn Sử Dụng Đầy Đủ - Hướng dẫn chi tiết bằng tiếng Việt

Sử Dụng Cơ Bản

Đăng Nhập

Đăng nhập bằng QR Code

import { Zalo } from "zalo-personal-sdk";

const zalo = new Zalo();
const api = await zalo.loginQR();
console.log('✅ Đăng nhập thành công!');

Đăng nhập bằng Cookie

import { Zalo } from "zalo-personal-sdk";

const credentials = {
  imei: 'your-device-imei',
  cookie: [/* cookie array */],
  userAgent: 'Mozilla/5.0...',
  language: 'vi'
};

const zalo = new Zalo();
const api = await zalo.login(credentials);

Lắng Nghe Tin Nhắn Mới

import { Zalo, ThreadType } from "zalo-personal-sdk";

const zalo = new Zalo({ selfListen: true });
const api = await zalo.loginQR();

api.listener.on("message", (message) => {
  const isPlainText = typeof message.data.content === "string";

  switch (message.threadType) {
    case ThreadType.User: {
      if (isPlainText) {
        console.log(`💬 Tin nhắn cá nhân: ${message.data.content}`);
      }
      break;
    }
    case ThreadType.Group: {
      if (isPlainText) {
        console.log(`👥 Tin nhắn nhóm: ${message.data.content}`);
      }
      break;
    }
  }
});

await api.listener.start();
console.log('🎧 Đang lắng nghe tin nhắn...');

[!IMPORTANT] Chỉ có một listener web có thể chạy cho mỗi tài khoản tại một thời điểm. Nếu bạn mở Zalo trên trình duyệt khi listener đang hoạt động, listener sẽ tự động dừng.

Gửi Tin Nhắn

Bot Echo đơn giản

import { Zalo, ThreadType } from "zalo-personal-sdk";

const zalo = new Zalo();
const api = await zalo.loginQR();

api.listener.on("message", async (message) => {
  const isPlainText = typeof message.data.content === "string";
  if (message.isSelf || !isPlainText) return;

  const echoMessage = {
    msg: "🔊 Echo: " + message.data.content,
    quote: message // Trả lời tin nhắn gốc (tùy chọn)
  };

  try {
    await api.sendMessage(echoMessage, message.threadId, message.threadType);
    console.log('✅ Đã gửi tin nhắn echo');
  } catch (error) {
    console.error('❌ Lỗi gửi tin nhắn:', error.message);
  }
});

await api.listener.start();

Gửi tin nhắn với định dạng

import { TextStyle, Urgency } from "zalo-personal-sdk";

const formattedMessage = {
  msg: 'Tin nhắn quan trọng với định dạng!',
  styles: [
    { start: 0, len: 11, st: TextStyle.Bold },      // "Tin nhắn"
    { start: 12, len: 9, st: TextStyle.Red }        // "quan trọng"
  ],
  urgency: Urgency.Important
};

await api.sendMessage(formattedMessage, threadId, ThreadType.User);

Gửi File Đính Kèm Từ URL

// Gửi ảnh từ URL
await api.sendMessage({
  msg: "Ảnh từ internet",
  attachments: {
    url: "https://picsum.photos/800/600",
    filename: "random-image.jpg" // Tùy chọn, sẽ tự phát hiện nếu không cung cấp
  }
}, threadId, ThreadType.User);

// Gửi nhiều file từ URL
await api.sendMessage({
  msg: "Nhiều file từ URL",
  attachments: [
    {
      url: "https://picsum.photos/400/300?random=1",
      filename: "image1.jpg"
    },
    {
      url: "https://picsum.photos/400/300?random=2", 
      filename: "image2.jpg"
    }
  ]
}, threadId, ThreadType.User);

// Gửi file với headers tùy chỉnh
await api.sendMessage({
  msg: "File với headers tùy chỉnh",
  attachments: {
    url: "https://api.example.com/protected-image.jpg",
    filename: "protected-image.jpg",
    headers: {
      "Authorization": "Bearer your-token",
      "User-Agent": "Custom-Agent"
    }
  }
}, threadId, ThreadType.User);

// Kết hợp file local, URL và buffer
await api.sendMessage({
  msg: "File đính kèm hỗn hợp",
  attachments: [
    "./local-file.jpg", // Đường dẫn file local
    {
      url: "https://picsum.photos/300/200",
      filename: "url-image.jpg"
    },
    {
      data: fileBuffer,
      filename: "buffer-file.jpg",
      metadata: { totalSize: fileBuffer.length }
    }
  ]
}, threadId, ThreadType.User);

Lấy/Gửi Sticker

// Tìm sticker theo từ khóa
const stickers = await api.getStickers();
console.log('Danh sách sticker:', stickers);

// Lấy chi tiết sticker
const stickerDetail = await api.getStickersDetail('sticker-category-id');

// Gửi sticker
await api.sendSticker(
  'sticker-id',
  threadId,
  ThreadType.User,
  'category-id'
);

Bot Thông Minh

api.listener.on("message", async (message) => {
  const { threadId, threadType, data, senderId } = message;
  
  // Bỏ qua tin nhắn của chính mình
  if (message.isSelf) return;
  
  const text = data.content?.toLowerCase().trim();
  if (!text) return;

  try {
    if (text === '/help') {
      await api.sendMessage(`
🤖 **Bot Commands:**
• \`/help\` - Hiển thị hướng dẫn  
• \`/time\` - Xem thời gian hiện tại
• \`/weather\` - Dự báo thời tiết
• \`/ping\` - Test bot
      `, threadId, threadType);
      
    } else if (text === '/time') {
      const now = new Date().toLocaleString('vi-VN');
      await api.sendMessage(`🕐 **Bây giờ là:** ${now}`, threadId, threadType);
      
    } else if (text === '/ping') {
      await api.sendMessage('🏓 **Pong!** Bot đang hoạt động bình thường.', threadId, threadType);
      
    } else if (text.includes('hello') || text.includes('chào')) {
      await api.sendMessage('👋 **Xin chào!** Gõ `/help` để xem hướng dẫn.', threadId, threadType);
    }
  } catch (error) {
    console.error('❌ Lỗi xử lý tin nhắn:', error.message);
  }
});

Ví Dụ

Xem thư mục examples để biết thêm chi tiết và các ví dụ nâng cao.

Các ví dụ có sẵn:

Bot Echo - Bot trả lời lại tin nhắn
Auto Friend Accept - Tự động chấp nhận lời mời kết bạn
Group Manager - Quản lý nhóm tự động
Message Analytics - Thống kê tin nhắn
File Backup - Sao lưu tin nhắn và file

Đóng Góp

Chúng tôi hoan nghênh sự đóng góp từ cộng đồng! Vui lòng xem Hướng Dẫn Đóng Góp để biết chi tiết về cách:

🐛 Báo cáo lỗi và vấn đề
✨ Đề xuất tính năng mới
🔧 Gửi code contribution
📚 Cải thiện tài liệu
🧪 Thêm hoặc cải thiện tests
🔒 Báo cáo lỗ hổng bảo mật

Để biết thêm thông tin, vui lòng đọc Quy Tắc Ứng Xử và Chính Sách Bảo Mật của chúng tôi.

Tính Năng Chính

🔐 Xác Thực

Đăng nhập bằng Cookie
Đăng nhập bằng QR Code
Tự động làm mới session
Hỗ trợ nhiều tài khoản

💬 Tin Nhắn

Gửi tin nhắn văn bản (có định dạng)
Gửi file đính kèm (ảnh, video, tài liệu)
Tin nhắn trả lời (quote)
Mention người dùng trong nhóm
Tin nhắn tự hủy (TTL)
Sticker và emoji

👥 Quản Lý Bạn Bè

Tìm kiếm người dùng
Gửi/chấp nhận lời mời kết bạn
Quản lý danh sách bạn bè
Chặn/bỏ chặn người dùng
Quản lý biệt danh

👨‍👩‍👧‍👦 Quản Lý Nhóm

Tạo và quản lý nhóm
Thêm/xóa thành viên
Quản lý quyền admin
Cài đặt nhóm
Tạo poll và reminder
Link tham gia nhóm

🎧 Sự Kiện Real-time

Lắng nghe tin nhắn mới
Sự kiện nhóm
Sự kiện bạn bè
Reaction và typing
Seen/delivered status

🛠️ Tiện Ích

TypeScript support đầy đủ
Error handling mạnh mẽ
Rate limiting tự động
Logging và monitoring
Auto reconnect
Memory management

Yêu Cầu Hệ Thống

Node.js: ≥ 16.0.0
TypeScript: ≥ 4.0 (nếu sử dụng TypeScript)
Hệ điều hành: Windows, macOS, Linux

Hiệu Năng

⚡ Nhanh: Xử lý hàng nghìn tin nhắn/phút
🔄 Ổn định: Auto reconnect và error recovery
💾 Tiết kiệm bộ nhớ: Memory management tối ưu
🌐 Mở rộng: Hỗ trợ multiple instances

Bảo Mật

🔒 Không lưu trữ credentials
🛡️ Rate limiting tự động
🔐 Mã hóa dữ liệu nhạy cảm
⚠️ Cảnh báo rủi ro bảo mật

Hỗ Trợ

📖 Tài liệu: Comprehensive documentation
💬 Community: GitHub Discussions
🐛 Bug Reports: GitHub Issues
📧 Email: Liên hệ

Giấy Phép

Dự án này được cấp phép theo Giấy phép MIT - xem file LICENSE để biết chi tiết.

⭐ Nếu SDK này hữu ích, hãy cho chúng tôi một star trên GitHub! ⭐

🌟 Star trên GitHub • 📖 Tài liệu • 💬 Thảo luận