@warriorteam/redai-zalo-sdk 1.20.0 → 1.22.0

package/docs/BROADCAST_SERVICE.md

@@ -44,7 +44,37 @@ const result = await zalo.broadcast.sendBroadcastMessage(
 console.log("Message ID:", result.data.message_id);
 ```
 
-### 2. Tạo Targeting Criteria
+### 2. Gửi Nhiều Broadcast Messages
+
+```typescript
+// Gửi nhiều article attachments tuần tự
+const attachmentIds = [
+  "article-id-1",
+  "article-id-2",
+  "article-id-3"
+];
+
+const target = zalo.broadcast.createBroadcastTarget({
+  cities: ["Hồ Chí Minh"]
+});
+
+const result = await zalo.broadcast.sendMultipleBroadcastMessages(
+  accessToken,
+  { target },
+  attachmentIds,
+  {
+    mode: 'sequential',
+    delay: 2000, // 2 giây giữa các tin
+    onProgress: (progress) => {
+      console.log(`${progress.completed}/${progress.total} completed`);
+    }
+  }
+);
+
+console.log(`Sent ${result.successfulMessages}/${result.totalMessages} messages`);
+```
+
+### 3. Tạo Targeting Criteria
 
 ```typescript
 // Targeting phức tạp
@@ -184,6 +214,61 @@ const result = await zalo.broadcast.sendBroadcastMessage(
 );
 ```
 
+### 4. Gửi Nhiều Messages Song Song
+
+```typescript
+// Gửi nhiều articles cùng lúc (parallel)
+const attachmentIds = [
+  "promo-article-1",
+  "promo-article-2",
+  "promo-article-3"
+];
+
+const result = await zalo.broadcast.sendMultipleBroadcastMessages(
+  accessToken,
+  { target },
+  attachmentIds,
+  {
+    mode: 'parallel', // Gửi song song
+    onProgress: (progress) => {
+      console.log(`Progress: ${progress.completed}/${progress.total}`);
+      console.log(`Success: ${progress.successful}, Failed: ${progress.failed}`);
+    }
+  }
+);
+
+console.log("Results:", result.results.map(r => ({
+  attachmentId: r.attachmentId,
+  success: r.success,
+  messageId: r.messageId
+})));
+```
+
+### 5. Gửi Với Delay Tùy Chỉnh
+
+```typescript
+// Gửi tuần tự với delay 5 giây giữa các tin
+const result = await zalo.broadcast.sendMultipleBroadcastMessages(
+  accessToken,
+  { target },
+  attachmentIds,
+  {
+    mode: 'sequential',
+    delay: 5000, // 5 giây
+    onProgress: (progress) => {
+      if (progress.isCompleted) {
+        console.log("All messages sent!");
+      } else {
+        console.log(`Sending: ${progress.currentAttachmentId}`);
+      }
+    }
+  }
+);
+
+console.log(`Campaign completed in ${result.totalDuration}ms`);
+console.log(`Success rate: ${(result.successfulMessages / result.totalMessages * 100).toFixed(1)}%`);
+```
+
 ## Error Handling
 
 ### Các Lỗi Thường Gặp

package/docs/PROMOTION_API_V3_MIGRATION.md

@@ -0,0 +1,229 @@
+# Zalo Promotion API v3.0 Migration Guide
+
+## Tổng quan thay đổi
+
+Promotion Service đã được cập nhật để tương thích với **Zalo Official Account API v3.0**. Đây là những thay đổi chính:
+
+### 🔄 Thay đổi URL API
+- **Cũ**: `https://openapi.zalo.me/v2.0/oa/message/promotion`
+- **Mới**: `https://openapi.zalo.me/v3.0/oa/message/promotion`
+
+### 🏗️ Cấu trúc Message Elements hoàn toàn mới
+
+#### Cũ (v2.0):
+```typescript
+elements: [{
+  title: string;
+  subtitle?: string;
+  image_url?: string;
+  buttons?: Array<{...}>;
+}]
+```
+
+#### Mới (v3.0):
+```typescript
+elements: [
+  {
+    type: "banner",
+    attachment_id: "...", // hoặc image_url
+  },
+  {
+    type: "header", 
+    content: "💥💥Ưu đãi thành viên Platinum💥💥"
+  },
+  {
+    type: "text",
+    align: "left",
+    content: "Nội dung chi tiết..."
+  },
+  {
+    type: "table",
+    content: [
+      { key: "Voucher", value: "VC09279222" },
+      { key: "Hạn sử dụng", value: "30/12/2023" }
+    ]
+  }
+]
+```
+
+### 🎯 Các Element Types được hỗ trợ
+
+1. **Banner Element**
+   ```typescript
+   {
+     type: "banner",
+     attachment_id?: string,  // ID từ API upload ảnh
+     image_url?: string       // URL trực tiếp (chỉ dùng 1 trong 2)
+   }
+   ```
+
+2. **Header Element**
+   ```typescript
+   {
+     type: "header",
+     content: string,                    // Tối đa 100 ký tự
+     align?: "left" | "center" | "right" // Mặc định: left
+   }
+   ```
+
+3. **Text Element**
+   ```typescript
+   {
+     type: "text", 
+     content: string,                    // Tối đa 1000 ký tự
+     align?: "left" | "center" | "right" // Mặc định: left
+   }
+   ```
+
+4. **Table Element**
+   ```typescript
+   {
+     type: "table",
+     content: Array<{
+       key: string,    // Tối đa 25 ký tự
+       value: string   // Tối đa 100 ký tự
+     }>                // Tối đa 5 phần tử
+   }
+   ```
+
+### 🔘 Cấu trúc Buttons mới
+
+#### Cũ (v2.0):
+```typescript
+buttons: [{
+  type: string;
+  title: string;
+  url?: string;
+  payload?: string;
+}]
+```
+
+#### Mới (v3.0):
+```typescript
+buttons: [{
+  title: string,        // Tối đa 35 ký tự
+  image_icon?: string,  // URL hoặc attachment_id hoặc "default"
+  type: string,         // VD: "oa.open.url", "oa.query.hide"
+  payload: object | string  // Tùy thuộc vào type
+}]
+```
+
+**Payload format theo type:**
+- `oa.open.url`: `{ url: "https://..." }`
+- `oa.query.show`: `"#callback_data"` (string)
+- `oa.query.hide`: `"#callback_data"` (string)
+- `oa.open.sms`: `{ content: "text", phone_code: "84xxx" }`
+- `oa.open.phone`: `{ phone_code: "84xxx" }`
+
+### 🌐 Hỗ trợ đa ngôn ngữ
+
+Thêm thuộc tính `language` trong payload:
+```typescript
+{
+  template_type: "promotion",
+  language: "VI" | "EN",  // Mặc định: VI
+  elements: [...],
+  buttons: [...]
+}
+```
+
+## 📝 Cách sử dụng mới
+
+### 1. Gửi Promotion theo format chuẩn docs
+
+```typescript
+import { PromotionService } from "./services/promotion.service";
+
+const promotionService = new PromotionService(zaloClient);
+
+// Gửi promotion message theo đúng format docs v3.0
+await promotionService.sendCustomPromotion(
+  accessToken,
+  { user_id: "user_id" },
+  {
+    attachmentId: "your_attachment_id",
+    headerContent: "💥💥Ưu đãi thành viên Platinum💥💥",
+    textContent: "Ưu đãi dành riêng cho khách hàng...",
+    tableData: [
+      { key: "Voucher", value: "VC09279222" },
+      { key: "Hạn sử dụng", value: "30/12/2023" }
+    ],
+    footerText: "Áp dụng tất cả cửa hàng trên toàn quốc",
+    buttons: [
+      {
+        title: "Tham khảo chương trình",
+        type: "oa.open.url",
+        payload: { url: "https://oa.zalo.me/home" }
+      }
+    ],
+    language: "VI"
+  }
+);
+```
+
+### 2. Gửi Product Promotion (đã cập nhật)
+
+```typescript
+await promotionService.sendProductPromotion(
+  accessToken,
+  { user_id: "user_id" },
+  {
+    title: "iPhone 15 Pro Max",
+    description: "Siêu phẩm công nghệ mới nhất...",
+    attachmentId: "product_image_id", // Thay vì imageUrl
+    originalPrice: 34990000,
+    discountPrice: 29990000,
+    discountPercent: 14,
+    validUntil: "31/12/2024",
+    productUrl: "https://example.com/product"
+  }
+);
+```
+
+### 3. Gửi Event Notification (đã cập nhật)
+
+```typescript
+await promotionService.sendEventNotification(
+  accessToken,
+  { user_id: "user_id" },
+  {
+    title: "Hội thảo Digital Marketing 2024",
+    description: "Khám phá xu hướng marketing...",
+    attachmentId: "event_image_id",
+    eventDate: "15/01/2024 - 9:00 AM",
+    location: "Trung tâm Hội nghị Quốc gia, Hà Nội",
+    registrationUrl: "https://example.com/register"
+  }
+);
+```
+
+## ⚠️ Breaking Changes
+
+1. **URL API**: Phải cập nhật từ v2.0 lên v3.0
+2. **Elements Structure**: Hoàn toàn khác, không tương thích ngược
+3. **Buttons Payload**: Từ `string` thành `object`
+4. **Image Handling**: Ưu tiên `attachment_id` thay vì `image_url`
+5. **Validation**: Thêm validation cho elements và buttons
+
+## 🔍 Validation Rules
+
+- **Header content**: Tối đa 100 ký tự
+- **Text content**: Tối đa 1000 ký tự mỗi đoạn, tối đa 2 đoạn text
+- **Table**: Tối đa 5 phần tử, key ≤ 25 ký tự, value ≤ 100 ký tự
+- **Button title**: Tối đa 35 ký tự, tối đa 4 buttons
+- **Sending time**: Chỉ từ 8:00 - 22:00 hàng ngày
+
+## 📚 Examples
+
+Xem file `examples/promotion-examples.ts` để có ví dụ chi tiết về cách sử dụng tất cả các tính năng mới.
+
+## 🚀 Migration Checklist
+
+- [ ] Cập nhật URL API từ v2.0 lên v3.0
+- [ ] Thay đổi cấu trúc elements theo format mới
+- [ ] Cập nhật cấu trúc buttons với payload object
+- [ ] Thêm support cho attachment_id
+- [ ] Thêm language parameter
+- [ ] Test với các element types khác nhau
+- [ ] Kiểm tra validation rules mới
+- [ ] Cập nhật documentation và examples

package/examples/broadcast-example.ts

@@ -101,8 +101,65 @@ async function broadcastExample() {
       message: complexResult.message
     });
 
