GroupApi

群管理模块，涵盖群信息查询、成员管理、禁言、公告、相册、待办等操作。

方法

群信息

方法	返回类型	说明
getGroupList()	Result<GroupInfo[]>	获取群列表
getGroupInfo(groupId: number)	Result<GroupInfo>	获取群信息
getGroupInfoEx(groupId: number)	Result<GroupInfoEx>	获取群扩展信息
getGroupDetailInfo(groupId: number)	Result<unknown>	获取群详细信息
getGroupMemberList(groupId: number)	Result<GroupMember[]>	获取群成员列表
getGroupMemberInfo(groupId: number, userId: number)	Result<GroupMember>	获取群成员信息

群管理

方法	返回类型	说明
setGroupKick(groupId: number, userId: number, rejectAddRequest?: boolean)	Result<void>	群组踢人
setGroupKickMembers(groupId: number, userIds: number[])	Result<void>	批量踢出群成员
setGroupBan(groupId: number, userId: number, duration?: number)	Result<void>	群组单人禁言（duration 秒，0 为解禁）
setGroupWholeBan(groupId: number, enable?: boolean)	Result<void>	群组全员禁言
setGroupAdmin(groupId: number, userId: number, enable?: boolean)	Result<void>	群组设置管理员
setGroupCard(groupId: number, userId: number, card: string)	Result<void>	设置群名片（群备注）
setGroupName(groupId: number, name: string)	Result<void>	设置群名称
setGroupLeave(groupId: number, isDismiss?: boolean)	Result<void>	退出群组
setGroupSpecialTitle(groupId: number, userId: number, title: string)	Result<void>	设置群组专属头衔
setGroupRemark(groupId: number, remark: string)	Result<void>	设置群备注
setGroupPortrait(groupId: number, file: string)	Result<void>	设置群头像
setGroupSign(groupId: number)	Result<void>	群签到
sendGroupSign(groupId: number)	Result<void>	群打卡
getGroupHonorInfo(groupId: number, type: HonorType)	Result<GroupHonor>	获取群荣誉信息
getGroupAtAllRemain(groupId: number)	Result<GroupAtAllRemain>	获取群 @全体成员 剩余次数
getGroupSystemMsg(count?: number)	Result<GroupSystemMsg>	获取群系统消息
getGroupIgnoredNotifies()	Result<IgnoredRequest[]>	获取群通知忽略列表
getGroupShutList(groupId: number)	Result<GroupShutMember[]>	获取群禁言列表

精华消息

方法	返回类型	说明
setEssenceMsg(messageId: number)	Result<void>	设置精华消息
deleteEssenceMsg(messageId: number)	Result<void>	移出精华消息
getEssenceMsgList(groupId: number)	Result<EssenceMsg[]>	获取精华消息列表

群公告

方法	返回类型	说明
sendGroupNotice(groupId: number, content: string, image?: string, pinned?: number, type?: number, confirmRequired?: number, isShowEditCard?: number, tipWindowType?: number)	Result<void>	发送群公告
getGroupNotice(groupId: number)	Result<GroupNotice[]>	获取群公告
deleteGroupNotice(groupId: number, noticeId: string)	Result<void>	删除群公告

群相册

方法	返回类型	说明
getQunAlbumList(groupId: number, attachInfo?: string)	Result<unknown[]>	获取群相册列表
getGroupAlbumMediaList(groupId: number, albumId: string, attachInfo?: string)	Result<unknown[]>	获取群相册媒体列表
delGroupAlbumMedia(groupId: number, albumId: string, lloc: string)	Result<void>	删除群相册媒体
setGroupAlbumMediaLike(groupId: number, albumId: string, batchId: string, lloc?: string)	Result<void>	点赞群相册媒体
cancelGroupAlbumMediaLike(groupId: number, albumId: string, batchId: string, lloc?: string)	Result<void>	取消点赞群相册媒体
doGroupAlbumComment(groupId: number, albumId: string, lloc: string, content: string)	Result<void>	发表群相册评论
uploadImageToQunAlbum(groupId: number, albumId: string, albumName: string, file: string)	Result<void>	上传图片到群相册
getGroupSignedList(groupId: number)	Result<unknown[]>	获取群今日打卡列表

群待办

方法	返回类型	说明
setGroupTodo(groupId: number, messageId: string, messageSeq: string)	Result<void>	设置群待办
completeGroupTodo(groupId: number, messageId: string, messageSeq: string)	Result<void>	完成群待办
cancelGroupTodo(groupId: number, messageId: string, messageSeq: string)	Result<void>	取消群待办

群设置

方法	返回类型	说明
setGroupAddOption(groupId: number, addType: number, groupQuestion?: string, groupAnswer?: string)	Result<void>	设置群加群选项
setGroupRobotAddOption(groupId: number, robotMemberSwitch?: number, robotMemberExamine?: number)	Result<void>	设置群机器人加群选项
setGroupSearch(groupId: number, noCodeFingerOpen?: boolean, noFingerOpen?: boolean)	Result<void>	设置群搜索选项

返回数据结构

GroupInfo

interface GroupInfo {
  group_id: number
  group_name: string
  member_count?: number
  max_member_count?: number
  [key: string]: unknown
}

GroupInfoEx

interface GroupInfoEx {
  group_id: number
  group_name: string
  member_count: number
  max_member_count: number
  [key: string]: unknown
}

GroupMember

interface GroupMember {
  group_id: number
  user_id: number
  nickname: string
  card?: string
  sex?: string
  age?: number
  area?: string
  join_time?: number
  last_sent_time?: number
  level?: string
  role: 'owner' | 'admin' | 'member'
  title?: string
  [key: string]: unknown
}

GroupAtAllRemain

interface GroupAtAllRemain {
  can_at_all: boolean
  remain_at_all_count_for_group: number
  remain_at_all_count_for_uin: number
  [key: string]: unknown
}

GroupShutMember

interface GroupShutMember {
  user_id: number
  ban_time: number
  [key: string]: unknown
}

EssenceMsg

interface EssenceMsg {
  sender_id: number
  sender_nick: string
  sender_time: number
  operator_id: number
  operator_nick: string
  operator_time: number
  message_id: number
  [key: string]: unknown
}

GroupNotice

interface GroupNotice {
  sender_id: number
  publish_time: number
  message: { text: string; images: unknown[] }
  [key: string]: unknown
}

HonorType

type HonorType = 'talkative' | 'performer' | 'legend' | 'strong_newbie' | 'emotion' | 'all'

示例

import { GroupApi } from '@aemeath-projects/napcat'

const group = new GroupApi(client)

// 获取群列表
const list = await group.getGroupList()
if (list.ok) {
  list.data.forEach((g) => console.log(g.group_id, g.group_name))
}

// 获取群成员信息
const member = await group.getGroupMemberInfo(123456789, 987654321)
if (member.ok) {
  console.log('昵称:', member.data.nickname, '角色:', member.data.role)
}

// 禁言用户 60 秒
const banResult = await group.setGroupBan(123456789, 987654321, 60)
if (banResult.ok) {
  console.log('禁言成功')
} else {
  console.error('禁言失败:', banResult.error.code, banResult.error.message)
}

// 获取精华消息列表
const essence = await group.getEssenceMsgList(123456789)
if (essence.ok) {
  essence.data.forEach((e) => console.log(e.message_id, e.sender_nick))
}