Group API

NTQQGroupApi methods for managing groups and group members

Overview

The NTQQGroupApi class provides comprehensive methods for managing QQ groups, including group information, member management, permissions, and group settings.

Group Information

getGroups

Get list of all groups the bot is in.

async getGroups(forced: boolean = false)

forced · boolean · default: "false"

Whether to force refresh from server

return · Group[]

Array of group objects

Example:

const groups = await core.apis.GroupApi.getGroups(true);
groups.forEach(group => {
  console.log(`${group.groupName} (${group.groupCode})`);
});

fetchGroupDetail

Get detailed information about a specific group.

async fetchGroupDetail(groupCode: string)

groupCode · string · required

Group code/ID

return · GroupDetailInfo

Detailed group information object

Example:

const detail = await core.apis.GroupApi.fetchGroupDetail('123456789');
console.log('Group name:', detail.groupName);
console.log('Member count:', detail.memberCount);

searchGroup

Search for a group by group code.

async searchGroup(groupCode: string)

groupCode · string · required

Group code to search for

return · GroupInfo | undefined

Group information if found

Group Members

getGroupMember

Get information about a specific group member.

async getGroupMember(
  groupCode: string | number,
  memberUinOrUid: string | number
): Promise<GroupMember | undefined>

groupCode · string | number · required

Group code

memberUinOrUid · string | number · required

Member UIN or UID

return · GroupMember | undefined

Group member object if found

Example:

const member = await core.apis.GroupApi.getGroupMember('123456789', 'u_abc123');
if (member) {
  console.log('Member card:', member.cardName);
  console.log('Member role:', member.role);
}

getGroupMemberAll

Get all members of a group.

async getGroupMemberAll(groupCode: string, forced: boolean = false)

groupCode · string · required

Group code

forced · boolean · default: "false"

Force refresh from server

return · { result: { infos: Map<string, GroupMember> } }

Object containing map of member UID to GroupMember

getGroupMemberEx

Get extended information about a group member.

async getGroupMemberEx(
  groupCode: string,
  uid: string,
  forced: boolean = false,
  retry: number = 2
): Promise<GroupMember | undefined>

groupCode · string · required

Group code

uid · string · required

Member UID

forced · boolean · default: "false"

Force refresh from server

retry · number · default: "2"

Number of retry attempts

getMemberExtInfo

Get extended member information including level and title.

async getMemberExtInfo(groupCode: string, uin: string)

groupCode · string · required

Group code

uin · string · required

Member UIN

Member Management

kickMember

Kick members from a group.

async kickMember(
  groupCode: string,
  kickUids: string[],
  refuseForever: boolean = false,
  kickReason: string = ''
)

groupCode · string · required

Group code

kickUids · string[] · required

Array of member UIDs to kick

refuseForever · boolean · default: "false"

Whether to permanently ban from rejoining

kickReason · string · default: "''"

Reason for kicking

Example:

await core.apis.GroupApi.kickMember(
  '123456789',
  ['u_member1', 'u_member2'],
  false,
  'Violation of group rules'
);

banMember

Mute/unmute group members.

async banMember(
  groupCode: string,
  memList: Array<{ uid: string, timeStamp: number }>
)

groupCode · string · required

Group code

memList · Array<{ uid: string, timeStamp: number }> · required

Array of objects with uid and mute duration in seconds (0 to unmute)

Example:

// Mute for 10 minutes
await core.apis.GroupApi.banMember('123456789', [
  { uid: 'u_member1', timeStamp: 600 }
]);

// Unmute
await core.apis.GroupApi.banMember('123456789', [
  { uid: 'u_member1', timeStamp: 0 }
]);

banGroup

Enable or disable mute all in a group.

async banGroup(groupCode: string, shutUp: boolean)

groupCode · string · required

Group code

shutUp · boolean · required

true to enable mute all, false to disable

getGroupShutUpMemberList

Get list of muted members in a group.

async getGroupShutUpMemberList(groupCode: string): Promise<ShutUpGroupMember[]>

groupCode · string · required

Group code

return · ShutUpGroupMember[]

Array of muted member information

setMemberCard

Set a member’s group card (nickname in group).

async setMemberCard(
  groupCode: string,
  memberUid: string,
  cardName: string
)

groupCode · string · required

Group code

memberUid · string · required

Member UID

cardName · string · required

New card name

setMemberRole

Set a member’s role (admin/member).

async setMemberRole(
  groupCode: string,
  memberUid: string,
  role: NTGroupMemberRole
)

groupCode · string · required

Group code

memberUid · string · required

Member UID

role · NTGroupMemberRole · required

New role (admin or member)

Group Settings

setGroupName

Change group name.

async setGroupName(groupCode: string, groupName: string)

groupCode · string · required

Group code

groupName · string · required

New group name

setGroupRemark

Set remark/note for a group.