-    // Example 5: Hiển thị các mã targeting có sẵn
-    console.log("\n5. Available targeting codes:");
+    // Example 5: Gửi nhiều broadcast messages cùng lúc
+    console.log("\n5. Multiple broadcast messages (Sequential):");
+    const multipleAttachmentIds = [
+      "bd5ea46bb32e5a0033f",
+      "cd6fb57cc43f6b1144g",
+      "de7gc68dd54g7c2255h"
+    ];
+
+    const multipleTarget = zalo.broadcast.createBroadcastTarget({
+      cities: ["Hà Nội"],
+      gender: "ALL"
+    });
+
+    const multipleResult = await zalo.broadcast.sendMultipleBroadcastMessages(
+      accessToken,
+      { target: multipleTarget },
+      multipleAttachmentIds,
+      {
+        mode: 'sequential',
+        delay: 2000, // 2 seconds delay between messages
+        onProgress: (progress) => {
+          console.log(`Progress: ${progress.completed}/${progress.total} - Current: ${progress.currentAttachmentId}`);
+          console.log(`Success: ${progress.successful}, Failed: ${progress.failed}`);
+        }
+      }
+    );
+
+    console.log("Multiple broadcast result:", {
+      totalMessages: multipleResult.totalMessages,
+      successful: multipleResult.successfulMessages,
+      failed: multipleResult.failedMessages,
+      duration: `${multipleResult.totalDuration}ms`,
+      mode: multipleResult.mode
+    });
+
+    // Example 6: Gửi nhiều broadcast messages song song
+    console.log("\n6. Multiple broadcast messages (Parallel):");
+    const parallelResult = await zalo.broadcast.sendMultipleBroadcastMessages(
+      accessToken,
+      { target: multipleTarget },
+      multipleAttachmentIds,
+      {
+        mode: 'parallel',
+        onProgress: (progress) => {
+          console.log(`Parallel progress: ${progress.completed}/${progress.total}`);
+        }
+      }
+    );
+
+    console.log("Parallel broadcast result:", {
+      totalMessages: parallelResult.totalMessages,
+      successful: parallelResult.successfulMessages,
+      failed: parallelResult.failedMessages,
+      duration: `${parallelResult.totalDuration}ms`,
+      mode: parallelResult.mode
+    });
+
+    // Example 7: Hiển thị các mã targeting có sẵn
+    console.log("\n7. 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());

package/examples/promotion-examples.ts

@@ -0,0 +1,250 @@
+import { PromotionService } from "../src/services/promotion.service";
+import { ZaloClient } from "../src/clients/zalo-client";
+
+/**
+ * Examples sử dụng Promotion Service với API v3.0
+ */
+
+// Khởi tạo service
+const client = new ZaloClient();
+const promotionService = new PromotionService(client);
+
+const ACCESS_TOKEN = "your_access_token_here";
+const USER_ID = "4356639876691778517";
+
+/**
+ * Example 1: Gửi promotion message theo format chuẩn docs v3.0
+ */
+export async function sendStandardPromotion() {
+  try {
+    const result = await promotionService.sendCustomPromotion(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        attachmentId: "aERC3A0iYGgQxim8fYIK6fxzsXkaFfq7ZFRB3RCyZH6RyziRis3RNydebK3iSPCJX_cJ3k1nW1EQufjN_pUL1f6Ypq3rTef5nxp6H_HnXKFDiyD5y762HS-baqRpQe5FdA376lTfq1sRyPr8ypd74ecbaLyA-tGmuJ-97W",
+        headerContent: "💥💥Ưu đãi thành viên Platinum💥💥",
+        textContent: "Ưu đãi dành riêng cho khách hàng Nguyen Van A hạng thẻ Platinum<br>Voucher trị giá 150$",
+        tableData: [
+          {
+            key: "Voucher",
+            value: "VC09279222"
+          },
+          {
+            key: "Hạn sử dụng", 
+            value: "30/12/2023"
+          }
+        ],
+        footerText: "Áp dụng tất cả cửa hàng trên toàn quốc",
+        buttons: [
+          {
+            title: "Tham khảo chương trình",
+            imageIcon: "",
+            type: "oa.open.url",
+            payload: {
+              url: "https://oa.zalo.me/home"
+            }
+          },
+          {
+            title: "Liên hệ chăm sóc viên",
+            imageIcon: "aeqg9SYn3nIUYYeWohGI1fYRF3V9f0GHceig8Ckq4WQVcpmWb-9SL8JLPt-6gX0QbTCfSuQv40UEst1imAm53CwFPsQ1jq9MsOnlQe6rIrZOYcrlWBTAKy_UQsV9vnfGozCuOvFfIbN5rcXddFKM4sSYVM0D50I9eWy3",
+            type: "oa.query.hide",
+            payload: "#tuvan" // String trực tiếp theo docs
+          }
+        ],
+        language: "VI"
+      }
+    );
+
+    console.log("Promotion sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send promotion:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 2: Gửi product promotion
+ */
+export async function sendProductPromotion() {
+  try {
+    const result = await promotionService.sendProductPromotion(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        title: "iPhone 15 Pro Max",
+        description: "Siêu phẩm công nghệ mới nhất từ Apple với chip A17 Pro mạnh mẽ",
+        attachmentId: "your_product_image_attachment_id",
+        originalPrice: 34990000,
+        discountPrice: 29990000,
+        discountPercent: 14,
+        validUntil: "31/12/2024",
+        productUrl: "https://example.com/iphone-15-pro-max"
+      }
+    );
+
+    console.log("Product promotion sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send product promotion:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 3: Gửi event notification
+ */
+export async function sendEventNotification() {
+  try {
+    const result = await promotionService.sendEventNotification(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        title: "Hội thảo Digital Marketing 2024",
+        description: "Khám phá xu hướng marketing số mới nhất và chiến lược tăng trưởng bền vững",
+        attachmentId: "your_event_image_attachment_id",
+        eventDate: "15/01/2024 - 9:00 AM",
+        location: "Trung tâm Hội nghị Quốc gia, Hà Nội",
+        registrationUrl: "https://example.com/register-event"
+      }
+    );
+
+    console.log("Event notification sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send event notification:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 4: Gửi newsletter
+ */
+export async function sendNewsletter() {
+  try {
+    const result = await promotionService.sendNewsletter(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        title: "Bản tin công nghệ tuần 52/2024",
+        summary: "Cập nhật những tin tức công nghệ hot nhất trong tuần qua",
+        attachmentId: "your_newsletter_image_attachment_id",
+        articles: [
+          {
+            title: "AI và tương lai của lập trình",
+            url: "https://example.com/ai-programming-future"
+          },
+          {
+            title: "Blockchain trong fintech",
+            url: "https://example.com/blockchain-fintech"
+          },
+          {
+            title: "IoT và smart city",
+            url: "https://example.com/iot-smart-city"
+          }
+        ],
+        unsubscribeUrl: "https://example.com/unsubscribe"
+      }
+    );
+
+    console.log("Newsletter sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send newsletter:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example 5: Demo tất cả button types
+ */
+export async function sendAllButtonTypes() {
+  try {
+    const result = await promotionService.sendCustomPromotion(
+      ACCESS_TOKEN,
+      { user_id: USER_ID },
+      {
+        attachmentId: "your_attachment_id",
+        headerContent: "🔘 Demo tất cả button types",
+        textContent: "Thử nghiệm các loại button được hỗ trợ trong Zalo API v3.0",
+        tableData: [
+          { key: "Button types", value: "5 loại" },
+          { key: "Tính năng", value: "Chỉ trên Mobile" }
+        ],
+        buttons: [
+          {
+            title: "Mở URL",
+            type: "oa.open.url",
+            payload: { url: "https://developers.zalo.me/" }
+          },
+          {
+            title: "Query Show",
+            type: "oa.query.show",
+            payload: "#callback_show"
+          },
+          {
+            title: "Query Hide",
+            type: "oa.query.hide",
+            payload: "#callback_hide"
+          },
+          {
+            title: "Gửi SMS",
+            type: "oa.open.sms",
+            payload: {
+              content: "Xin chào từ Zalo OA",
+              phone_code: "84919018791"
+            }
+          },
+          {
+            title: "Gọi điện",
+            type: "oa.open.phone",
+            payload: { phone_code: "84919018791" }
+          }
+        ],
+        language: "VI"
+      }
+    );
+
+    console.log("All button types demo sent successfully:", result);
+    return result;
+  } catch (error) {
+    console.error("Failed to send all button types demo:", error);
+    throw error;
+  }
+}
+
+/**
+ * Chạy tất cả examples
+ */
+export async function runAllExamples() {
+  console.log("=== Zalo Promotion API v3.0 Examples ===\n");
+
+  try {
+    console.log("1. Sending standard promotion...");
+    await sendStandardPromotion();
+    console.log("✅ Standard promotion sent\n");
+
+    console.log("2. Sending product promotion...");
+    await sendProductPromotion();
+    console.log("✅ Product promotion sent\n");
+
+    console.log("3. Sending event notification...");
+    await sendEventNotification();
+    console.log("✅ Event notification sent\n");
+
+    console.log("4. Sending newsletter...");
+    await sendNewsletter();
+    console.log("✅ Newsletter sent\n");
+
+    console.log("5. Sending all button types demo...");
+    await sendAllButtonTypes();
+    console.log("✅ All button types demo sent\n");
+
+    console.log("🎉 All examples completed successfully!");
+  } catch (error) {
+    console.error("❌ Error running examples:", error);
+  }
+}
+
+// Uncomment để chạy examples
+// runAllExamples();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warriorteam/redai-zalo-sdk",
-  "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",
+  "version": "1.22.0",
+  "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account v3.0, ZNS, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, Promotion Service v3.0, and Message Sequence APIs with Real-time Tracking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -48,7 +48,14 @@
     "bulk-group-messaging",
     "group-notifications",
     "team-communication",
-    "group-automation"
+    "group-automation",
+    "promotion-service",
+    "promotion-v3",
+    "zalo-v3",
+    "banner-element",
+    "table-element",
+    "multi-language",
+    "button-actions"
   ],
   "author": "RedAI Team",
   "license": "MIT",