@warriorteam/redai-zalo-sdk 1.18.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/docs/group-message-list-api.md

@@ -0,0 +1,332 @@
+# API Gửi Danh Sách Tin Nhắn Group
+
+API mở rộng cho phép gửi danh sách tin nhắn tới groups với callback tracking real-time.
+
+## Tính năng
+
+- ✅ Gửi danh sách tin nhắn tới 1 group
+- ✅ Gửi danh sách tin nhắn tới nhiều groups cùng lúc
+- ✅ Hỗ trợ đầy đủ 5 loại tin nhắn: text, image, file, sticker, mention
+- ✅ Callback tracking real-time cho từng tin nhắn/group
+- ✅ Delay tùy chỉnh giữa tin nhắn và giữa groups
+- ✅ Thống kê chi tiết thành công/thất bại
+- ✅ Error isolation - lỗi 1 tin nhắn/group không ảnh hưởng phần còn lại
+
+## Cách sử dụng
+
+### 1. Import các interface và service
+
+```typescript
+import { 
+  GroupMessageService, 
+  GroupMessageItem, 
+  SendMessageListToGroupRequest,
+  SendMessageListToMultipleGroupsRequest 
+} from "../src/services/group-message.service";
+import { ZaloClient } from "../src/clients/zalo-client";
+```
+
+### 2. Khởi tạo service
+
+```typescript
+const zaloClient = new ZaloClient();
+const groupMessageService = new GroupMessageService(zaloClient);
+```
+
+### 3. Định nghĩa danh sách tin nhắn
+
+```typescript
+const messages: GroupMessageItem[] = [
+  {
+    type: "text",
+    text: "📢 Thông báo quan trọng!",
+    delay: 2000, // Delay 2 giây sau tin nhắn này
+  },
+  {
+    type: "image",
+    imageUrl: "https://example.com/image.jpg",
+    caption: "Hình ảnh minh họa",
+    delay: 1500,
+  },
+  {
+    type: "mention",
+    text: "@Admin Vui lòng xem thông báo",
+    mentions: [
+      { user_id: "ADMIN_ID", offset: 0, length: 6 }
+    ],
+  },
+];
+```
+
+### 4. Gửi tới 1 group
+
+```typescript
+const result = await groupMessageService.sendMessageListToGroup({
+  accessToken: "YOUR_ACCESS_TOKEN",
+  groupId: "GROUP_ID",
+  messages,
+  defaultDelay: 1000,
+  onProgress: (progress) => {
+    console.log(`${progress.status}: Message ${progress.messageIndex + 1}/${progress.totalMessages}`);
+  }
+});
+
+console.log(`Thành công: ${result.successfulMessages}/${result.totalMessages} tin nhắn`);
+```
+
+### 5. Gửi tới nhiều groups
+
+```typescript
+const result = await groupMessageService.sendMessageListToMultipleGroups({
+  accessToken: "YOUR_ACCESS_TOKEN",
+  groupIds: ["GROUP_1", "GROUP_2", "GROUP_3"],
+  messages,
+  defaultDelay: 1000,
+  delayBetweenGroups: 3000, // Delay 3s giữa các groups
+  onProgress: (progress) => {
+    console.log(`${progress.status}: Group ${progress.groupIndex + 1}/${progress.totalGroups}`);
+  }
+});
+
+console.log(`Thành công: ${result.successfulGroups}/${result.totalGroups} groups`);
+```
+
+## 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",
+  caption: "Caption cho ảnh", // Optional, max 2000 ký tự
+  delay: 1500,
+}
+
+// Hoặc sử dụng attachment ID
+{
+  type: "image",
+  attachmentId: "ATTACHMENT_ID",
+  caption: "Caption cho ảnh",
+  delay: 1500,
+}
+```
+
+### 3. File Message
+```typescript
+{
+  type: "file",
+  fileToken: "FILE_TOKEN_FROM_UPLOAD_API", // Bắt buộc
+  fileName: "document.pdf", // Optional
+  delay: 1000,
+}
+```
+
+### 4. Sticker Message
+```typescript
+{
+  type: "sticker",
+  stickerId: "STICKER_ID", // Bắt buộc
+  delay: 500,
+}
+```
+
+### 5. Mention Message
+```typescript
+{
+  type: "mention",
+  text: "@Admin @User Vui lòng xem thông báo", // Bắt buộc
+  mentions: [ // Bắt buộc
+    { user_id: "ADMIN_ID", offset: 0, length: 6 },
+    { user_id: "USER_ID", offset: 7, length: 5 }
+  ],
+  delay: 2000,
+}
+```
+
+## Interface chi tiết
+
+### GroupMessageItem
+```typescript
+interface GroupMessageItem {
+  type: "text" | "image" | "file" | "sticker" | "mention";
+  text?: string;
+  imageUrl?: string;
+  attachmentId?: string;
+  caption?: string;
+  fileToken?: string;
+  fileName?: string;
+  stickerId?: string;
+  mentions?: Array<{
+    user_id: string;
+    offset: number;
+    length: number;
+  }>;
+  delay?: number; // milliseconds
+}
+```
+
+### SendMessageListToGroupRequest
+```typescript
+interface SendMessageListToGroupRequest {
+  accessToken: string;
+  groupId: string;
+  messages: GroupMessageItem[];
+  defaultDelay?: number; // milliseconds
+  onProgress?: (progress: GroupMessageProgressInfo) => void;
+}
+```
+
+### SendMessageListToMultipleGroupsRequest
+```typescript
+interface SendMessageListToMultipleGroupsRequest {
+  accessToken: string;
+  groupIds: string[];
+  messages: GroupMessageItem[];
+  defaultDelay?: number; // milliseconds
+  delayBetweenGroups?: number; // milliseconds
+  onProgress?: (progress: MultipleGroupsProgressInfo) => void;
+}
+```
+
+## Ví dụ thực tế
+
+### Thông báo bảo trì hệ thống
+```typescript
+const maintenanceMessages: GroupMessageItem[] = [
+  {
+    type: "text",
+    text: "🔧 THÔNG BÁO BẢO TRÌ HỆ THỐNG",
+    delay: 2000,
+  },
+  {
+    type: "text",
+    text: "⏰ Thời gian: 2:00 - 4:00 sáng ngày mai\n⚠️ Các dịch vụ sẽ tạm ngưng",
+    delay: 1500,
+  },
+  {
+    type: "image",
+    imageUrl: "https://company.com/maintenance-schedule.jpg",
+    caption: "Lịch trình bảo trì chi tiết",
+    delay: 2000,
+  },
+  {
+    type: "text",
+    text: "📞 Hotline hỗ trợ: 1900-xxxx",
+  },
+];
+
+const result = await groupMessageService.sendMessageListToMultipleGroups({
+  accessToken: "TOKEN",
+  groupIds: ["TECH_GROUP", "SUPPORT_GROUP", "ADMIN_GROUP"],
+  messages: maintenanceMessages,
+  delayBetweenGroups: 2000,
+  onProgress: (progress) => {
+    if (progress.status === 'completed') {
+      console.log(`✅ Đã thông báo tới group ${progress.groupIndex + 1}`);
+    }
+  }
+});
+```
+
+### Marketing Campaign
+```typescript
+const campaignMessages: GroupMessageItem[] = [
+  {
+    type: "text",
+    text: "🎉 FLASH SALE 24H - GIẢM GIÁ SỐC!",
+    delay: 2000,
+  },
+  {
+    type: "image",
+    imageUrl: "https://shop.com/flash-sale-banner.jpg",
+    caption: "🔥 Giảm tới 70% + Freeship",
+    delay: 3000,
+  },
+  {
+    type: "text",
+    text: "⏰ Chỉ còn 12 giờ!\n🛒 Mua ngay: https://shop.com/sale",
+    delay: 1500,
+  },
+  {
+    type: "sticker",
+    stickerId: "SALE_STICKER_ID",
+  },
+];
+
+const customerGroups = ["VIP_CUSTOMERS", "REGULAR_CUSTOMERS", "NEW_CUSTOMERS"];
+
+const result = await groupMessageService.sendMessageListToMultipleGroups({
+  accessToken: "TOKEN",
+  groupIds: customerGroups,
+  messages: campaignMessages,
+  defaultDelay: 1000,
+  delayBetweenGroups: 5000, // 5s delay để tránh spam
+  onProgress: (progress) => {
+    console.log(`📤 Campaign progress: ${progress.groupIndex + 1}/${progress.totalGroups}`);
+  }
+});
+
+console.log(`🎯 Campaign hoàn thành: ${result.successfulGroups} groups nhận được tin nhắn`);
+```
+
+### Meeting Notification với Mention
+```typescript
+const meetingMessages: GroupMessageItem[] = [
+  {
+    type: "text",
+    text: "📅 THÔNG BÁO CUỘC HỌP",
+    delay: 1000,
+  },
+  {
+    type: "mention",
+    text: "@TeamLead @Developer @Designer Cuộc họp dự án lúc 14:00 hôm nay",
+    mentions: [
+      { user_id: "LEAD_ID", offset: 0, length: 9 },
+      { user_id: "DEV_ID", offset: 10, length: 10 },
+      { user_id: "DESIGN_ID", offset: 21, length: 9 }
+    ],
+    delay: 2000,
+  },
+  {
+    type: "text",
+    text: "📋 Agenda:\n1. Sprint review\n2. Planning\n3. Q&A",
+  },
+];
+
+const result = await groupMessageService.sendMessageListToGroup({
+  accessToken: "TOKEN",
+  groupId: "PROJECT_TEAM_GROUP",
+  messages: meetingMessages,
+  defaultDelay: 1500,
+});
+```
+
+## So sánh với API cũ
+
+| Tính năng | API cũ | API mới |
+|-----------|--------|---------|
+| Số lượng tin nhắn | 1 tin nhắn | Nhiều tin nhắn |
+| Số lượng groups | 1 group | 1 hoặc nhiều groups |
+| Callback tracking | ❌ | ✅ Real-time |
+| Delay control | ❌ | ✅ Tùy chỉnh |
+| Error handling | Dừng khi lỗi | Tiếp tục với tin nhắn/group khác |
+| Statistics | ❌ | ✅ Chi tiết |
+| Use case | Tin nhắn đơn lẻ | Campaigns, notifications |
+
+## Lưu ý quan trọng
+
+1. **Rate Limiting**: Sử dụng `delayBetweenGroups` để tránh hit rate limit
+2. **Group Permissions**: OA phải có quyền gửi tin nhắn trong group
+3. **Message Limits**: Tuân thủ giới hạn của từng loại tin nhắn (text: 2000 ký tự, etc.)
+4. **Error Isolation**: Lỗi của 1 tin nhắn/group không ảnh hưởng phần còn lại
+5. **Callback Performance**: Callback không nên thực hiện operations nặng