@warriorteam/redai-zalo-sdk 1.19.0 → 1.20.0

package/docs/BROADCAST_SERVICE.md

@@ -0,0 +1,276 @@
+# RedAI Zalo SDK - Broadcast Service Guide
+
+## Tổng quan
+
+BroadcastService cho phép gửi tin truyền thông broadcast đến nhiều người dùng cùng lúc dựa trên các tiêu chí targeting như tuổi, giới tính, địa điểm, và platform.
+
+## API Endpoint
+
+- **URL**: `https://openapi.zalo.me/v2.0/oa/message`
+- **Method**: POST
+- **Content-Type**: application/json
+- **Header**: `access_token: <your_access_token>`
+
+## Khởi tạo Service
+
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret"
+});
+
+// Access broadcast service
+const broadcastService = zalo.broadcast;
+```
+
+## Các Phương Thức Chính
+
+### 1. Gửi Broadcast Message
+
+```typescript
+// Gửi broadcast đến người dùng ở Hồ Chí Minh
+const target = zalo.broadcast.createBroadcastTarget({
+  cities: ["Hồ Chí Minh"]
+});
+
+const result = await zalo.broadcast.sendBroadcastMessage(
+  accessToken,
+  { target },
+  "article-attachment-id"
+);
+
+console.log("Message ID:", result.data.message_id);
+```
+
+### 2. Tạo Targeting Criteria
+
+```typescript
+// Targeting phức tạp
+const complexTarget = zalo.broadcast.createBroadcastTarget({
+  gender: "FEMALE",           // Nữ giới
+  ages: ["18-24", "25-34"],   // Tuổi 18-34
+  cities: ["Hà Nội", "Đà Nẵng"], // Hà Nội và Đà Nẵng
+  platform: ["ANDROID", "IOS"]   // Android và iOS
+});
+```
+
+## Targeting Criteria
+
+### 1. Nhóm Tuổi (Ages)
+
+| Nhóm tuổi | Mã | Mô tả |
+|-----------|----|----|
+| `"0-12"` | `"0"` | Tuổi từ 0-12 |
+| `"13-17"` | `"1"` | Tuổi từ 13-17 |
+| `"18-24"` | `"2"` | Tuổi từ 18-24 |
+| `"25-34"` | `"3"` | Tuổi từ 25-34 |
+| `"35-44"` | `"4"` | Tuổi từ 35-44 |
+| `"45-54"` | `"5"` | Tuổi từ 45-54 |
+| `"55-64"` | `"6"` | Tuổi từ 55-64 |
+| `"65+"` | `"7"` | Tuổi từ 65 trở lên |
+
+```typescript
+const target = zalo.broadcast.createBroadcastTarget({
+  ages: ["18-24", "25-34"] // Targeting 18-34 tuổi
+});
+```
+
+### 2. Giới Tính (Gender)
+
+| Giới tính | Mã | Mô tả |
+|-----------|----|----|
+| `"ALL"` | `"0"` | Tất cả giới tính |
+| `"MALE"` | `"1"` | Nam |
+| `"FEMALE"` | `"2"` | Nữ |
+
+```typescript
+const target = zalo.broadcast.createBroadcastTarget({
+  gender: "MALE" // Chỉ targeting nam giới
+});
+```
+
+### 3. Tỉnh Thành (Cities)
+
+Hỗ trợ 63 tỉnh thành Việt Nam:
+
+```typescript
+const target = zalo.broadcast.createBroadcastTarget({
+  cities: ["Hồ Chí Minh", "Hà Nội", "Đà Nẵng"]
+});
+
+// Xem tất cả mã tỉnh thành
+const cityCodes = zalo.broadcast.getCityCodes();
+console.log(cityCodes);
+```
+
+### 4. Miền (Locations)
+
+| Miền | Mã | Mô tả |
+|------|----|----|
+| `"NORTH"` | `"0"` | Miền Bắc |
+| `"CENTRAL"` | `"1"` | Miền Trung |
+| `"SOUTH"` | `"2"` | Miền Nam |
+
+```typescript
+const target = zalo.broadcast.createBroadcastTarget({
+  locations: ["SOUTH"] // Chỉ miền Nam
+});
+```
+
+### 5. Platform
+
+| Platform | Mã | Mô tả |
+|----------|----|----|
+| `"IOS"` | `"1"` | iOS |
+| `"ANDROID"` | `"2"` | Android |
+| `"WINDOWS_PHONE"` | `"3"` | Windows Phone |
+
+```typescript
+const target = zalo.broadcast.createBroadcastTarget({
+  platforms: ["IOS", "ANDROID"] // iOS và Android
+});
+```
+
+## Ví Dụ Sử Dụng
+
+### 1. Broadcast Đơn Giản
+
+```typescript
+// Gửi đến tất cả người dùng ở Hồ Chí Minh
+const target = zalo.broadcast.createBroadcastTarget({
+  cities: ["Hồ Chí Minh"]
+});
+
+const result = await zalo.broadcast.sendBroadcastMessage(
+  accessToken,
+  { target },
+  "bd5ea46bb32e5a0033f"
+);
+```
+
+### 2. Targeting Theo Nhân Khẩu Học
+
+```typescript
+// Nữ giới 25-34 tuổi
+const target = zalo.broadcast.createBroadcastTarget({
+  gender: "FEMALE",
+  ages: ["25-34"]
+});
+
+const result = await zalo.broadcast.sendBroadcastMessage(
+  accessToken,
+  { target },
+  "article-id"
+);
+```
+
+### 3. Targeting Phức Tạp
+
+```typescript
+// Nam giới 18-34 tuổi, dùng iOS, ở miền Nam
+const target = zalo.broadcast.createBroadcastTarget({
+  gender: "MALE",
+  ages: ["18-24", "25-34"],
+  platforms: ["IOS"],
+  locations: ["SOUTH"]
+});
+
+const result = await zalo.broadcast.sendBroadcastMessage(
+  accessToken,
+  { target },
+  "article-id"
+);
+```
+
+## Error Handling
+
+### Các Lỗi Thường Gặp
+
+| Mã lỗi | Mô tả | Giải pháp |
+|--------|-------|-----------|
+| `3001` | Không có quyền broadcast | Liên hệ Zalo để được cấp quyền |
+| `3002` | Article không tồn tại | Kiểm tra attachment_id |
+| `3003` | Targeting không hợp lệ | Kiểm tra các tham số targeting |
+| `3004` | Vượt quota broadcast | Chờ reset quota hoặc nâng cấp |
+| `3005` | Vi phạm chính sách | Kiểm tra nội dung article |
+
+```typescript
+try {
+  const result = await zalo.broadcast.sendBroadcastMessage(
+    accessToken,
+    { target },
+    articleId
+  );
+  console.log("Success:", result.data.message_id);
+} catch (error) {
+  switch (error.code) {
+    case 3001:
+      console.error("Không có quyền broadcast");
+      break;
+    case 3002:
+      console.error("Article không tồn tại");
+      break;
+    default:
+      console.error("Lỗi khác:", error.message);
+  }
+}
+```
+
+## Yêu Cầu và Giới Hạn
+
+### 1. Quyền Broadcast
+- OA phải được Zalo cấp quyền gửi broadcast
+- Cần tuân thủ chính sách về spam và nội dung
+
+### 2. Article Attachment
+- Chỉ hỗ trợ template type `"media"` với `media_type: "article"`
+- Article phải được tạo trước và có attachment_id hợp lệ
+
+### 3. Targeting
+- Phải có ít nhất 1 tiêu chí targeting
+- Có thể kết hợp nhiều tiêu chí cùng lúc
+
+### 4. Rate Limiting
+- Tuân thủ giới hạn số lượng broadcast theo gói dịch vụ
+- Tránh gửi quá nhiều broadcast trong thời gian ngắn
+
+## Best Practices
+
+### 1. Targeting Hiệu Quả
+```typescript
+// Tốt: Targeting cụ thể
+const target = zalo.broadcast.createBroadcastTarget({
+  gender: "FEMALE",
+  ages: ["25-34"],
+  cities: ["Hồ Chí Minh"]
+});
+
+// Tránh: Targeting quá rộng
+const broadTarget = zalo.broadcast.createBroadcastTarget({
+  gender: "ALL" // Quá rộng, có thể bị spam
+});
+```
+
+### 2. Nội Dung Chất Lượng
+- Sử dụng article có nội dung hữu ích
+- Tránh nội dung spam hoặc quảng cáo quá mức
+- Tuân thủ chính sách của Zalo
+
+### 3. Monitoring và Analytics
+```typescript
+// Lưu message_id để tracking
+const result = await zalo.broadcast.sendBroadcastMessage(
+  accessToken,
+  { target },
+  articleId
+);
+
+// Lưu vào database để theo dõi
+await saveBroadcastLog({
+  messageId: result.data.message_id,
+  targetCriteria: target,
+  sentAt: new Date()
+});
+```

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warriorteam/redai-zalo-sdk",
-  "version": "1.19.0",
-  "description": "Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Group Messaging with List APIs, 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",