@warriorteam/redai-zalo-sdk 1.17.4 → 1.18.0

package/docs/message-sequence-api.md

@@ -0,0 +1,464 @@
+# API Gửi Chuỗi Tin Nhắn Tư Vấn
+
+API này cho phép gửi một chuỗi tin nhắn tư vấn tới một người dùng với khả năng delay tùy chỉnh giữa các tin nhắn.
+
+## Tính năng
+
+- ✅ Hỗ trợ tất cả các loại tin nhắn: `text`, `image`, `gif`, `file`, `sticker`, `request_user_info`
+- ✅ Delay tùy chỉnh cho từng tin nhắn
+- ✅ Delay mặc định cho toàn bộ chuỗi tin nhắn
+- ✅ Xử lý lỗi chi tiết cho từng tin nhắn
+- ✅ Thống kê kết quả gửi tin nhắn
+- ✅ Ghi log thời gian thực hiện
+
+## Cách sử dụng
+
+### 1. Import các interface và service
+
+```typescript
+import { 
+  ConsultationService, 
+  MessageItem, 
+  SendMessageSequenceRequest 
+} from "../src/services/consultation.service";
+import { ZaloClient } from "../src/clients/zalo-client";
+```
+
+### 2. Khởi tạo service
+
+```typescript
+const zaloClient = new ZaloClient();
+const consultationService = new ConsultationService(zaloClient);
+```
+
+### 3. Định nghĩa chuỗi tin nhắn
+
+```typescript
+const messages: MessageItem[] = [
+  {
+    type: "text",
+    text: "Xin chào! 👋",
+    delay: 2000, // Delay 2 giây sau tin nhắn này
+  },
+  {
+    type: "image",
+    imageUrl: "https://example.com/image.jpg",
+    text: "Hình ảnh minh họa",
+    delay: 1500,
+  },
+  {
+    type: "sticker",
+    stickerAttachmentId: "STICKER_ID",
+  },
+];
+```
+
+### 4. Gửi chuỗi tin nhắn
+
+```typescript
+const request: SendMessageSequenceRequest = {
+  accessToken: "YOUR_ACCESS_TOKEN",
+  userId: "USER_ID",
+  messages,
+  defaultDelay: 1000, // Delay mặc định 1 giây
+};
+
+try {
+  const result = await consultationService.sendMessageSequence(request);
+  console.log(`Thành công: ${result.successCount}/${messages.length}`);
+} catch (error) {
+  console.error("Lỗi:", error);
+}
+```
+
+## Các loại tin nhắn được hỗ trợ
+
+### 1. Text Message
+```typescript
+{
+  type: "text",
+  text: "Nội dung tin nhắn",
+  delay: 1000, // Optional
+}
+```
+
+### 2. Image Message
+```typescript
+// Sử dụng URL
+{
+  type: "image",
+  imageUrl: "https://example.com/image.jpg",
+  text: "Caption cho ảnh", // Optional
+  delay: 1500,
+}
+
+// Hoặc sử dụng attachment ID
+{
+  type: "image",
+  attachmentId: "ATTACHMENT_ID",
+  text: "Caption cho ảnh", // Optional
+  delay: 1500,
+}
+```
+
+### 3. GIF Message
+```typescript
+{
+  type: "gif",
+  gifUrl: "https://example.com/animation.gif",
+  width: 300,  // Bắt buộc
+  height: 200, // Bắt buộc
+  text: "Caption cho GIF", // Optional
+  delay: 2000,
+}
+```
+
+### 4. File Message
+```typescript
+{
+  type: "file",
+  fileToken: "FILE_TOKEN_FROM_UPLOAD_API", // Bắt buộc
+  delay: 1000,
+}
+```
+
+### 5. Sticker Message
+```typescript
+{
+  type: "sticker",
+  stickerAttachmentId: "STICKER_ID", // Bắt buộc
+  delay: 500,
+}
+```
+
+### 6. Request User Info Message
+```typescript
+{
+  type: "request_user_info",
+  title: "Đăng ký tư vấn",           // Bắt buộc, max 100 ký tự
+  subtitle: "Vui lòng cung cấp...", // Bắt buộc, max 500 ký tự
+  imageUrl: "https://example.com/form.jpg", // Bắt buộc
+  delay: 2000,
+}
+```
+
+## Interface chi tiết
+
+### MessageItem
+```typescript
+interface MessageItem {
+  type: "text" | "image" | "gif" | "file" | "sticker" | "request_user_info";
+  text?: string;
+  imageUrl?: string;
+  gifUrl?: string;
+  width?: number;
+  height?: number;
+  fileToken?: string;
+  attachmentId?: string;
+  stickerAttachmentId?: string;
+  title?: string;
+  subtitle?: string;
+  delay?: number; // milliseconds
+}
+```
+
+### SendMessageSequenceRequest
+```typescript
+interface SendMessageSequenceRequest {
+  accessToken: string;
+  userId: string;
+  messages: MessageItem[];
+  defaultDelay?: number; // milliseconds
+}
+```
+
+### SendMessageSequenceResponse
+```typescript
+interface SendMessageSequenceResponse {
+  successCount: number;
+  failureCount: number;
+  results: Array<{
+    index: number;
+    type: string;
+    success: boolean;
+    response?: SendMessageResponse;
+    error?: string;
+    timestamp: number;
+  }>;
+  totalDuration: number; // milliseconds
+}
+```
+
+## Ví dụ thực tế
+
+### Chuỗi tin nhắn chào mừng khách hàng mới
+```typescript
+const welcomeMessages: MessageItem[] = [
+  {
+    type: "text",
+    text: "🎉 Chào mừng bạn đến với dịch vụ của chúng tôi!",
+    delay: 2000,
+  },
+  {
+    type: "sticker",
+    stickerAttachmentId: "WELCOME_STICKER_ID",
+    delay: 1500,
+  },
+  {
+    type: "image",
+    imageUrl: "https://company.com/welcome-banner.jpg",
+    text: "Khám phá các dịch vụ tuyệt vời",
+    delay: 3000,
+  },
+  {
+    type: "text",
+    text: "Chúng tôi sẽ hỗ trợ bạn 24/7. Hãy cho chúng tôi biết nếu bạn cần giúp đỡ! 💪",
+  },
+];
+```
+
+### Chuỗi tin nhắn hỗ trợ kỹ thuật
+```typescript
+const supportMessages: MessageItem[] = [
+  {
+    type: "text",
+    text: "Chúng tôi đã nhận được yêu cầu hỗ trợ của bạn 🔧",
+    delay: 1000,
+  },
+  {
+    type: "file",
+    fileToken: "TROUBLESHOOTING_GUIDE_TOKEN",
+    delay: 2000,
+  },
+  {
+    type: "text",
+    text: "Vui lòng tham khảo hướng dẫn trên. Nếu vẫn gặp vấn đề, hãy liên hệ trực tiếp:",
+    delay: 1500,
+  },
+  {
+    type: "request_user_info",
+    title: "Thông tin liên hệ",
+    subtitle: "Để chúng tôi hỗ trợ bạn nhanh nhất",
+    imageUrl: "https://company.com/support-form.jpg",
+  },
+];
+```
+
+## Lưu ý quan trọng
+
+1. **Delay**: Tính bằng milliseconds. Delay chỉ áp dụng giữa các tin nhắn, không có delay sau tin nhắn cuối cùng.
+
+2. **Error Handling**: API sẽ tiếp tục gửi các tin nhắn tiếp theo ngay cả khi một tin nhắn thất bại.
+
+3. **Rate Limiting**: Cần tuân thủ giới hạn tần suất gửi tin nhắn của Zalo để tránh bị chặn.
+
+4. **Validation**: Mỗi loại tin nhắn có các trường bắt buộc riêng, cần đảm bảo cung cấp đầy đủ thông tin.
+
+5. **File Upload**: Đối với file message, cần upload file trước và lấy token từ API upload của Zalo.
+
+---
+
+# API Gửi Chuỗi Tin Nhắn Tới Nhiều Users
+
+API mở rộng cho phép gửi chuỗi tin nhắn tư vấn tới nhiều users cùng lúc với callback tracking real-time.
+
+## Tính năng mới
+
+- ✅ Gửi chuỗi tin nhắn tới nhiều users
+- ✅ Callback tracking real-time cho từng user
+- ✅ Thống kê chi tiết (thành công/thất bại)
+- ✅ Delay tùy chỉnh giữa các users
+- ✅ Loại bỏ user IDs trùng lặp tự động
+- ✅ Error handling riêng biệt cho từng user
+
+## Cách sử dụng
+
+### 1. Import interface mới
+
+```typescript
+import {
+  SendMessageSequenceToMultipleUsersRequest,
+  UserProgressInfo
+} from "../src/services/consultation.service";
+```
+
+### 2. Định nghĩa callback tracking
+
+```typescript
+const onProgress = (progress: UserProgressInfo) => {
+  switch (progress.status) {
+    case 'started':
+      console.log(`🚀 Bắt đầu gửi cho User ${progress.userIndex + 1}/${progress.totalUsers}`);
+      break;
+    case 'completed':
+      console.log(`✅ Hoàn thành User ${progress.userIndex + 1} - Thành công: ${progress.result?.successCount}`);
+      break;
+    case 'failed':
+      console.log(`❌ Thất bại User ${progress.userIndex + 1} - Lỗi: ${progress.error}`);
+      break;
+  }
+};
+```
+
+### 3. Gửi tới nhiều users
+
+```typescript
+const request: SendMessageSequenceToMultipleUsersRequest = {
+  accessToken: "YOUR_ACCESS_TOKEN",
+  userIds: ["USER_1", "USER_2", "USER_3"],
+  messages: [
+    { type: "text", text: "Tin nhắn 1", delay: 1000 },
+    { type: "text", text: "Tin nhắn 2" },
+  ],
+  delayBetweenUsers: 2000, // Delay 2s giữa các user
+  onProgress, // Callback tracking
+};
+
+const result = await consultationService.sendMessageSequenceToMultipleUsers(request);
+```
+
+## Interface chi tiết
+
+### SendMessageSequenceToMultipleUsersRequest
+```typescript
+interface SendMessageSequenceToMultipleUsersRequest {
+  accessToken: string;
+  userIds: string[];                    // Danh sách user IDs
+  messages: MessageItem[];              // Chuỗi tin nhắn
+  defaultDelay?: number;                // Delay giữa tin nhắn (ms)
+  delayBetweenUsers?: number;           // Delay giữa users (ms)
+  onProgress?: (progress: UserProgressInfo) => void; // Callback tracking
+}
+```
+
+### UserProgressInfo
+```typescript
+interface UserProgressInfo {
+  userId: string;                       // User ID hiện tại
+  userIndex: number;                    // Index của user (0-based)
+  totalUsers: number;                   // Tổng số users
+  status: 'started' | 'completed' | 'failed'; // Trạng thái
+  result?: SendMessageSequenceResponse; // Kết quả (nếu completed)
+  error?: string;                       // Lỗi (nếu failed)
+  startTime: number;                    // Thời gian bắt đầu
+  endTime?: number;                     // Thời gian kết thúc
+}
+```
+
+### SendMessageSequenceToMultipleUsersResponse
+```typescript
+interface SendMessageSequenceToMultipleUsersResponse {
+  totalUsers: number;                   // Tổng số users
+  successfulUsers: number;              // Số users thành công
+  failedUsers: number;                  // Số users thất bại
+  userResults: Array<{                  // Chi tiết từng user
+    userId: string;
+    userIndex: number;
+    success: boolean;
+    messageSequenceResult?: SendMessageSequenceResponse;
+    error?: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+  }>;
+  totalDuration: number;                // Tổng thời gian (ms)
+  messageStats: {                       // Thống kê tin nhắn
+    totalSuccessfulMessages: number;
+    totalFailedMessages: number;
+    totalMessages: number;
+  };
+}
+```
+
+## Ví dụ thực tế
+
+### Marketing Campaign
+```typescript
+const marketingMessages: MessageItem[] = [
+  {
+    type: "text",
+    text: "🎉 Flash Sale 24h - Giảm 50% tất cả sản phẩm!",
+    delay: 2000,
+  },
+  {
+    type: "image",
+    imageUrl: "https://shop.com/flash-sale-banner.jpg",
+    text: "Khuyến mãi khủng - Số lượng có hạn",
+    delay: 3000,
+  },
+  {
+    type: "text",
+    text: "⏰ Chỉ còn 12 giờ! Mua ngay: https://shop.com/sale",
+  },
+];
+
+const customerIds = ["CUSTOMER_1", "CUSTOMER_2", "CUSTOMER_3"];
+
+let sentCount = 0;
+const onProgress = (progress: UserProgressInfo) => {
+  if (progress.status === 'completed') {
+    sentCount++;
+    console.log(`📤 Đã gửi cho ${sentCount}/${progress.totalUsers} khách hàng`);
+  }
+};
+
+const result = await consultationService.sendMessageSequenceToMultipleUsers({
+  accessToken: "TOKEN",
+  userIds: customerIds,
+  messages: marketingMessages,
+  delayBetweenUsers: 1500, // Tránh spam
+  onProgress,
+});
+
+console.log(`🎯 Campaign hoàn thành: ${result.successfulUsers}/${result.totalUsers} khách hàng`);
+```
+
+### Customer Support Notification
+```typescript
+const supportMessages: MessageItem[] = [
+  {
+    type: "text",
+    text: "🔧 Hệ thống sẽ bảo trì từ 2:00-4:00 sáng mai",
+    delay: 1000,
+  },
+  {
+    type: "text",
+    text: "📞 Hotline hỗ trợ 24/7: 1900-xxxx",
+  },
+];
+
+const allCustomers = ["USER_1", "USER_2", "USER_3", "USER_4"];
+
+const result = await consultationService.sendMessageSequenceToMultipleUsers({
+  accessToken: "TOKEN",
+  userIds: allCustomers,
+  messages: supportMessages,
+  delayBetweenUsers: 500,
+  onProgress: (progress) => {
+    if (progress.status === 'failed') {
+      console.log(`❌ Không gửi được cho ${progress.userId}: ${progress.error}`);
+    }
+  },
+});
+
+console.log(`📢 Thông báo đã gửi tới ${result.successfulUsers} khách hàng`);
+```
+
+## So sánh API cũ vs mới
+
+| Tính năng | API đơn user | API nhiều users |
+|-----------|-------------|-----------------|
+| Số lượng users | 1 user | Nhiều users |
+| Callback tracking | ❌ | ✅ Real-time |
+| Thống kê tổng quan | ❌ | ✅ Chi tiết |
+| Delay giữa users | ❌ | ✅ Tùy chỉnh |
+| Error handling | Dừng khi lỗi | Tiếp tục với user khác |
+| Use case | Tư vấn 1-1 | Marketing, thông báo |
+
+## Lưu ý quan trọng
+
+1. **Rate Limiting**: Sử dụng `delayBetweenUsers` để tránh hit rate limit của Zalo
+2. **Memory Usage**: Với số lượng users lớn, cân nhắc chia batch
+3. **Callback Performance**: Callback không nên thực hiện operations nặng
+4. **Error Isolation**: Lỗi của 1 user không ảnh hưởng đến users khác
+5. **Duplicate Handling**: API tự động loại bỏ user IDs trùng lặp

