@warriorteam/redai-zalo-sdk 1.18.0 → 1.20.0

package/examples/broadcast-example.ts

@@ -0,0 +1,144 @@
+/**
+ * Broadcast Message Example
+ * 
+ * Ví dụ về cách sử dụng BroadcastService để gửi tin truyền thông broadcast
+ * đến nhiều người dùng dựa trên tiêu chí targeting
+ */
+
+import { ZaloSDK } from "../src/index";
+
+async function broadcastExample() {
+  // Khởi tạo SDK
+  const zalo = new ZaloSDK({
+    appId: "your-app-id",
+    appSecret: "your-app-secret",
+    debug: true
+  });
+
+  // Access token của OA (cần có quyền broadcast)
+  const accessToken = "your-oa-access-token";
+  
+  // ID của article attachment đã được tạo trước
+  const articleAttachmentId = "bd5ea46bb32e5a0033f";
+
+  try {
+    console.log("=== Broadcast Message Examples ===\n");
+
+    // Example 1: Broadcast đến tất cả người dùng ở Hồ Chí Minh
+    console.log("1. Broadcast to Ho Chi Minh City users:");
+    const hcmTarget = zalo.broadcast.createBroadcastTarget({
+      cities: ["Hồ Chí Minh"]
+    });
+
+    const hcmResult = await zalo.broadcast.sendBroadcastMessage(
+      accessToken,
+      { target: hcmTarget },
+      articleAttachmentId
+    );
+
+    console.log("HCM broadcast result:", {
+      messageId: hcmResult.data.message_id,
+      error: hcmResult.error,
+      message: hcmResult.message
+    });
+
+    // Example 2: Broadcast đến nam giới 25-34 tuổi
+    console.log("\n2. Broadcast to male users aged 25-34:");
+    const maleTarget = zalo.broadcast.createBroadcastTarget({
+      gender: "MALE",
+      ages: ["25-34"]
+    });
+
+    const maleResult = await zalo.broadcast.sendBroadcastMessage(
+      accessToken,
+      { target: maleTarget },
+      articleAttachmentId
+    );
+
+    console.log("Male 25-34 broadcast result:", {
+      messageId: maleResult.data.message_id,
+      error: maleResult.error,
+      message: maleResult.message
+    });
+
+    // Example 3: Broadcast đến người dùng iOS ở miền Nam
+    console.log("\n3. Broadcast to iOS users in South Vietnam:");
+    const iosTarget = zalo.broadcast.createBroadcastTarget({
+      platform: ["IOS"],
+      locations: ["SOUTH"]
+    });
+
+    const iosResult = await zalo.broadcast.sendBroadcastMessage(
+      accessToken,
+      { target: iosTarget },
+      articleAttachmentId
+    );
+
+    console.log("iOS South broadcast result:", {
+      messageId: iosResult.data.message_id,
+      error: iosResult.error,
+      message: iosResult.message
+    });
+
+    // Example 4: Broadcast phức tạp - Nữ giới 18-24 tuổi, dùng Android, ở Hà Nội và Đà Nẵng
+    console.log("\n4. Complex targeting broadcast:");
+    const complexTarget = zalo.broadcast.createBroadcastTarget({
+      gender: "FEMALE",
+      ages: ["18-24"],
+      platform: ["ANDROID"],
+      cities: ["Hà Nội", "Đà Nẵng"]
+    });
+
+    const complexResult = await zalo.broadcast.sendBroadcastMessage(
+      accessToken,
+      { target: complexTarget },
+      articleAttachmentId
+    );
+
+    console.log("Complex targeting broadcast result:", {
+      messageId: complexResult.data.message_id,
+      error: complexResult.error,
+      message: complexResult.message
+    });
+
+    // Example 5: Hiển thị các mã targeting có sẵn
+    console.log("\n5. Available targeting codes:");
+    console.log("City codes:", Object.keys(zalo.broadcast.getCityCodes()).slice(0, 10), "...");
+    console.log("Age group codes:", zalo.broadcast.getAgeGroupCodes());
+    console.log("Gender codes:", zalo.broadcast.getGenderCodes());
+    console.log("Location codes:", zalo.broadcast.getLocationCodes());
+    console.log("Platform codes:", zalo.broadcast.getPlatformCodes());
+
+  } catch (error) {
+    console.error("Broadcast error:", error);
+    
+    if (error.code) {
+      switch (error.code) {
+        case 3001:
+          console.error("Không có quyền gửi broadcast. Liên hệ Zalo để được cấp quyền.");
+          break;
+        case 3002:
+          console.error("Article attachment không tồn tại hoặc đã hết hạn.");
+          break;
+        case 3003:
+          console.error("Targeting criteria không hợp lệ.");
+          break;
+        case 3004:
+          console.error("Vượt quá giới hạn broadcast cho phép.");
+          break;
+        case 3005:
+          console.error("Nội dung vi phạm chính sách Zalo.");
+          break;
+        default:
+          console.error("Lỗi không xác định:", error.message);
+      }
+    }
+  }
+}
+
+// Chạy example nếu file được execute trực tiếp
+if (require.main === module) {
+  broadcastExample().catch(console.error);
+}
+
+export { broadcastExample };

