@warriorteam/redai-zalo-sdk/docs/GROUP_MANAGEMENT.md

Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Group Messaging, and Social APIs

# Group Management Service

The `GroupManagementService` provides comprehensive group management capabilities for Zalo Official Account (OA) using the Group Message Framework (GMF).

## Features

- ✅ Create new groups with asset_id
- ✅ Update group information and avatar
- ✅ Invite and remove members
- ✅ Manage pending member requests
- ✅ Add and remove admin rights
- ✅ Delete groups
- ✅ Get group information and member lists
- ✅ Manage group quota and assets
- ✅ Get conversation history

## Prerequisites

1. **OA Requirements:**
   - OA must be granted GMF (Group Message Framework) permissions
   - Access token must have "manage_group" and "group_message" scopes
   - OA must have active status and be verified

2. **Limits:**
   - Maximum groups: 10-100 (depends on service package)
   - Maximum members per group: 200 people
   - Group creation frequency: max 10 groups/day
   - Member invitation frequency: max 500 invitations/day

## Usage

### Initialize SDK

```typescript
import { ZaloSDK } from 'redai-zalo-sdk';

const sdk = new ZaloSDK({
  appId: 'your_app_id',
  appSecret: 'your_app_secret',
});

const groupManagement = sdk.groupManagement;
```

### 1. Create Group

```typescript
const groupData = {
  group_name: "Support Group",
  group_description: "Customer support group",
  asset_id: "your_asset_id", // Get from getAssetId()
  member_user_ids: ["user1", "user2", "user3"]
};

const result = await groupManagement.createGroup(accessToken, groupData);
console.log(`Group created with ID: ${result.group_id}`);
```

### 2. Get Group Information

```typescript
const groupInfo = await groupManagement.getGroupInfo(accessToken, groupId);
console.log('Group details:', groupInfo);
```

### 3. Update Group Information

```typescript
const updateData = {
  group_name: "New Group Name",
  description: "Updated description"
};

await groupManagement.updateGroupInfo(accessToken, groupId, updateData);
```

### 4. Invite Members

```typescript
const inviteData = {
  member_uids: ["user4", "user5"]
};

const result = await groupManagement.inviteMembers(accessToken, groupId, inviteData);
console.log(`Invited ${result.invited_count} members`);
```

### 5. Manage Pending Members

```typescript
// Get pending members
const pending = await groupManagement.getPendingMembers(accessToken, groupId);

// Accept pending members
const memberIds = pending.data?.members.map(m => m.user_id) || [];
await groupManagement.acceptPendingMembers(accessToken, groupId, memberIds);

// Or reject pending members
await groupManagement.rejectPendingMembers(accessToken, groupId, memberIds);
```

### 6. Manage Admins

```typescript
// Add admin rights
const adminData = { admin_uids: ["user1"] };
await groupManagement.addAdmins(accessToken, groupId, adminData);

// Remove admin rights
await groupManagement.removeAdmins(accessToken, groupId, adminData);
```

### 7. Get Asset ID for Group Creation

```typescript
// Get single asset_id
const assetId = await groupManagement.getAssetId(accessToken);

// Get all available asset_ids
const assets = await groupManagement.getAssetIds(accessToken);
console.log('Available assets:', assets.data);
```

### 8. Get Group Members

```typescript
const members = await groupManagement.getGroupMembers(accessToken, groupId, 0, 10);
console.log('Group members:', members.data?.members);
```

### 9. Remove Members

```typescript
const memberIds = ["user1", "user2"];
await groupManagement.removeMembers(accessToken, groupId, memberIds);
```

### 10. Delete Group

```typescript
await groupManagement.deleteGroup(accessToken, groupId);
console.log('Group deleted successfully');
```

### 11. Get Groups of OA

```typescript
const groups = await groupManagement.getGroupsOfOA(accessToken, 0, 20);
console.log(`Found ${groups.total} groups:`, groups.groups);
```

### 12. Get Group Quota

```typescript
import { GMFProductType, QuotaType } from 'redai-zalo-sdk';

const quota = await groupManagement.getGroupQuota(
  accessToken, 
  GMFProductType.GMF10, 
  QuotaType.SUB_QUOTA
);
console.log('Group quota:', quota);
```

## Error Handling

```typescript
try {
  const result = await groupManagement.createGroup(accessToken, groupData);
  console.log('Success:', result);
} catch (error) {
  if (error instanceof ZaloSDKError) {
    console.error('Zalo API Error:', error.message, error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Complete Example

```typescript
import { ZaloSDK, GMFProductType } from 'redai-zalo-sdk';

class GroupManager {
  private sdk: ZaloSDK;
  
  constructor() {
    this.sdk = new ZaloSDK({
      appId: process.env.ZALO_APP_ID!,
      appSecret: process.env.ZALO_APP_SECRET!,
    });
  }

  async createAndManageGroup(accessToken: string) {
    try {
      // 1. Get asset_id for group creation
      const assetId = await this.sdk.groupManagement.getAssetId(accessToken);
      
      // 2. Create new group
      const newGroup = await this.sdk.groupManagement.createGroup(accessToken, {
        group_name: "Support Team",
        description: "Customer support team",
        asset_id: assetId,
        member_uids: ["user1", "user2"]
      });
      
      // 3. Invite more members
      await this.sdk.groupManagement.inviteMembers(accessToken, newGroup.group_id, {
        member_uids: ["user3", "user4"]
      });
      
      // 4. Add admin
      await this.sdk.groupManagement.addAdmins(accessToken, newGroup.group_id, {
        admin_uids: ["user1"]
      });
      
      // 5. Get group info
      const groupInfo = await this.sdk.groupManagement.getGroupInfo(accessToken, newGroup.group_id);
      
      return groupInfo;
    } catch (error) {
      console.error('Group management error:', error);
      throw error;
    }
  }
}
```

## API Reference

For detailed API documentation, see the TypeScript definitions in the source code. All methods include comprehensive JSDoc comments with parameter descriptions and return types.