@warriorteam/redai-zalo-sdk 1.3.0 → 1.4.1

package/docs/USER_MANAGEMENT.md

@@ -1,1248 +1,481 @@
-# 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.
+# User Management - Hướng Dẫn Sử Dụng
+
+## Tổng Quan
+
+`UserService` cung cấp các công cụ toàn diện để quản lý người dùng Zalo Official Account, bao gồm:
+
+- 👥 **User Information** - Lấy thông tin chi tiết người dùng
+- 📋 **User Lists** - Quản lý danh sách người dùng với phân trang
+- 🏷️ **Tag Management** - Gắn và quản lý tags cho users
+- 📊 **Custom Info** - Quản lý thông tin tùy chỉnh
+- 🔄 **Bulk Operations** - Xử lý hàng loạt users
+
+**Endpoints sử dụng:**
+- User Info: `https://openapi.zalo.me/v3.0/oa/user/detail`
+- User List: `https://openapi.zalo.me/v3.0/oa/user/getlist`
+- Update User: `https://openapi.zalo.me/v3.0/oa/user/update`
+- Custom Info: `https://openapi.zalo.me/v3.0/oa/user/getcustominfo`
+- Tags: `https://openapi.zalo.me/v3.0/oa/tag/gettagsofoa`
+
+## Khởi Tạo Service
+
+```typescript
+import { UserService } from "@warriorteam/redai-zalo-sdk";
+import { ZaloClient } from "@warriorteam/redai-zalo-sdk";
+
+const client = new ZaloClient();
+const userService = new UserService(client);
+```
+
+## Các Phương Thức Chính
+
+### 1. Lấy Thông Tin User Chi Tiết
+
+```typescript
+// Lấy thông tin chi tiết của một user
+const userInfo = await userService.getUserInfo(
+  accessToken,
+  "user-id-here"
+);
+
+console.log("User Info:", {
+  userId: userInfo.user_id,
+  displayName: userInfo.display_name,
+  avatar: userInfo.avatar,
+  userGender: userInfo.user_gender,
+  userAlias: userInfo.user_alias,
+  isFollower: userInfo.is_follower,
+  sharedInfo: userInfo.shared_info
+});
+```
+
+**Tham số:**
+- `accessToken`: Access token của OA
+- `userId`: ID người dùng cần lấy thông tin
+
+### 2. Lấy Danh Sách Users
+
+```typescript
+// Lấy danh sách users với filter
+const userList = await userService.getUserList(accessToken, {
+  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)
+  last_interaction_period: "L7D" // Tương tác trong 7 ngày qua
+});
+
+console.log("Total users:", userList.total);
+console.log("Count:", userList.count);
+console.log("Offset:", userList.offset);
+
+userList.users.forEach(user => {
+  console.log(`${user.display_name} - ${user.user_id}`);
+});
+```
+
+**Tham số:**
+- `offset`: Vị trí bắt đầu (0-based)
+- `count`: Số lượng users mỗi page (tối đa 50)
+- `tag_name`: Lọc theo tag (tùy chọn)
+- `is_follower`: true/false để lọc followers
+- `last_interaction_period`: "TODAY", "YESTERDAY", "L7D", "L30D"
+
+### 3. Lấy Tất Cả Users (Auto Pagination)
+
+```typescript
+// Lấy tất cả users với phân trang tự động
+const allUsers = await userService.getAllUsers(accessToken, {
+  is_follower: true,
+  tag_name: "PREMIUM"
+});
+
+console.log(`Total users fetched: ${allUsers.length}`);
+```
+
+**Lưu ý:**
+- Zalo giới hạn max offset = 9951 (tương ứng ~10000 users)
+- Method này tự động handle pagination và warning khi vượt giới hạn
+
+### 4. Lấy Danh Sách User IDs (Tối Ưu)
+
+```typescript
+// Chỉ lấy user IDs, không lấy thông tin chi tiết (nhanh hơn)
+const userIds = await userService.getAllUserIds(accessToken, {
+  is_follower: true
+});
+
+console.log(`Total user IDs: ${userIds.length}`);
+```
+
+### 5. Helper Methods
+
+```typescript
+// Lấy chỉ followers
+const followers = await userService.getFollowers(accessToken, 0, 50);
+
+// Lấy users theo tag
+const vipUsers = await userService.getUsersByTag(accessToken, "VIP", 0, 50);
+
+// Lấy users theo thời gian tương tác
+const recentUsers = await userService.getUsersByInteraction(
+  accessToken,
+  "L7D", // 7 ngày qua
+  0,
+  50
+);
+```
+
+## User Management Operations
+
+### 6. Cập Nhật Thông Tin User
+
+```typescript
+// Cập nhật thông tin user
+const success = await userService.updateUser(accessToken, {
+  user_id: "user-id-here",
+  notes: "Customer quan tâm sản phẩm cao cấp",
+  // Các field khác có thể cập nhật
+});
+
+console.log("Update success:", success);
+```
+
+### 7. Xóa Thông Tin User
+
+```typescript
+// Xóa thông tin user khỏi OA (không ảnh hưởng tài khoản Zalo)
+const success = await userService.deleteUserInfo(accessToken, "user-id-here");
+console.log("Delete success:", success);
+```
+
+### 8. Quản Lý Custom Info
+
+```typescript
+// Lấy custom info của user
+const customInfo = await userService.getUserCustomInfo(accessToken, {
+  user_id: "user-id-here",
+  fields_to_export: ["customer_tier", "total_spent"] // Tùy chọn
+});
+
+console.log("Custom Info:", customInfo.custom_info);
+
+// Cập nhật custom info
+const updateSuccess = await userService.updateUserCustomInfo(accessToken, {
+  user_id: "user-id-here",
+  custom_info: {
+    customer_tier: "VIP",
+    total_spent: "10000000",
+    last_purchase: "2024-12-01"
+  }
+});
+```
+
+**Lưu ý:** Cấu trúc `custom_info` phụ thuộc vào thiết lập OA
+
+## Tag Management
+
+### 9. Quản Lý Tags
+
+```typescript
+// Lấy danh sách tất cả tags của OA
+const tags = await userService.getLabels(accessToken);
+console.log("Available tags:", tags);
+
+// Thêm tag cho user
+const addSuccess = await userService.addTagToUser(accessToken, {
+  user_id: "user-id-here",
+  tag_name: "VIP_CUSTOMER"
+});
+
+// Xóa tag khỏi user
+const removeSuccess = await userService.removeTagFromUser(accessToken, {
+  user_id: "user-id-here",
+  tag_name: "OLD_TAG"
+});
+
+// Xóa tag khỏi OA (xóa hoàn toàn)
+const deleteSuccess = await userService.deleteLabel(accessToken, "UNUSED_TAG");
+```
+
+### 10. Bulk Operations
+
+```typescript
+// Bulk add tag cho nhiều users
+const bulkAddResult = await userService.bulkAddTag(
+  accessToken,
+  ["user1", "user2", "user3"],
+  "FLASH_SALE_2024"
+);
+
+console.log("Success:", bulkAddResult.success);
+console.log("Failed:", bulkAddResult.failed);
+
+// Bulk remove tag
+const bulkRemoveResult = await userService.bulkRemoveTag(
+  accessToken,
+  ["user1", "user2", "user3"],
+  "OLD_CAMPAIGN"
+);
+```
+
+## API Methods Summary
+
+| Method | Description | Parameters |
+|--------|-------------|------------|
+| `getUserInfo` | Lấy thông tin chi tiết user | `accessToken`, `userId` |
+| `getUserList` | Lấy danh sách users với pagination | `accessToken`, `request` |
+| `getAllUsers` | Lấy tất cả users (auto pagination) | `accessToken`, `filters?` |
+| `getAllUserIds` | Lấy tất cả user IDs (tối ưu) | `accessToken`, `filters?` |
+| `updateUser` | Cập nhật thông tin user | `accessToken`, `request` |
+| `deleteUserInfo` | Xóa thông tin user | `accessToken`, `userId` |
+| `getUserCustomInfo` | Lấy custom info | `accessToken`, `request` |
+| `updateUserCustomInfo` | Cập nhật custom info | `accessToken`, `request` |
+| `getLabels` | Lấy danh sách tags | `accessToken` |
+| `addTagToUser` | Thêm tag cho user | `accessToken`, `request` |
+| `removeTagFromUser` | Xóa tag khỏi user | `accessToken`, `request` |
+| `deleteLabel` | Xóa tag khỏi OA | `accessToken`, `tagName` |
+| `getUsersByTag` | Lấy users theo tag | `accessToken`, `tagName`, `offset?`, `count?` |
+| `getFollowers` | Lấy chỉ followers | `accessToken`, `offset?`, `count?` |
+| `getUsersByInteraction` | Lấy users theo thời gian tương tác | `accessToken`, `period`, `offset?`, `count?` |
+| `bulkAddTag` | Bulk add tag | `accessToken`, `userIds`, `tagName` |
+| `bulkRemoveTag` | Bulk remove tag | `accessToken`, `userIds`, `tagName` |
+
+## Ví Dụ Thực Tế
+
+### 1. Customer Support System
+
+```typescript
+class CustomerSupportSystem {
+  constructor(private userService: UserService, private accessToken: string) {}
+
+  async handleNewCustomer(userId: string) {
+    // Lấy thông tin customer
+    const userInfo = await this.userService.getUserInfo(this.accessToken, userId);
+
+    // Thêm tag "NEW_CUSTOMER"
+    await this.userService.addTagToUser(this.accessToken, {
+      user_id: userId,
+      tag_name: "NEW_CUSTOMER"
+    });
+
+    // Cập nhật custom info
+    await this.userService.updateUserCustomInfo(this.accessToken, {
+      user_id: userId,
+      custom_info: {
+        registration_date: new Date().toISOString(),
+        customer_tier: "STANDARD",
+        total_interactions: "1"
+      }
+    });
+
+    console.log(`New customer ${userInfo.display_name} processed`);
+  }
+
+  async promoteToVIP(userId: string) {
+    // Remove old tags
+    await this.userService.removeTagFromUser(this.accessToken, {
+      user_id: userId,
+      tag_name: "STANDARD"
+    });
+
+    // Add VIP tag
+    await this.userService.addTagToUser(this.accessToken, {
+      user_id: userId,
+      tag_name: "VIP"
+    });
+
+    // Update custom info
+    await this.userService.updateUserCustomInfo(this.accessToken, {
+      user_id: userId,
+      custom_info: {
+        customer_tier: "VIP",
+        promotion_date: new Date().toISOString()
+      }
+    });
+  }
+}
+
+}
+```
+
+### 2. Bulk Campaign System
+
+```typescript
+class BulkCampaignSystem {
+  constructor(private userService: UserService, private accessToken: string) {}
+
+  async runSegmentedCampaign(campaignConfig: {
+    segments: string[];
+    message: string;
+    batchSize?: number;
+  }) {
+    const results = {
+      totalSent: 0,
+      totalFailed: 0,
+      segmentResults: new Map<string, any>()
+    };
+
+    for (const segment of campaignConfig.segments) {
+      console.log(`Processing segment: ${segment}`);
+
+      // Get users by tag
+      const users = await this.userService.getUsersByTag(
+        this.accessToken,
+        segment,
+        0,
+        1000
+      );
+
+      // Bulk add campaign tag
+      const userIds = users.users.map(u => u.user_id);
+      const bulkResult = await this.userService.bulkAddTag(
+        this.accessToken,
+        userIds,
+        `CAMPAIGN_${Date.now()}`
+      );
+
+      results.segmentResults.set(segment, {
+        totalUsers: users.total,
+        tagged: bulkResult.success.length,
+        failed: bulkResult.failed.length
+      });
+
+      results.totalSent += bulkResult.success.length;
+      results.totalFailed += bulkResult.failed.length;
+    }
+
+    return results;
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+import { ZaloSDKError } from "@warriorteam/redai-zalo-sdk";
+
+try {
+  const userInfo = await userService.getUserInfo(accessToken, "user-id");
+  console.log("User found:", userInfo.display_name);
+} catch (error) {
+  if (error instanceof ZaloSDKError) {
+    switch (error.code) {
+      case -216:
+        console.error("Access token không hợp lệ");
+        break;
+      case -233:
+        console.error("User không tồn tại hoặc đã unfollow");
+        break;
+      case -201:
+        console.error("Tham số không hợp lệ");
+        break;
+      default:
+        console.error("Lỗi khác:", error.message);
+    }
+  } else {
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+## Giới Hạn API
+
+### Zalo API Limits
+
+1. **User List Pagination**:
+   - Max offset: 9951
+   - Max count per request: 50
+   - Tối đa ~10000 users có thể lấy được
+
+2. **Rate Limiting**:
+   - Nên có delay giữa các requests
+   - Sử dụng batch operations khi có thể
+
+3. **Custom Info**:
+   - Cấu trúc phụ thuộc vào thiết lập OA
+   - Tất cả giá trị đều là string
+
+## Best Practices
+
+### 1. Performance Optimization
+
+```typescript
+// ✅ Sử dụng getAllUserIds cho performance tốt hơn
+const userIds = await userService.getAllUserIds(accessToken);
+
+// ✅ Batch operations
+const bulkResult = await userService.bulkAddTag(
+  accessToken,
+  userIds.slice(0, 100),
+  "NEW_TAG"
+);
+
+// ✅ Pagination với reasonable page size
+const users = await userService.getUserList(accessToken, {
+  offset: 0,
+  count: 50 // Không quá 50
+});
+```
+
+### 2. Error Handling
+
+```typescript
+// ✅ Validate user ID format
+function validateUserId(userId: string): boolean {
+  return /^[0-9]+$/.test(userId) && userId.length > 0;
+}
+
+// ✅ Safe operations
+async function safeGetUser(userId: string) {
+  if (!validateUserId(userId)) {
+    throw new Error("Invalid user ID format");
+  }
+
+  try {
+    return await userService.getUserInfo(accessToken, userId);
+  } catch (error) {
+    if (error.code === -233) {
+      return null; // User not found
+    }
+    throw error;
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Q: "User not found" error**
+```
+A: User có thể đã unfollow OA hoặc chặn OA.
+   Kiểm tra is_follower field trước.
+```
+
+**Q: Không lấy được phone number**
+```
+A: Phone chỉ có khi user đã share với OA.
+   Sử dụng request_user_info để yêu cầu.
+```
+
+**Q: getAllUsers không lấy hết**
+```
+A: Zalo giới hạn max offset = 9951.
+   Chỉ lấy được ~10000 users đầu tiên.
+```
+
+**Q: Custom info không cập nhật**
+```
+A: Kiểm tra cấu trúc custom_info trong OA settings.
+   Tất cả values phải là string.
+```
+
+## Tài Liệu Liên Quan
+
+- [Zalo Official Account API](https://developers.zalo.me/docs/api/official-account-api)
+- [User Management API](https://developers.zalo.me/docs/api/official-account-api/quan-ly-nguoi-dung)
+- [Tag Management API](https://developers.zalo.me/docs/api/official-account-api/quan-ly-nhan)
+- [Consultation Service](./CONSULTATION_SERVICE.md)
+- [Tag Management](./TAG_MANAGEMENT.md)
+