@warriorteam/redai-zalo-sdk
Version:
Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account v3.0, ZNS with Full Type Safety, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, Promotion Service v3.0 with Multip
413 lines • 18.1 kB
TypeScript
import { ZaloClient } from "../clients/zalo-client";
import { GroupCreateRequest, GroupCreateResult, GroupCreateData, GroupUpdateRequest, GroupUpdateResult, GroupAssetUpdateRequest, GroupAvatarUpdateRequest, GroupMemberInviteRequest, GroupInviteResult, RecentChatsResponse, GroupConversationResponse, GroupsOfOAResponse, GroupDetailResponse, GroupPendingMembersResponse, GroupAcceptPendingMembersResponse, GroupRemoveMembersResponse, GroupMembersResponse, GroupMemberInfo, GroupQuotaMessageResponse, AllGroupMembersResponse, GetAllMembersProgress, EnhancedGroupMember, AllGroupMembersWithDetailsResponse, GetAllMembersWithDetailsProgress, OAGroupItem, AllGroupsOfOAResponse } from "../types/group";
import { GMFProductType, QuotaType } from "../types/oa";
import { UserService } from "./user.service";
/**
* Service for handling Zalo Official Account Group Management Framework (GMF) APIs
*
* CONDITIONS FOR USING ZALO GMF GROUP MANAGEMENT:
*
* 1. GENERAL CONDITIONS:
* - OA must be granted permission to use GMF (Group Message Framework) feature
* - Access token must have "manage_group" and "group_message" scopes
* - OA must have active status and be verified
* - Must comply with limits on number of groups and members
*
* 2. CREATE NEW GROUP:
* - Group name: required, max 100 characters, no special characters
* - Description: optional, max 500 characters
* - Avatar: optional, JPG/PNG format, max 5MB
* - Initial members: max 200 people, must be users who have interacted with OA
* - OA automatically becomes admin of the group
*
* 3. MEMBER MANAGEMENT:
* - Only admins can invite/remove members
* - Invite members: max 50 people per time, users must have interacted with OA
* - Remove members: cannot remove other admins, must have at least 1 admin
* - Members can leave group themselves
*
* 4. ADMIN MANAGEMENT:
* - Only current admins can add/remove other admins
* - Must have at least 1 admin in group
* - OA always has admin rights and cannot be removed
*
* 5. LIMITS AND CONSTRAINTS:
* - Maximum groups: according to service package (usually 10-100 groups)
* - Maximum members per group: 200 people
* - Group creation frequency: max 10 groups/day
* - Member invitation frequency: max 500 invitations/day
*/
export declare class GroupManagementService {
private readonly client;
private readonly userService?;
private readonly endpoints;
constructor(client: ZaloClient, userService?: UserService);
/**
* Create GroupManagementService with UserService for enhanced member details
* @param client ZaloClient instance
* @param userService UserService instance for fetching detailed user info
* @returns GroupManagementService with enhanced capabilities
*/
static withUserService(client: ZaloClient, userService: UserService): GroupManagementService;
/**
* Create basic GroupManagementService without UserService
* @param client ZaloClient instance
* @returns GroupManagementService with basic capabilities only
*/
static basic(client: ZaloClient): GroupManagementService;
/**
* Create new group chat with asset_id
* @param accessToken OA access token
* @param groupData Group information to create
* @returns Created group information
*
* API: POST https://openapi.zalo.me/v3.0/oa/group/creategroupwithoa
*/
createGroup(accessToken: string, groupData: GroupCreateRequest): Promise<GroupCreateResult>;
/**
* Helper method to extract group data from create response
* @param response Full API response
* @returns Group data only
*/
extractGroupData(response: GroupCreateResult): GroupCreateData;
/**
* Helper method to extract group info from update response
* @param response Full API response
* @returns Group info only
*/
extractGroupInfo(response: GroupUpdateResult): {
group_id: string;
group_link: string;
name: string;
group_description: string;
avatar: string;
status: "enabled" | "disabled";
total_member: number;
max_member: string;
auto_delete_date: string;
};
/**
* Helper method to extract group settings from update response
* @param response Full API response
* @returns Group settings only
*/
extractGroupSettings(response: GroupUpdateResult): {
lock_send_msg: boolean;
join_appr: boolean;
enable_msg_history: boolean;
enable_link_join: boolean;
};
/**
* Helper method to extract asset info from update response
* @param response Full API response
* @returns Asset info only
*/
extractAssetInfo(response: GroupUpdateResult): {
asset_type: "gmf10" | "gmf50" | "gmf100";
asset_id: string;
valid_through: string;
auto_renew: string;
};
/**
* Update group asset (upgrade package or extend expiration)
* @param accessToken OA access token
* @param groupId Group ID
* @param assetId New asset ID for the group
* @returns Update result with full group information
*
* API: POST https://openapi.zalo.me/v3.0/oa/group/updateasset
*
* Use cases:
* - Increase member limit for the group
* - Extend group expiration when expired
*/
updateGroupAsset(accessToken: string, groupId: string, assetId: string): Promise<GroupUpdateResult>;
/**
* Update group asset (upgrade package or extend expiration) - Object parameter version
* @param accessToken OA access token
* @param updateData Asset update data
* @returns Update result with full group information
*
* API: POST https://openapi.zalo.me/v3.0/oa/group/updateasset
*/
updateGroupAsset(accessToken: string, updateData: GroupAssetUpdateRequest): Promise<GroupUpdateResult>;
/**
* Get detailed group information
* @param accessToken OA access token
* @param groupId Group ID
* @returns Detailed group information including group_info, asset_info and group_setting
*
* API: GET https://openapi.zalo.me/v3.0/oa/group/getgroup
*/
getGroupInfo(accessToken: string, groupId: string): Promise<GroupDetailResponse>;
/**
* Update group information
* @param accessToken OA access token
* @param groupId Group ID
* @param updateData Information to update
* @returns Update result with full group information
*
* API: POST https://openapi.zalo.me/v3.0/oa/group/updateinfo
*/
updateGroupInfo(accessToken: string, groupId: string, updateData: GroupUpdateRequest): Promise<GroupUpdateResult>;
/**
* Update group avatar
* @param accessToken OA access token
* @param groupId Group ID
* @param avatarData New avatar information
* @returns Update result
* @deprecated Use updateGroupInfo() with group_avatar field instead
*/
updateGroupAvatar(accessToken: string, groupId: string, avatarData: GroupAvatarUpdateRequest): Promise<{
success: boolean;
}>;
/**
* Invite members to group
* @param accessToken OA access token
* @param groupId Group ID
* @param inviteData List of user IDs to invite
* @returns Invitation result
*
* API: POST https://openapi.zalo.me/v3.0/oa/group/invite
*/
inviteMembers(accessToken: string, groupId: string, inviteData: GroupMemberInviteRequest): Promise<GroupInviteResult>;
/**
* Invite members to group - Array parameter version
* @param accessToken OA access token
* @param groupId Group ID
* @param memberUserIds Array of user IDs to invite
* @returns Invitation result
*
* API: POST https://openapi.zalo.me/v3.0/oa/group/invite
*/
inviteMembers(accessToken: string, groupId: string, memberUserIds: string[]): Promise<GroupInviteResult>;
/**
* Get list of pending members
* @param accessToken OA access token
* @param groupId Group ID
* @param offset Offset for pagination (default: 0)
* @param count Maximum number to return (default: 20, max: 50)
* @returns List of pending members
*/
getPendingMembers(accessToken: string, groupId: string, offset?: number, count?: number): Promise<GroupPendingMembersResponse>;
/**
* Accept pending members to group
* @param accessToken OA access token
* @param groupId Group ID
* @param memberUserIds List of user IDs to accept
* @returns Accept result
*/
acceptPendingMembers(accessToken: string, groupId: string, memberUserIds: string[]): Promise<GroupAcceptPendingMembersResponse>;
/**
* Reject pending members from group
* @param accessToken OA access token
* @param groupId Group ID
* @param memberUserIds List of user IDs to reject
* @returns Reject result
*/
rejectPendingMembers(accessToken: string, groupId: string, memberUserIds: string[]): Promise<GroupAcceptPendingMembersResponse>;
/**
* Remove members from group
* @param accessToken OA access token
* @param groupId Group ID
* @param memberUserIds List of user IDs to remove
* @returns Remove result
*/
removeMembers(accessToken: string, groupId: string, memberUserIds: string[]): Promise<GroupRemoveMembersResponse>;
/**
* Add admin rights to members - Array parameter version
* @param accessToken OA access token
* @param groupId Group ID
* @param memberUserIds Array of user IDs to add admin rights
* @returns Add admin result
*
* API: POST https://openapi.zalo.me/v3.0/oa/group/addadmins
*/
addAdmins(accessToken: string, groupId: string, memberUserIds: string[]): Promise<{
error: number;
message: string;
}>;
/**
* Remove admin rights from members - Array parameter version
* @param accessToken OA access token
* @param groupId Group ID
* @param memberUserIds Array of user IDs to remove admin rights
* @returns Remove admin result
*
* API: POST https://openapi.zalo.me/v3.0/oa/group/removeadmins
*/
removeAdmins(accessToken: string, groupId: string, memberUserIds: string[]): Promise<{
error: number;
message: string;
}>;
/**
* Delete group chat (Disband group)
* @param accessToken OA access token
* @param groupId Group ID to delete
* @returns Delete result
*/
deleteGroup(accessToken: string, groupId: string): Promise<{
error: number;
message: string;
}>;
/**
* Get list of OA groups
* @param accessToken OA access token
* @param offset Offset for pagination (default: 0)
* @param count Maximum number to return (default: 5, max: 50)
* @returns List of OA groups
*
* API: GET https://openapi.zalo.me/v3.0/oa/group/getgroupsofoa
*/
getGroupsOfOA(accessToken: string, offset?: number, count?: number): Promise<GroupsOfOAResponse>;
/**
* Get ALL groups of OA (custom function with automatic pagination)
* @param accessToken OA access token
* @param maxGroups Maximum number of groups to retrieve (default: unlimited)
* @param progressCallback Optional callback to track progress
* @returns All OA groups with pagination info
*
* This function automatically handles pagination to retrieve all groups,
* not limited by the 50-group API limit per request.
*/
getAllGroupsOfOA(accessToken: string, maxGroups?: number, progressCallback?: (progress: {
currentCount: number;
totalCount?: number;
percentage?: number;
isComplete: boolean;
}) => void): Promise<AllGroupsOfOAResponse>;
/**
* Get ALL groups of OA with simple interface (no progress tracking)
* @param accessToken OA access token
* @param maxGroups Maximum number of groups to retrieve (optional)
* @returns Array of all OA groups
*
* Simplified version of getAllGroupsOfOA that returns just the groups array
*/
getAllGroupsOfOASimple(accessToken: string, maxGroups?: number): Promise<OAGroupItem[]>;
/**
* Get group quota information and asset_id
* @param accessToken OA access token
* @param productType Product type (optional)
* @param quotaType Quota type (optional)
* @returns Group quota information including asset_id
*
* API: POST https://openapi.zalo.me/v3.0/oa/quota/group
*/
getGroupQuota(accessToken: string, productType?: GMFProductType, quotaType?: QuotaType): Promise<GroupQuotaMessageResponse>;
/**
* Get asset_id for creating GMF group
* @param accessToken OA access token
* @returns Asset_id for group creation
*/
getAssetId(accessToken: string): Promise<string>;
/**
* Get list of asset_ids available for creating GMF groups
* @param accessToken OA access token
* @returns List of asset_ids and quota information
*/
getAssetIds(accessToken: string): Promise<GroupQuotaMessageResponse>;
/**
* Get list of recent chats
* @param accessToken OA access token
* @param offset Offset for pagination (default: 0)
* @param count Maximum number to return (default: 5, max: 50)
* @returns List of recent chats
*
* API: GET https://openapi.zalo.me/v3.0/oa/group/listrecentchat
*/
getRecentChats(accessToken: string, offset?: number, count?: number): Promise<RecentChatsResponse>;
/**
* Lấy thông tin tin nhắn trong một nhóm
*
* Lưu ý: Ứng dụng cần được cấp quyền quản lý thông tin nhóm.
*
* @param accessToken Access token của Official Account
* @param groupId ID nhóm muốn query
* @param offset Offset muốn query (mặc định: 0)
* @param count Số lượng mong muốn query (mặc định: 5)
* @returns Lịch sử tin nhắn trong nhóm
*
* @example
* ```typescript
* const messages = await groupService.getGroupConversation(
* accessToken,
* 'f414c8f76fa586fbdfb4',
* 0,
* 2
* );
* ```
*
* API: GET https://openapi.zalo.me/v3.0/oa/group/conversation
*/
getGroupConversation(accessToken: string, groupId: string, offset?: number, count?: number): Promise<GroupConversationResponse>;
/**
* Get group members list from Zalo API
* @param accessToken OA access token
* @param groupId Group ID
* @param offset Offset for pagination (default: 0)
* @param count Maximum number to return (default: 5, max: 50)
* @returns Group members list
*/
getGroupMembers(accessToken: string, groupId: string, offset?: number, count?: number): Promise<GroupMembersResponse>;
/**
* Get ALL members of a group (custom function with automatic pagination)
* @param accessToken OA access token
* @param groupId Group ID
* @param maxMembers Maximum number of members to retrieve (default: unlimited)
* @param progressCallback Optional callback to track progress
* @returns All group members with pagination info
*
* This function automatically handles pagination to retrieve all members,
* not limited by the 50-member API limit per request.
*/
getAllGroupMembers(accessToken: string, groupId: string, maxMembers?: number, progressCallback?: (progress: GetAllMembersProgress) => void): Promise<AllGroupMembersResponse>;
/**
* Get ALL members of a group with simple interface (no progress tracking)
* @param accessToken OA access token
* @param groupId Group ID
* @param maxMembers Maximum number of members to retrieve (optional)
* @returns Array of all group members
*
* Simplified version of getAllGroupMembers that returns just the members array
*/
getAllGroupMembersSimple(accessToken: string, groupId: string, maxMembers?: number): Promise<GroupMemberInfo[]>;
/**
* Get ALL members of a group with DETAILED user information (advanced API)
* @param accessToken OA access token
* @param groupId Group ID
* @param maxMembers Maximum number of members to retrieve (default: unlimited)
* @param progressCallback Optional callback to track progress
* @param options Advanced options for fetching details
* @returns All group members with detailed user information
*
* This function:
* 1. First gets all basic member info using getAllGroupMembers()
* 2. Then fetches detailed user info for each member using UserService.getUserInfo()
* 3. Combines both basic and detailed info into EnhancedGroupMember objects
* 4. If detailed info fails to fetch, falls back to basic info only
* 5. Provides detailed progress tracking and statistics
*/
getAllGroupMembersWithDetails(accessToken: string, groupId: string, maxMembers?: number, progressCallback?: (progress: GetAllMembersWithDetailsProgress) => void, options?: {
/** Batch size for fetching user details (default: 10) */
detailBatchSize?: number;
/** Timeout for each user detail request in ms (default: 5000) */
detailTimeout?: number;
/** Whether to continue if UserService is not available (default: true) */
continueWithoutUserService?: boolean;
/** Maximum concurrent detail requests (default: 5) */
maxConcurrentRequests?: number;
}): Promise<AllGroupMembersWithDetailsResponse>;
/**
* Get ALL members of a group with detailed info - Simple interface
* @param accessToken OA access token
* @param groupId Group ID
* @param maxMembers Maximum number of members to retrieve (optional)
* @returns Array of enhanced group members with detailed info
*
* Simplified version that returns just the enhanced members array
*/
getAllGroupMembersWithDetailsSimple(accessToken: string, groupId: string, maxMembers?: number): Promise<EnhancedGroupMember[]>;
private handleGroupManagementError;
}
//# sourceMappingURL=group-management.service.d.ts.map