Skip to main content

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

Build docs developers (and LLMs) love