async setGroupRemark(groupCode: string, remark: string)

groupCode · string · required

Group code

remark · string · required

Remark text

setGroupAvatar

Set group avatar.

async setGroupAvatar(groupCode: string, filePath: string)

groupCode · string · required

Group code

filePath · string · required

Path to image file

setGroupAddOption

Set group join options.

async setGroupAddOption(
  groupCode: string,
  option: {
    addOption: number;
    groupQuestion?: string;
    groupAnswer?: string;
  }
)

groupCode · string · required

Group code

option.addOption · number · required

Join option: 4 (question + answer), 5 (question + admin approval)

option.groupQuestion · string

Question for joining (if addOption is 4 or 5)

option.groupAnswer · string

Answer to question (if addOption is 4)

Group Requests

getSingleScreenNotifies

Get group join/invite notifications.

async getSingleScreenNotifies(
  doubt: boolean,
  count: number
): Promise<GroupNotify[]>

doubt · boolean · required

Whether to get doubt/verification requests

count · number · required

Number of notifications to retrieve

return · GroupNotify[]

Array of group notifications

handleGroupRequest

Handle group join/invite requests.

async handleGroupRequest(
  doubt: boolean,
  notify: GroupNotify,
  operateType: NTGroupRequestOperateTypes,
  reason?: string
)

doubt · boolean · required

Whether this is a doubt request

notify · GroupNotify · required

Group notification object

operateType · NTGroupRequestOperateTypes · required

Operation type (approve/reject)

reason · string

Reason for rejection (optional)

clearGroupNotifiesUnreadCount

Clear unread count for group notifications.

async clearGroupNotifiesUnreadCount(doubt: boolean)

doubt · boolean · required

Whether to clear doubt notifications

Group Actions

quitGroup

Leave a group.

async quitGroup(groupCode: string)

groupCode · string · required

Group code to leave

quitGroupV2

Leave a group with option to delete local messages.

async quitGroupV2(
  GroupCode: string,
  needDeleteLocalMsg: boolean
)

GroupCode · string · required

Group code to leave

needDeleteLocalMsg · boolean · required

Whether to delete local messages

Group Files

creatGroupFileFolder

Create a folder in group files.

async creatGroupFileFolder(
  groupCode: string,
  folderName: string
)

groupCode · string · required

Group code

folderName · string · required

Name of folder to create

delGroupFile

Delete files from group.

async delGroupFile(
  groupCode: string,
  files: Array<string>
)

groupCode · string · required

Group code

files · Array<string> · required

Array of file IDs to delete

delGroupFileFolder

Delete a folder from group files.

async delGroupFileFolder(
  groupCode: string,
  folderId: string
)

groupCode · string · required

Group code

folderId · string · required

Folder ID to delete

getGroupFileCount

Get file count for groups.

async getGroupFileCount(groupCodes: Array<string>)

groupCodes · Array<string> · required

Array of group codes

Group Announcements

publishGroupBulletin

Publish a group announcement.

async publishGroupBulletin(
  groupCode: string,
  content: string,
  picInfo?: { id: string, width: number, height: number },
  pinned: number = 0,
  confirmRequired: number = 0
)

groupCode · string · required

Group code

content · string · required

Announcement content

picInfo · object

Optional image information

pinned · number · default: "0"

Whether to pin announcement

confirmRequired · number · default: "0"

Whether confirmation is required

deleteGroupBulletin

Delete a group announcement.

async deleteGroupBulletin(
  groupCode: string,
  noticeId: string
)

groupCode · string · required

Group code

noticeId · string · required

Notice ID to delete

uploadGroupBulletinPic

Upload image for group announcement.

async uploadGroupBulletinPic(
  groupCode: string,
  imageurl: string
)

groupCode · string · required

Group code

imageurl · string · required

Image URL or path

Group Essence

addGroupEssence

Add a message to group essence.

async addGroupEssence(groupCode: string, msgId: string)

groupCode · string · required

Group code

msgId · string · required

Message ID to add to essence

removeGroupEssence

Remove a message from group essence.

async removeGroupEssence(groupCode: string, msgId: string)

groupCode · string · required

Group code

msgId · string · required

Message ID to remove from essence

fetchGroupEssenceList

Get list of essence messages.

async fetchGroupEssenceList(groupCode: string)

groupCode · string · required

Group code

Utilities

createGrayTip

Create a gray tip message in group.

async createGrayTip(groupCode: string, tip: string)

groupCode · string · required

Group code

tip · string · required

Tip text to display

getGroupRemainAtTimes

Get remaining @all count for today.

async getGroupRemainAtTimes(groupCode: string)

groupCode · string · required

Group code

getArkJsonGroupShare

Get group share card in Ark JSON format.

async getArkJsonGroupShare(groupCode: string): Promise<string>

groupCode · string · required

Group code

return · string

Ark JSON string for group share