package/examples/send-message-sequence.ts

@@ -0,0 +1,200 @@
+import { ConsultationService, MessageItem, SendMessageSequenceRequest } from "../src/services/consultation.service";
+import { ZaloClient } from "../src/clients/zalo-client";
+
+/**
+ * Ví dụ sử dụng API gửi chuỗi tin nhắn tư vấn
+ */
+async function sendMessageSequenceExample() {
+  // Khởi tạo Zalo client và consultation service
+  const zaloClient = new ZaloClient();
+  const consultationService = new ConsultationService(zaloClient);
+
+  // Thông tin cấu hình
+  const accessToken = "YOUR_ACCESS_TOKEN";
+  const userId = "USER_ID_TO_SEND_TO";
+
+  // Định nghĩa chuỗi tin nhắn
+  const messages: MessageItem[] = [
+    // 1. Tin nhắn chào hỏi
+    {
+      type: "text",
+      text: "Xin chào! Cảm ơn bạn đã liên hệ với chúng tôi 👋",
+      delay: 2000, // Delay 2 giây sau tin nhắn này
+    },
+
+    // 2. Gửi sticker
+    {
+      type: "sticker",
+      stickerAttachmentId: "STICKER_ID",
+      delay: 1500, // Delay 1.5 giây
+    },
+
+    // 3. Tin nhắn giới thiệu dịch vụ
+    {
+      type: "text",
+      text: "Chúng tôi cung cấp các dịch vụ tư vấn chuyên nghiệp. Dưới đây là một số thông tin chi tiết:",
+      delay: 3000, // Delay 3 giây
+    },
+
+    // 4. Gửi hình ảnh minh họa
+    {
+      type: "image",
+      imageUrl: "https://example.com/service-image.jpg",
+      text: "Dịch vụ tư vấn của chúng tôi",
+      delay: 2000,
+    },
+
+    // 5. Gửi file tài liệu
+    {
+      type: "file",
+      fileToken: "FILE_TOKEN_FROM_UPLOAD_API",
+      delay: 1000,
+    },
+
+    // 6. Gửi GIF
+    {
+      type: "gif",
+      gifUrl: "https://example.com/animation.gif",
+      width: 300,
+      height: 200,
+      text: "Quy trình làm việc của chúng tôi",
+      delay: 2500,
+    },
+
+    // 7. Yêu cầu thông tin người dùng
+    {
+      type: "request_user_info",
+      title: "Đăng ký tư vấn miễn phí",
+      subtitle: "Vui lòng cung cấp thông tin để chúng tôi hỗ trợ bạn tốt nhất",
+      imageUrl: "https://example.com/consultation-form.jpg",
+      delay: 1000,
+    },
+
+    // 8. Tin nhắn kết thúc (không có delay vì là tin cuối)
+    {
+      type: "text",
+      text: "Cảm ơn bạn! Chúng tôi sẽ liên hệ lại trong thời gian sớm nhất. 🙏",
+    },
+  ];
+
+  // Tạo request
+  const request: SendMessageSequenceRequest = {
+    accessToken,
+    userId,
+    messages,
+    defaultDelay: 1000, // Delay mặc định 1 giây nếu tin nhắn không có delay riêng
+  };
+
+  try {
+    console.log("🚀 Bắt đầu gửi chuỗi tin nhắn...");
+    console.log(`📝 Tổng số tin nhắn: ${messages.length}`);
+    
+    // Gửi chuỗi tin nhắn
+    const result = await consultationService.sendMessageSequence(request);
+
+    console.log("\n✅ Kết quả gửi tin nhắn:");
+    console.log(`✅ Thành công: ${result.successCount}/${messages.length}`);
+    console.log(`❌ Thất bại: ${result.failureCount}/${messages.length}`);
+    console.log(`⏱️ Tổng thời gian: ${result.totalDuration}ms`);
+
+    // In chi tiết kết quả từng tin nhắn
+    console.log("\n📊 Chi tiết từng tin nhắn:");
+    result.results.forEach((messageResult, index) => {
+      const status = messageResult.success ? "✅" : "❌";
+      const time = new Date(messageResult.timestamp).toLocaleTimeString();
+      
+      console.log(`${status} [${index + 1}] ${messageResult.type} - ${time}`);
+      
+      if (messageResult.success && messageResult.response) {
+        console.log(`   📧 Message ID: ${messageResult.response.message_id}`);
+      }
+      
+      if (!messageResult.success && messageResult.error) {
+        console.log(`   ❌ Lỗi: ${messageResult.error}`);
+      }
+    });
+
+  } catch (error) {
+    console.error("❌ Lỗi khi gửi chuỗi tin nhắn:", error);
+  }
+}
+
+/**
+ * Ví dụ gửi chuỗi tin nhắn đơn giản chỉ có text
+ */
+async function sendSimpleTextSequence() {
+  const zaloClient = new ZaloClient();
+  const consultationService = new ConsultationService(zaloClient);
+
+  const accessToken = "YOUR_ACCESS_TOKEN";
+  const userId = "USER_ID_TO_SEND_TO";
+
+  const messages: MessageItem[] = [
+    {
+      type: "text",
+      text: "Tin nhắn đầu tiên",
+      delay: 1000,
+    },
+    {
+      type: "text", 
+      text: "Tin nhắn thứ hai",
+      delay: 1500,
+    },
+    {
+      type: "text",
+      text: "Tin nhắn cuối cùng",
+    },
+  ];
+
+  const request: SendMessageSequenceRequest = {
+    accessToken,
+    userId,
+    messages,
+  };
+
+  try {
+    const result = await consultationService.sendMessageSequence(request);
+    console.log("Kết quả:", result);
+  } catch (error) {
+    console.error("Lỗi:", error);
+  }
+}
+
+/**
+ * Ví dụ gửi chuỗi tin nhắn với delay mặc định
+ */
+async function sendSequenceWithDefaultDelay() {
+  const zaloClient = new ZaloClient();
+  const consultationService = new ConsultationService(zaloClient);
+
+  const accessToken = "YOUR_ACCESS_TOKEN";
+  const userId = "USER_ID_TO_SEND_TO";
+
+  // Các tin nhắn không có delay riêng sẽ sử dụng defaultDelay
+  const messages: MessageItem[] = [
+    { type: "text", text: "Tin nhắn 1" },
+    { type: "text", text: "Tin nhắn 2" },
+    { type: "text", text: "Tin nhắn 3" },
+  ];
+
+  const request: SendMessageSequenceRequest = {
+    accessToken,
+    userId,
+    messages,
+    defaultDelay: 2000, // Delay 2 giây giữa các tin nhắn
+  };
+
+  try {
+    const result = await consultationService.sendMessageSequence(request);
+    console.log("Kết quả:", result);
+  } catch (error) {
+    console.error("Lỗi:", error);
+  }
+}
+
+// Export các function để sử dụng
+export {
+  sendMessageSequenceExample,
+  sendSimpleTextSequence,
+  sendSequenceWithDefaultDelay,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warriorteam/redai-zalo-sdk",
-  "version": "1.17.4",
-  "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Group Messaging, Social APIs, and Enhanced Article Management with Auto-Pagination",
+  "version": "1.18.0",
+  "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Group Messaging, Social APIs, Enhanced Article Management, and Message Sequence APIs with Real-time Tracking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -33,7 +33,14 @@
     "article-management",
     "auto-pagination",
     "bulk-fetch",
-    "progress-tracking"
+    "progress-tracking",
+    "message-sequence",
+    "bulk-messaging",
+    "marketing-automation",
+    "real-time-tracking",
+    "callback-tracking",
+    "multiple-users",
+    "campaign-management"
   ],
   "author": "RedAI Team",
   "license": "MIT",