@warriorteam/redai-zalo-sdk 1.2.0 → 1.3.0

package/docs/USER_MANAGEMENT.md

@@ -0,0 +1,1248 @@
+# RedAI Zalo SDK - User Management Guide
+
+## Tổng quan
+
+User Management trong RedAI Zalo SDK cung cấp các công cụ toàn diện để quản lý người dùng, bao gồm:
+
+- 👥 **UserService** - Truy cập thông tin user social và OA followers
+- 🏷️ **UserManagementService** - Quản lý user profiles và interactions
+- 📊 **User Analytics** - Phân tích hành vi và tương tác
+- 🔍 **User Search** - Tìm kiếm và lọc users
+- 📋 **Bulk Operations** - Xử lý hàng loạt users
+
+---
+
+## UserService
+
+Truy cập thông tin user từ Social API và OA followers.
+
+### Khởi tạo
+
+```typescript
+import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";
+
+const zalo = new ZaloSDK({
+  appId: "your-app-id",
+  appSecret: "your-app-secret"
+});
+
+// Access user service
+const userService = zalo.user;
+```
+
+### 1. Lấy thông tin user Social
+
+```typescript
+// Lấy thông tin user từ Social API
+const socialUserInfo = await zalo.getSocialUserInfo(
+  socialAccessToken,
+  "id,name,picture,birthday,gender,locale"
+);
+
+console.log("User ID:", socialUserInfo.id);
+console.log("Name:", socialUserInfo.name);
+console.log("Avatar:", socialUserInfo.picture?.data.url);
+console.log("Birthday:", socialUserInfo.birthday);
+```
+
+### 2. Lấy thông tin user OA
+
+```typescript
+// Lấy thông tin user đã tương tác với OA
+const userInfo = await zalo.user.getUserInfo(
+  oaAccessToken,
+  "zalo-user-id"
+);
+
+console.log("User Info:", {
+  userId: userInfo.user_id,
+  displayName: userInfo.display_name, 
+  avatar: userInfo.avatar,
+  userGender: userInfo.user_gender,
+  userAlias: userInfo.user_alias
+});
+```
+
+### 3. Lấy danh sách users
+
+```typescript
+// Lấy danh sách users với filter
+const userList = await zalo.user.getUserList(oaAccessToken, {
+  offset: 0,
+  count: 50,
+  tag_name: "VIP_CUSTOMER", // Lọc theo tag (tùy chọn)
+  is_follower: true          // Chỉ lấy followers (tùy chọn)
+});
+
+console.log("Total users:", userList.total);
+userList.data.forEach(user => {
+  console.log(`${user.display_name} - ${user.user_id}`);
+});
+```
+
+### 4. Lấy danh sách followers
+
+```typescript
+// Lấy tất cả followers của OA
+const followers = await zalo.user.getFollowers(oaAccessToken, {
+  offset: 0,
+  count: 100
+});
+
+console.log("Total followers:", followers.total);
+followers.data.forEach(follower => {
+  console.log(`Follower: ${follower.display_name}`);
+  console.log(`Follow time: ${new Date(follower.user_id_by_app).toLocaleString()}`);
+});
+```
+
+---
+
+## UserManagementService
+
+Quản lý user profiles chi tiết và interactions.
+
+### Khởi tạo
+
+```typescript
+const userManagement = zalo.userManagement;
+```
+
+### 1. Lấy user profile chi tiết
+
+```typescript
+// Lấy profile đầy đủ của user
+const userProfile = await zalo.userManagement.getUserProfile(
+  oaAccessToken,
+  "user-zalo-id"
+);
+
+console.log("User Profile:", {
+  userId: userProfile.user_id,
+  displayName: userProfile.display_name,
+  avatar: userProfile.avatar,
+  phone: userProfile.shared_info?.phone,
+  address: userProfile.shared_info?.address,
+  tags: userProfile.tags,
+  notes: userProfile.notes,
+  lastInteraction: userProfile.last_interaction_time
+});
+```
+
+### 2. Cập nhật user profile
+
+```typescript
+// Cập nhật thông tin user
+const updatedProfile = await zalo.userManagement.updateUserProfile(
+  oaAccessToken,
+  "user-zalo-id",
+  {
+    notes: "Customer quan tâm sản phẩm cao cấp",
+    custom_fields: {
+      customer_tier: "VIP",
+      preferred_contact: "zalo",
+      last_purchase_date: "2024-12-01",
+      total_spent: "5000000"
+    }
+  }
+);
+```
+
+### 3. Lấy lịch sử tương tác
+
+```typescript
+// Lấy tất cả interactions với user
+const interactions = await zalo.userManagement.getUserInteractions(
+  oaAccessToken,
+  "user-zalo-id",
+  {
+    from_time: Date.now() - (30 * 24 * 60 * 60 * 1000), // 30 days ago
+    to_time: Date.now(),
+    interaction_type: "all", // message, call, order, etc.
+    limit: 100
+  }
+);
+
+interactions.forEach(interaction => {
+  console.log(`${interaction.type}: ${interaction.content} at ${new Date(interaction.time).toLocaleString()}`);
+});
+```
+
+### 4. Phân tích user analytics
+
+```typescript
+// Lấy analytics của user
+const userAnalytics = await zalo.userManagement.getUserAnalytics(
+  oaAccessToken,
+  "user-zalo-id"
+);
+
+console.log("User Analytics:", {
+  totalMessages: userAnalytics.total_messages_sent,
+  totalMessagesReceived: userAnalytics.total_messages_received,
+  avgResponseTime: userAnalytics.avg_response_time,
+  engagementScore: userAnalytics.engagement_score,
+  lastSeenTime: userAnalytics.last_seen_time,
+  preferredTime: userAnalytics.most_active_time
+});
+```
+
+### 5. Tìm kiếm users
+
+```typescript
+// Tìm kiếm users theo điều kiện
+const searchResult = await zalo.userManagement.searchUsers(
+  oaAccessToken,
+  {
+    query: "Nguyễn",              // Tên hoặc phone
+    tags: ["VIP", "Premium"],      // Tags
+    interaction_period: 30,        // Tương tác trong 30 ngày qua
+    min_order_value: 1000000,      // Đơn hàng tối thiểu
+    location: "Ho Chi Minh",       // Địa điểm
+    gender: "male",               // Giới tính
+    age_range: "25-35",           // Độ tuổi
+    limit: 50,
+    offset: 0
+  }
+);
+
+console.log(`Found ${searchResult.total} users matching criteria`);
+searchResult.users.forEach(user => {
+  console.log(`${user.display_name} - Score: ${user.match_score}`);
+});
+```
+
+---
+
+## User Segmentation & Analytics
+
+### 1. User Segmentation Service
+
+```typescript
+class UserSegmentationService {
+  constructor(private zalo: ZaloSDK, private accessToken: string) {}
+
+  // Phân đoạn users theo hành vi mua hàng
+  async segmentUsersByPurchaseBehavior(): Promise<UserSegments> {
+    const allUsers = await this.getAllUsers();
+    const segments = {
+      highValue: [],      // > 10M VND
+      mediumValue: [],    // 1M - 10M VND  
+      lowValue: [],       // < 1M VND
+      inactive: []        // Không mua trong 90 ngày
+    };
+
+    for (const user of allUsers) {
+      const analytics = await this.zalo.userManagement.getUserAnalytics(
+        this.accessToken,
+        user.user_id
+      );
+
+      const totalSpent = analytics.total_spent || 0;
+      const daysSinceLastPurchase = analytics.days_since_last_purchase || 999;
+
+      if (daysSinceLastPurchase > 90) {
+        segments.inactive.push(user);
+      } else if (totalSpent > 10000000) {
+        segments.highValue.push(user);
+      } else if (totalSpent > 1000000) {
+        segments.mediumValue.push(user);
+      } else {
+        segments.lowValue.push(user);
+      }
+    }
+
+    return segments;
+  }
+
+  // Phân đoạn theo engagement
+  async segmentUsersByEngagement(): Promise<EngagementSegments> {
+    const users = await this.getAllUsers();
+    const segments = {
+      champions: [],      // High value + High engagement
+      loyalists: [],      // High engagement
+      potential: [],      // Medium engagement  
+      atRisk: [],        // Low recent engagement
+      lost: []           // No recent engagement
+    };
+
+    for (const user of users) {
+      const analytics = await this.zalo.userManagement.getUserAnalytics(
+        this.accessToken,
+        user.user_id
+      );
+
+      const engagementScore = analytics.engagement_score || 0;
+      const daysSinceLastInteraction = analytics.days_since_last_interaction || 999;
+      const totalSpent = analytics.total_spent || 0;
+
+      if (engagementScore > 80 && totalSpent > 5000000) {
+        segments.champions.push(user);
+      } else if (engagementScore > 70) {
+        segments.loyalists.push(user);
+      } else if (engagementScore > 40) {
+        segments.potential.push(user);
+      } else if (daysSinceLastInteraction < 30) {
+        segments.atRisk.push(user);
+      } else {
+        segments.lost.push(user);
+      }
+    }
+
+    return segments;
+  }
+
+  private async getAllUsers(): Promise<UserProfile[]> {
+    const allUsers = [];
+    let offset = 0;
+    const limit = 100;
+
+    while (true) {
+      const userList = await this.zalo.user.getUserList(this.accessToken, {
+        offset,
+        count: limit
+      });
+
+      allUsers.push(...userList.data);
+
+      if (userList.data.length < limit) break;
+      offset += limit;
+    }
+
+    return allUsers;
+  }
+}
+```
+
+### 2. Customer Lifetime Value Analysis
+
+```typescript
+class CLVAnalysisService {
+  constructor(private zalo: ZaloSDK, private accessToken: string) {}
+
+  async calculateUserCLV(userId: string): Promise<CLVMetrics> {
+    const analytics = await this.zalo.userManagement.getUserAnalytics(
+      this.accessToken,
+      userId
+    );
+
+    const interactions = await this.zalo.userManagement.getUserInteractions(
+      this.accessToken,
+      userId,
+      { interaction_type: "purchase", limit: 1000 }
+    );
+
+    const purchases = interactions.filter(i => i.type === "purchase");
+    
+    if (purchases.length === 0) {
+      return { clv: 0, tier: "inactive", recommendations: [] };
+    }
+
+    // Tính toán CLV
+    const totalSpent = purchases.reduce((sum, p) => sum + (p.value || 0), 0);
+    const avgOrderValue = totalSpent / purchases.length;
+    const purchaseFrequency = this.calculatePurchaseFrequency(purchases);
+    const customerLifespan = this.calculateCustomerLifespan(purchases);
+    
+    const clv = avgOrderValue * purchaseFrequency * customerLifespan;
+
+    return {
+      clv,
+      avgOrderValue,
+      purchaseFrequency,
+      customerLifespan,
+      totalOrders: purchases.length,
+      totalSpent,
+      tier: this.determineTier(clv),
+      recommendations: this.generateRecommendations(clv, analytics)
+    };
+  }
+
+  private calculatePurchaseFrequency(purchases: any[]): number {
+    if (purchases.length < 2) return 0;
+
+    const timespan = purchases[0].time - purchases[purchases.length - 1].time;
+    const days = timespan / (24 * 60 * 60 * 1000);
+    
+    return purchases.length / (days / 365); // Purchases per year
+  }
+
+  private calculateCustomerLifespan(purchases: any[]): number {
+    if (purchases.length < 2) return 1;
+
+    const timespan = purchases[0].time - purchases[purchases.length - 1].time;
+    return Math.max(1, timespan / (365 * 24 * 60 * 60 * 1000)); // Years
+  }
+
+  private determineTier(clv: number): string {
+    if (clv > 50000000) return "diamond";
+    if (clv > 20000000) return "gold";
+    if (clv > 5000000) return "silver";
+    if (clv > 1000000) return "bronze";
+    return "standard";
+  }
+
+  private generateRecommendations(clv: number, analytics: any): string[] {
+    const recommendations = [];
+
+    if (clv > 20000000) {
+      recommendations.push("Assign dedicated account manager");
+      recommendations.push("Offer exclusive products and early access");
+      recommendations.push("Provide VIP customer service");
+    } else if (clv > 5000000) {
+      recommendations.push("Implement loyalty program");
+      recommendations.push("Send personalized offers");
+      recommendations.push("Prioritize customer support");
+    } else if (clv < 1000000) {
+      recommendations.push("Focus on engagement and education");
+      recommendations.push("Offer entry-level products");
+      recommendations.push("Encourage repeat purchases");
+    }
+
+    return recommendations;
+  }
+}
+```
+
+---
+
+## Bulk Operations
+
+### 1. Bulk User Operations
+
+```typescript
+// Thực hiện bulk operations trên nhiều users
+const bulkResult = await zalo.userManagement.bulkUserOperation(
+  oaAccessToken,
+  {
+    operation: "update_tags",
+    user_ids: ["user1", "user2", "user3"],
+    data: {
+      add_tags: ["FLASH_SALE_2024"],
+      remove_tags: ["OLD_CAMPAIGN"]
+    }
+  }
+);
+
+console.log(`Updated ${bulkResult.successful_count} users`);
+console.log(`Failed: ${bulkResult.failed_count}`);
+```
+
+### 2. Bulk Message Service
+
+```typescript
+class BulkMessageService {
+  constructor(private zalo: ZaloSDK, private accessToken: string) {}
+
+  async sendBulkConsultationMessages(
+    userMessages: Array<{userId: string, message: any}>
+  ): Promise<BulkMessageResult> {
+    const results = {
+      successful: 0,
+      failed: 0,
+      errors: [] as Array<{userId: string, error: string}>
+    };
+
+    const batchSize = 10; // Process 10 users at a time
+
+    for (let i = 0; i < userMessages.length; i += batchSize) {
+      const batch = userMessages.slice(i, i + batchSize);
+      
+      const promises = batch.map(async ({userId, message}) => {
+        try {
+          await this.zalo.consultation.sendTextMessage(
+            this.accessToken,
+            { user_id: userId },
+            message
+          );
+          return { userId, success: true };
+        } catch (error) {
+          return { userId, success: false, error: error.message };
+        }
+      });
+
+      const batchResults = await Promise.all(promises);
+      
+      batchResults.forEach(result => {
+        if (result.success) {
+          results.successful++;
+        } else {
+          results.failed++;
+          results.errors.push({
+            userId: result.userId,
+            error: result.error || 'Unknown error'
+          });
+        }
+      });
+
+      // Delay between batches to avoid rate limiting
+      if (i + batchSize < userMessages.length) {
+        await this.delay(1000);
+      }
+    }
+
+    return results;
+  }
+
+  // Gửi tin nhắn theo segments
+  async sendSegmentedCampaign(campaign: Campaign): Promise<CampaignResult> {
+    const segments = await this.getUserSegments(campaign.targetSegments);
+    const results = new Map<string, BulkMessageResult>();
+
+    for (const [segmentName, users] of segments) {
+      console.log(`Sending campaign to ${segmentName}: ${users.length} users`);
+      
+      const segmentMessage = this.personalizeMessageForSegment(
+        campaign.message,
+        segmentName
+      );
+      
+      const userMessages = users.map(user => ({
+        userId: user.user_id,
+        message: this.personalizeMessage(segmentMessage, user)
+      }));
+
+      const segmentResult = await this.sendBulkConsultationMessages(userMessages);
+      results.set(segmentName, segmentResult);
+    }
+
+    return this.aggregateResults(results);
+  }
+
+  private async getUserSegments(targetSegments: string[]): Promise<Map<string, UserProfile[]>> {
+    const segments = new Map();
+
+    for (const segment of targetSegments) {
+      const users = await this.zalo.userManagement.searchUsers(
+        this.accessToken,
+        { tags: [segment], limit: 1000 }
+      );
+      segments.set(segment, users.users);
+    }
+
+    return segments;
+  }
+
+  private personalizeMessageForSegment(template: string, segment: string): any {
+    // Customize message based on segment
+    const customizations = {
+      'VIP': {
+        greeting: 'Kính chào Quý khách VIP',
+        offer: 'ưu đãi đặc biệt dành riêng cho VIP'
+      },
+      'Premium': {
+        greeting: 'Xin chào khách hàng Premium',
+        offer: 'chương trình ưu đãi Premium'
+      },
+      'Standard': {
+        greeting: 'Xin chào',
+        offer: 'chương trình khuyến mại'
+      }
+    };
+
+    const custom = customizations[segment] || customizations['Standard'];
+    
+    return {
+      type: "text",
+      text: template
+        .replace('{greeting}', custom.greeting)
+        .replace('{offer}', custom.offer)
+    };
+  }
+
+  private personalizeMessage(template: any, user: UserProfile): any {
+    return {
+      ...template,
+      text: template.text.replace('{name}', user.display_name || 'bạn')
+    };
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+---
+
+## User Journey Tracking
+
+### 1. Journey Mapping Service
+
+```typescript
+class UserJourneyService {
+  constructor(private zalo: ZaloSDK, private accessToken: string) {}
+
+  async mapUserJourney(userId: string): Promise<UserJourney> {
+    const interactions = await this.zalo.userManagement.getUserInteractions(
+      this.accessToken,
+      userId,
+      { limit: 1000 }
+    );
+
+    const journey = this.analyzeJourneyStages(interactions);
+    const touchpoints = this.identifyTouchpoints(interactions);
+    const conversion = this.calculateConversionMetrics(interactions);
+
+    return {
+      userId,
+      currentStage: journey.currentStage,
+      stages: journey.stages,
+      touchpoints,
+      conversion,
+      recommendations: this.generateJourneyRecommendations(journey, conversion)
+    };
+  }
+
+  private analyzeJourneyStages(interactions: any[]): JourneyStages {
+    const stages = {
+      awareness: [],
+      consideration: [],
+      purchase: [],
+      retention: [],
+      advocacy: []
+    };
+
+    const currentStage = this.determineCurrentStage(interactions);
+
+    // Classify interactions by journey stage
+    interactions.forEach(interaction => {
+      const stage = this.classifyInteractionStage(interaction);
+      stages[stage].push(interaction);
+    });
+
+    return { currentStage, stages };
+  }
+
+  private identifyTouchpoints(interactions: any[]): Touchpoint[] {
+    const touchpointMap = new Map();
+
+    interactions.forEach(interaction => {
+      const touchpoint = this.getTouchpointFromInteraction(interaction);
+      
+      if (touchpointMap.has(touchpoint.type)) {
+        touchpointMap.get(touchpoint.type).count++;
+        touchpointMap.get(touchpoint.type).lastInteraction = interaction.time;
+      } else {
+        touchpointMap.set(touchpoint.type, {
+          ...touchpoint,
+          count: 1,
+          lastInteraction: interaction.time
+        });
+      }
+    });
+
+    return Array.from(touchpointMap.values()).sort((a, b) => b.count - a.count);
+  }
+
+  private calculateConversionMetrics(interactions: any[]): ConversionMetrics {
+    const totalInteractions = interactions.length;
+    const purchases = interactions.filter(i => i.type === 'purchase');
+    const inquiries = interactions.filter(i => i.type === 'product_inquiry');
+    
+    return {
+      conversionRate: purchases.length / totalInteractions,
+      inquiryToPurchase: purchases.length / (inquiries.length || 1),
+      avgTimeToConversion: this.calculateAvgTimeToConversion(interactions),
+      totalPurchases: purchases.length,
+      totalValue: purchases.reduce((sum, p) => sum + (p.value || 0), 0)
+    };
+  }
+
+  private generateJourneyRecommendations(
+    journey: JourneyStages,
+    conversion: ConversionMetrics
+  ): string[] {
+    const recommendations = [];
+
+    switch (journey.currentStage) {
+      case 'awareness':
+        recommendations.push('Send educational content about products');
+        recommendations.push('Showcase customer testimonials and reviews');
+        break;
+        
+      case 'consideration':
+        recommendations.push('Provide detailed product comparisons');
+        recommendations.push('Offer consultation sessions');
+        recommendations.push('Send limited-time offers to encourage decision');
+        break;
+        
+      case 'purchase':
+        recommendations.push('Streamline checkout process');
+        recommendations.push('Offer multiple payment options');
+        recommendations.push('Provide immediate support');
+        break;
+        
+      case 'retention':
+        recommendations.push('Send onboarding and education materials');
+        recommendations.push('Implement loyalty program');
+        recommendations.push('Request feedback and reviews');
+        break;
+        
+      case 'advocacy':
+        recommendations.push('Encourage referrals with incentives');
+        recommendations.push('Feature as case study');
+        recommendations.push('Invite to exclusive events');
+        break;
+    }
+
+    if (conversion.conversionRate < 0.1) {
+      recommendations.push('Focus on engagement improvement');
+      recommendations.push('Personalize content based on interests');
+    }
+
+    return recommendations;
+  }
+}
+```
+
+---
+
+## User Retention & Re-engagement
+
+### 1. Retention Analysis
+
+```typescript
+class UserRetentionService {
+  constructor(private zalo: ZaloSDK, private accessToken: string) {}
+
+  async analyzeUserRetention(period: 'weekly' | 'monthly'): Promise<RetentionAnalysis> {
+    const cohorts = await this.getCohorts(period);
+    const retentionRates = new Map();
+
+    for (const [cohortDate, users] of cohorts) {
+      const retention = await this.calculateCohortRetention(users, cohortDate, period);
+      retentionRates.set(cohortDate, retention);
+    }
+
+    return {
+      period,
+      cohorts: Array.from(retentionRates.entries()),
+      averageRetention: this.calculateAverageRetention(retentionRates),
+      insights: this.generateRetentionInsights(retentionRates)
+    };
+  }
+
+  // Identify users at risk of churning
+  async identifyChurnRisk(): Promise<ChurnRiskAnalysis> {
+    const allUsers = await this.getAllActiveUsers();
+    const riskUsers = [];
+
+    for (const user of allUsers) {
+      const riskScore = await this.calculateChurnRiskScore(user.user_id);
+      
+      if (riskScore > 0.7) {
+        riskUsers.push({
+          ...user,
+          riskScore,
+          riskFactors: await this.identifyRiskFactors(user.user_id)
+        });
+      }
+    }
+
+    return {
+      totalUsers: allUsers.length,
+      highRiskUsers: riskUsers.filter(u => u.riskScore > 0.9),
+      mediumRiskUsers: riskUsers.filter(u => u.riskScore > 0.7 && u.riskScore <= 0.9),
+      recommendations: this.generateChurnPreventionStrategies(riskUsers)
+    };
+  }
+
+  private async calculateChurnRiskScore(userId: string): Promise<number> {
+    const analytics = await this.zalo.userManagement.getUserAnalytics(
+      this.accessToken,
+      userId
+    );
+
+    let score = 0;
+
+    // Days since last interaction
+    const daysSinceLastInteraction = analytics.days_since_last_interaction || 0;
+    if (daysSinceLastInteraction > 30) score += 0.3;
+    if (daysSinceLastInteraction > 60) score += 0.2;
+    if (daysSinceLastInteraction > 90) score += 0.3;
+
+    // Declining engagement
+    const engagementTrend = analytics.engagement_trend || 0;
+    if (engagementTrend < -0.2) score += 0.2;
+
+    // Reduced purchase frequency
+    const purchaseTrend = analytics.purchase_frequency_trend || 0;
+    if (purchaseTrend < -0.3) score += 0.3;
+
+    // Support issues
+    const supportIssues = analytics.recent_support_issues || 0;
+    if (supportIssues > 2) score += 0.2;
+
+    return Math.min(1, score);
+  }
+
+  // Re-engagement campaign for inactive users
+  async runReengagementCampaign(
+    inactiveUsers: string[],
+    campaignType: 'win_back' | 'survey' | 'special_offer'
+  ): Promise<ReengagementResult> {
+    const results = {
+      contacted: 0,
+      responded: 0,
+      reactivated: 0,
+      errors: []
+    };
+
+    for (const userId of inactiveUsers) {
+      try {
+        const message = this.createReengagementMessage(campaignType, userId);
+        
+        await this.zalo.consultation.sendTextMessage(
+          this.accessToken,
+          { user_id: userId },
+          message
+        );
+        
+        results.contacted++;
+
+        // Track if user responds within campaign period
+        setTimeout(async () => {
+          const isReactivated = await this.checkUserReactivation(userId);
+          if (isReactivated) {
+            results.reactivated++;
+          }
+        }, 7 * 24 * 60 * 60 * 1000); // Check after 7 days
+
+      } catch (error) {
+        results.errors.push({ userId, error: error.message });
+      }
+    }
+
+    return results;
+  }
+
+  private createReengagementMessage(
+    campaignType: string,
+    userId: string
+  ): any {
+    const messages = {
+      win_back: {
+        type: "text",
+        text: "Chúng tôi nhớ bạn! 🥺\nBạn đã không tương tác với chúng tôi một thời gian rồi. Có gì chúng tôi có thể giúp bạn không?"
+      },
+      survey: {
+        type: "text", 
+        text: "Xin chào! 👋\nChúng tôi muốn cải thiện dịch vụ. Bạn có thể chia sẻ lý do tại sao ít tương tác với chúng tôi gần đây không?"
+      },
+      special_offer: {
+        type: "text",
+        text: "🎁 Ưu đãi đặc biệt dành cho bạn!\nGiảm 50% cho lần mua hàng tiếp theo. Mã: COMEBACK50\nChỉ còn 3 ngày!"
+      }
+    };
+
+    return messages[campaignType] || messages.win_back;
+  }
+}
+```
+
+---
+
+## Data Privacy & GDPR Compliance
+
+### 1. User Consent Management
+
+```typescript
+class UserConsentService {
+  constructor(private zalo: ZaloSDK, private accessToken: string) {}
+
+  async recordUserConsent(
+    userId: string,
+    consentType: ConsentType,
+    granted: boolean
+  ): Promise<void> {
+    await this.zalo.userManagement.updateUserProfile(
+      this.accessToken,
+      userId,
+      {
+        custom_fields: {
+          [`consent_${consentType}`]: granted.toString(),
+          [`consent_${consentType}_date`]: new Date().toISOString(),
+          [`consent_${consentType}_ip`]: this.getCurrentIP()
+        }
+      }
+    );
+  }
+
+  async getUserConsents(userId: string): Promise<UserConsents> {
+    const profile = await this.zalo.userManagement.getUserProfile(
+      this.accessToken,
+      userId
+    );
+
+    return {
+      marketing: profile.custom_fields?.consent_marketing === 'true',
+      analytics: profile.custom_fields?.consent_analytics === 'true',
+      data_processing: profile.custom_fields?.consent_data_processing === 'true',
+      third_party_sharing: profile.custom_fields?.consent_third_party === 'true'
+    };
+  }
+
+  async exportUserData(userId: string): Promise<UserDataExport> {
+    const profile = await this.zalo.userManagement.getUserProfile(
+      this.accessToken,
+      userId
+    );
+
+    const interactions = await this.zalo.userManagement.getUserInteractions(
+      this.accessToken,
+      userId,
+      { limit: 10000 }
+    );
+
+    const analytics = await this.zalo.userManagement.getUserAnalytics(
+      this.accessToken,
+      userId
+    );
+
+    return {
+      personal_data: {
+        user_id: profile.user_id,
+        display_name: profile.display_name,
+        avatar: profile.avatar,
+        phone: profile.shared_info?.phone,
+        address: profile.shared_info?.address
+      },
+      interaction_history: interactions,
+      analytics_data: analytics,
+      consent_records: await this.getUserConsents(userId),
+      export_date: new Date().toISOString(),
+      retention_period: "36_months"
+    };
+  }
+
+  async deleteUserData(userId: string): Promise<DeletionResult> {
+    // Implement GDPR-compliant data deletion
+    const deletionTasks = [
+      this.deleteUserProfile(userId),
+      this.deleteUserInteractions(userId),
+      this.deleteUserAnalytics(userId),
+      this.removeFromMarketingLists(userId)
+    ];
+
+    const results = await Promise.allSettled(deletionTasks);
+    
+    return {
+      userId,
+      deleted: results.every(r => r.status === 'fulfilled'),
+      deletion_date: new Date().toISOString(),
+      retention_logs: this.createDeletionLog(userId, results)
+    };
+  }
+}
+```
+
+---
+
+## Testing User Management
+
+### 1. Unit Tests
+
+```typescript
+// user-management.test.ts
+import { ZaloSDK } from '@warriorteam/redai-zalo-sdk';
+
+describe('User Management', () => {
+  const zalo = new ZaloSDK({
+    appId: 'test_app_id',
+    appSecret: 'test_app_secret'
+  });
+
+  it('should get user profile', async () => {
+    const mockProfile = {
+      user_id: 'test_user',
+      display_name: 'Test User',
+      avatar: 'https://example.com/avatar.jpg'
+    };
+
+    jest.spyOn(zalo.userManagement, 'getUserProfile').mockResolvedValue(mockProfile);
+
+    const profile = await zalo.userManagement.getUserProfile('test_token', 'test_user');
+    
+    expect(profile.user_id).toBe('test_user');
+    expect(profile.display_name).toBe('Test User');
+  });
+
+  it('should search users with filters', async () => {
+    const mockResult = {
+      total: 5,
+      users: [
+        { user_id: '1', display_name: 'User 1' },
+        { user_id: '2', display_name: 'User 2' }
+      ]
+    };
+
+    jest.spyOn(zalo.userManagement, 'searchUsers').mockResolvedValue(mockResult);
+
+    const result = await zalo.userManagement.searchUsers('test_token', {
+      query: 'test',
+      tags: ['VIP']
+    });
+
+    expect(result.total).toBe(5);
+    expect(result.users).toHaveLength(2);
+  });
+});
+```
+
+---
+
+## Performance Optimization
+
+### 1. Caching User Data
+
+```typescript
+class UserDataCache {
+  private cache = new Map<string, CachedUserData>();
+  private readonly ttl = 10 * 60 * 1000; // 10 minutes
+
+  async getUserProfile(
+    zalo: ZaloSDK,
+    accessToken: string,
+    userId: string
+  ): Promise<UserProfile> {
+    const cacheKey = `profile_${userId}`;
+    const cached = this.get(cacheKey);
+    
+    if (cached) {
+      return cached.data;
+    }
+
+    const profile = await zalo.userManagement.getUserProfile(accessToken, userId);
+    this.set(cacheKey, profile);
+    
+    return profile;
+  }
+
+  private get(key: string): CachedUserData | null {
+    const item = this.cache.get(key);
+    
+    if (!item) return null;
+    
+    if (Date.now() - item.timestamp > this.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+    
+    return item;
+  }
+
+  private set(key: string, data: any): void {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now()
+    });
+  }
+
+  // Batch load multiple users
+  async batchLoadUsers(
+    zalo: ZaloSDK,
+    accessToken: string,
+    userIds: string[]
+  ): Promise<Map<string, UserProfile>> {
+    const results = new Map();
+    const uncachedIds = [];
+
+    // Check cache first
+    for (const userId of userIds) {
+      const cached = this.get(`profile_${userId}`);
+      if (cached) {
+        results.set(userId, cached.data);
+      } else {
+        uncachedIds.push(userId);
+      }
+    }
+
+    // Batch load uncached users
+    if (uncachedIds.length > 0) {
+      const batchSize = 5; // API rate limiting
+      
+      for (let i = 0; i < uncachedIds.length; i += batchSize) {
+        const batch = uncachedIds.slice(i, i + batchSize);
+        
+        const promises = batch.map(async (userId) => {
+          try {
+            const profile = await zalo.userManagement.getUserProfile(accessToken, userId);
+            this.set(`profile_${userId}`, profile);
+            return { userId, profile };
+          } catch (error) {
+            console.error(`Failed to load user ${userId}:`, error);
+            return { userId, profile: null };
+          }
+        });
+
+        const batchResults = await Promise.all(promises);
+        
+        batchResults.forEach(({ userId, profile }) => {
+          if (profile) {
+            results.set(userId, profile);
+          }
+        });
+
+        // Delay between batches
+        if (i + batchSize < uncachedIds.length) {
+          await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+      }
+    }
+
+    return results;
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Data Management Best Practices
+
+```typescript
+// ✅ Good practices
+class UserDataBestPractices {
+  // Always validate user IDs
+  private validateUserId(userId: string): boolean {
+    return /^[0-9]+$/.test(userId) && userId.length > 0;
+  }
+
+  // Implement proper error handling
+  async safeGetUserProfile(
+    zalo: ZaloSDK,
+    accessToken: string,
+    userId: string
+  ): Promise<UserProfile | null> {
+    if (!this.validateUserId(userId)) {
+      throw new Error('Invalid user ID format');
+    }
+
+    try {
+      return await zalo.userManagement.getUserProfile(accessToken, userId);
+    } catch (error) {
+      if (error.code === -233) {
+        console.log(`User ${userId} not found`);
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  // Always paginate large datasets
+  async getAllUsersWithPagination(
+    zalo: ZaloSDK,
+    accessToken: string
+  ): Promise<UserProfile[]> {
+    const allUsers = [];
+    let offset = 0;
+    const limit = 50; // Reasonable page size
+
+    while (true) {
+      const page = await zalo.user.getUserList(accessToken, {
+        offset,
+        count: limit
+      });
+
+      allUsers.push(...page.data);
+
+      if (page.data.length < limit) break;
+      offset += limit;
+
+      // Rate limiting
+      await new Promise(resolve => setTimeout(resolve, 500));
+    }
+
+    return allUsers;
+  }
+
+  // Implement data validation
+  private validateUserData(userData: any): boolean {
+    const required = ['user_id', 'display_name'];
+    return required.every(field => userData[field]);
+  }
+}
+```
+
+### 2. Privacy-First Approach
+
+```typescript
+class PrivacyCompliantUserService {
+  // Always check consent before processing
+  async sendMarketingMessage(
+    userId: string,
+    message: any
+  ): Promise<boolean> {
+    const consents = await this.getUserConsents(userId);
+    
+    if (!consents.marketing) {
+      console.log(`User ${userId} has not consented to marketing messages`);
+      return false;
+    }
+
+    // Proceed with sending message
+    return true;
+  }
+
+  // Minimize data collection
+  async updateUserProfile(
+    userId: string,
+    updates: Partial<UserProfile>
+  ): Promise<void> {
+    // Only update necessary fields
+    const allowedFields = ['notes', 'tags', 'preferences'];
+    const filteredUpdates = Object.keys(updates)
+      .filter(key => allowedFields.includes(key))
+      .reduce((obj, key) => {
+        obj[key] = updates[key];
+        return obj;
+      }, {});
+
+    if (Object.keys(filteredUpdates).length === 0) {
+      throw new Error('No valid fields to update');
+    }
+
+    // Proceed with update
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Q: "User not found" error khi lấy profile**
+```
+A: User có thể đã unfollow OA hoặc chặn OA. 
+   Kiểm tra danh sách followers trước khi truy cập profile.
+```
+
+**Q: Không lấy được thông tin phone number**
+```
+A: Phone number chỉ có sẵn nếu user đã share với OA.
+   Cần yêu cầu user cung cấp thông tin qua request_user_info.
+```
+
+**Q: Search results không accurate**
+```
+A: Zalo search có giới hạn. Implement local caching và filtering
+   để có kết quả search tốt hơn.
+```
+
+---
+
+## Next Steps
+
+Sau khi nắm vững User Management:
+
+1. **[Tag Management](./TAG_MANAGEMENT.md)** - User tagging và segmentation
+2. **[Group Management](./GROUP_MANAGEMENT.md)** - Quản lý Zalo groups  
+3. **[Webhook Events](./WEBHOOK_EVENTS.md)** - Xử lý user events
+4. **[Error Handling](./ERROR_HANDLING.md)** - Xử lý lỗi toàn diện
+5. **[Video Upload](./VIDEO_UPLOAD.md)** - Upload và manage media
+
+Tham khảo **[API Reference](./API_REFERENCE.md)** để biết chi tiết về tất cả user management methods.