package/examples/group-message-list.ts

@@ -0,0 +1,288 @@
+import { 
+  GroupMessageService, 
+  GroupMessageItem, 
+  SendMessageListToGroupRequest,
+  SendMessageListToMultipleGroupsRequest,
+  GroupMessageProgressInfo,
+  MultipleGroupsProgressInfo 
+} from "../src/services/group-message.service";
+import { ZaloClient } from "../src/clients/zalo-client";
+
+/**
+ * Ví dụ sử dụng API gửi danh sách tin nhắn tới 1 group với callback tracking
+ */
+async function sendMessageListToGroupExample() {
+  // Khởi tạo Zalo client và group message service
+  const zaloClient = new ZaloClient();
+  const groupMessageService = new GroupMessageService(zaloClient);
+
+  // Thông tin cấu hình
+  const accessToken = "YOUR_ACCESS_TOKEN";
+  const groupId = "GROUP_ID_TO_SEND_TO";
+
+  // Định nghĩa danh sách tin nhắn thông báo
+  const messages: GroupMessageItem[] = [
+    {
+      type: "text",
+      text: "📢 THÔNG BÁO QUAN TRỌNG",
+      delay: 2000,
+    },
+    {
+      type: "text",
+      text: "🔧 Hệ thống sẽ bảo trì từ 2:00 - 4:00 sáng ngày mai (15/09/2024)",
+      delay: 1500,
+    },
+    {
+      type: "image",
+      imageUrl: "https://example.com/maintenance-schedule.jpg",
+      caption: "Lịch trình bảo trì chi tiết",
+      delay: 2000,
+    },
+    {
+      type: "text",
+      text: "⚠️ Trong thời gian bảo trì, các dịch vụ sau sẽ tạm ngưng:\n• Website chính\n• Mobile App\n• API Services",
+      delay: 1500,
+    },
+    {
+      type: "sticker",
+      stickerId: "MAINTENANCE_STICKER_ID",
+      delay: 1000,
+    },
+    {
+      type: "text",
+      text: "📞 Hotline hỗ trợ khẩn cấp: 1900-xxxx\n📧 Email: support@company.com",
+    },
+  ];
+
+  // Callback function để tracking tiến trình
+  const onProgress = (progress: GroupMessageProgressInfo) => {
+    const percentage = Math.round(((progress.messageIndex + 1) / progress.totalMessages) * 100);
+    
+    switch (progress.status) {
+      case 'started':
+        console.log(`🚀 [${percentage}%] Bắt đầu gửi tin nhắn ${progress.messageIndex + 1}/${progress.totalMessages} (${progress.messageType})`);
+        break;
+        
+      case 'completed':
+        const duration = progress.endTime ? progress.endTime - progress.startTime : 0;
+        console.log(`✅ [${percentage}%] Hoàn thành tin nhắn ${progress.messageIndex + 1}/${progress.totalMessages} - ${duration}ms`);
+        break;
+        
+      case 'failed':
+        const failDuration = progress.endTime ? progress.endTime - progress.startTime : 0;
+        console.log(`❌ [${percentage}%] Thất bại tin nhắn ${progress.messageIndex + 1}/${progress.totalMessages} - ${failDuration}ms - Lỗi: ${progress.error}`);
+        break;
+    }
+  };
+
+  // Tạo request
+  const request: SendMessageListToGroupRequest = {
+    accessToken,
+    groupId,
+    messages,
+    defaultDelay: 1000, // Delay mặc định 1 giây giữa các tin nhắn
+    onProgress, // Callback tracking
+  };
+
+  try {
+    console.log("📢 Bắt đầu gửi danh sách tin nhắn thông báo tới group...");
+    console.log(`👥 Group ID: ${groupId}`);
+    console.log(`📝 Tổng số tin nhắn: ${messages.length}`);
+    console.log("─".repeat(60));
+    
+    // Gửi danh sách tin nhắn tới group
+    const result = await groupMessageService.sendMessageListToGroup(request);
+
+    console.log("─".repeat(60));
+    console.log("🎊 KẾT QUẢ:");
+    console.log(`📝 Tổng tin nhắn: ${result.totalMessages}`);
+    console.log(`✅ Thành công: ${result.successfulMessages} (${Math.round((result.successfulMessages / result.totalMessages) * 100)}%)`);
+    console.log(`❌ Thất bại: ${result.failedMessages} (${Math.round((result.failedMessages / result.totalMessages) * 100)}%)`);
+    console.log(`⏱️ Tổng thời gian: ${result.totalDuration}ms (${Math.round(result.totalDuration / 1000)}s)`);
+
+    // In chi tiết từng tin nhắn
+    console.log("\n📋 CHI TIẾT TỪNG TIN NHẮN:");
+    result.messageResults.forEach((messageResult, index) => {
+      const status = messageResult.success ? "✅" : "❌";
+      console.log(`${status} [${index + 1}] ${messageResult.messageType} - ${messageResult.duration}ms`);
+      
+      if (!messageResult.success && messageResult.error) {
+        console.log(`   ❌ Lỗi: ${messageResult.error}`);
+      }
+    });
+
+  } catch (error) {
+    console.error("❌ Lỗi khi gửi danh sách tin nhắn tới group:", error);
+  }
+}
+
+/**
+ * Ví dụ gửi danh sách tin nhắn tới nhiều groups
+ */
+async function sendMessageListToMultipleGroupsExample() {
+  const zaloClient = new ZaloClient();
+  const groupMessageService = new GroupMessageService(zaloClient);
+
+  const accessToken = "YOUR_ACCESS_TOKEN";
+  const groupIds = [
+    "GROUP_ID_1",
+    "GROUP_ID_2", 
+    "GROUP_ID_3",
+    "GROUP_ID_4"
+  ];
+
+  // Danh sách tin nhắn marketing
+  const messages: GroupMessageItem[] = [
+    {
+      type: "text",
+      text: "🎉 FLASH SALE 24H - GIẢM GIÁ SỐC!",
+      delay: 2000,
+    },
+    {
+      type: "image",
+      imageUrl: "https://example.com/flash-sale-banner.jpg",
+      caption: "🔥 Giảm tới 70% + Freeship toàn quốc",
+      delay: 3000,
+    },
+    {
+      type: "text",
+      text: "⏰ Chỉ còn 12 giờ! Số lượng có hạn!\n🛒 Mua ngay: https://shop.example.com/flash-sale",
+      delay: 1500,
+    },
+    {
+      type: "sticker",
+      stickerId: "SALE_STICKER_ID",
+    },
+  ];
+
+  // Callback tracking cho multiple groups
+  let completedGroups = 0;
+  const onProgress = (progress: MultipleGroupsProgressInfo) => {
+    switch (progress.status) {
+      case 'started':
+        console.log(`🎯 Bắt đầu gửi tới Group ${progress.groupIndex + 1}/${progress.totalGroups} (${progress.groupId})`);
+        break;
+        
+      case 'completed':
+        completedGroups++;
+        const successRate = progress.result ? 
+          Math.round((progress.result.successfulMessages / progress.result.totalMessages) * 100) : 0;
+        console.log(`✅ Hoàn thành Group ${completedGroups}/${progress.totalGroups} - Thành công: ${successRate}%`);
+        break;
+        
+      case 'failed':
+        console.log(`❌ Thất bại Group ${progress.groupIndex + 1}/${progress.totalGroups} - Lỗi: ${progress.error}`);
+        break;
+    }
+  };
+
+  const request: SendMessageListToMultipleGroupsRequest = {
+    accessToken,
+    groupIds,
+    messages,
+    defaultDelay: 1000, // Delay giữa tin nhắn
+    delayBetweenGroups: 3000, // Delay 3 giây giữa các groups
+    onProgress,
+  };
+
+  try {
+    console.log("🎯 Bắt đầu chiến dịch marketing tới nhiều groups...");
+    console.log(`👥 Tổng số groups: ${groupIds.length}`);
+    console.log(`📝 Tổng số tin nhắn mỗi group: ${messages.length}`);
+    console.log(`📊 Tổng số tin nhắn sẽ gửi: ${groupIds.length * messages.length}`);
+    console.log("─".repeat(60));
+    
+    const result = await groupMessageService.sendMessageListToMultipleGroups(request);
+
+    console.log("─".repeat(60));
+    console.log("🎊 KẾT QUẢ TỔNG QUAN:");
+    console.log(`👥 Tổng groups: ${result.totalGroups}`);
+    console.log(`✅ Groups thành công: ${result.successfulGroups} (${Math.round((result.successfulGroups / result.totalGroups) * 100)}%)`);
+    console.log(`❌ Groups thất bại: ${result.failedGroups} (${Math.round((result.failedGroups / result.totalGroups) * 100)}%)`);
+    console.log(`⏱️ Tổng thời gian: ${result.totalDuration}ms (${Math.round(result.totalDuration / 1000)}s)`);
+    
+    console.log("\n📊 THỐNG KÊ TIN NHẮN:");
+    console.log(`✅ Tin nhắn thành công: ${result.messageStats.totalSuccessfulMessages}`);
+    console.log(`❌ Tin nhắn thất bại: ${result.messageStats.totalFailedMessages}`);
+    console.log(`📝 Tổng tin nhắn: ${result.messageStats.totalMessages}`);
+    console.log(`📈 Tỷ lệ thành công: ${Math.round((result.messageStats.totalSuccessfulMessages / result.messageStats.totalMessages) * 100)}%`);
+
+    // In chi tiết từng group
+    console.log("\n📋 CHI TIẾT TỪNG GROUP:");
+    result.groupResults.forEach((groupResult, index) => {
+      const status = groupResult.success ? "✅" : "❌";
+      const successRate = groupResult.messageListResult ? 
+        Math.round((groupResult.messageListResult.successfulMessages / groupResult.messageListResult.totalMessages) * 100) : 0;
+      
+      console.log(`${status} Group ${index + 1}: ${groupResult.groupId} - ${groupResult.duration}ms - Thành công: ${successRate}%`);
+      
+      if (!groupResult.success && groupResult.error) {
+        console.log(`   ❌ Lỗi: ${groupResult.error}`);
+      }
+    });
+
+  } catch (error) {
+    console.error("❌ Lỗi khi gửi danh sách tin nhắn tới nhiều groups:", error);
+  }
+}
+
+/**
+ * Ví dụ gửi tin nhắn mention tới group
+ */
+async function sendMentionMessageListExample() {
+  const zaloClient = new ZaloClient();
+  const groupMessageService = new GroupMessageService(zaloClient);
+
+  const accessToken = "YOUR_ACCESS_TOKEN";
+  const groupId = "GROUP_ID";
+
+  const messages: GroupMessageItem[] = [
+    {
+      type: "text",
+      text: "🎯 Cuộc họp quan trọng sắp diễn ra!",
+      delay: 1000,
+    },
+    {
+      type: "mention",
+      text: "@Admin @Manager Vui lòng chuẩn bị tài liệu cho cuộc họp lúc 14:00",
+      mentions: [
+        { user_id: "ADMIN_USER_ID", offset: 0, length: 6 },
+        { user_id: "MANAGER_USER_ID", offset: 7, length: 8 }
+      ],
+      delay: 2000,
+    },
+    {
+      type: "text",
+      text: "📋 Agenda:\n1. Báo cáo tháng\n2. Kế hoạch quý mới\n3. Q&A",
+    },
+  ];
+
+  const onProgress = (progress: GroupMessageProgressInfo) => {
+    if (progress.status === 'completed') {
+      console.log(`✅ Đã gửi tin nhắn ${progress.messageIndex + 1}: ${progress.messageType}`);
+    } else if (progress.status === 'failed') {
+      console.log(`❌ Gửi thất bại tin nhắn ${progress.messageIndex + 1}: ${progress.error}`);
+    }
+  };
+
+  try {
+    const result = await groupMessageService.sendMessageListToGroup({
+      accessToken,
+      groupId,
+      messages,
+      defaultDelay: 1500,
+      onProgress,
+    });
+
+    console.log(`\n📢 Đã gửi thông báo cuộc họp: ${result.successfulMessages}/${result.totalMessages} tin nhắn thành công`);
+  } catch (error) {
+    console.error("❌ Lỗi gửi thông báo cuộc họp:", error);
+  }
+}
+
+// Export các function để sử dụng
+export {
+  sendMessageListToGroupExample,
+  sendMessageListToMultipleGroupsExample,
+  sendMentionMessageListExample,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warriorteam/redai-zalo-sdk",
-  "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",
+  "version": "1.20.0",
+  "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, and Message Sequence APIs with Real-time Tracking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -28,6 +28,8 @@
     "official-account",
     "notification-service",
     "consultation-service",
+    "broadcast-service",
+    "mass-communication",
     "customer-support",
     "messaging",
     "article-management",
@@ -40,7 +42,13 @@
     "real-time-tracking",
     "callback-tracking",
     "multiple-users",
-    "campaign-management"
+    "campaign-management",
+    "group-messaging",
+    "group-message-list",
+    "bulk-group-messaging",
+    "group-notifications",
+    "team-communication",
+    "group-automation"
   ],
   "author": "RedAI Team",
   "license": "MIT",