群组 API - YumeBot

群组 API 提供全面的群管理功能，包括成员管理、信息查询、公告、精华消息等。

概述

在插件中通过 groupApi 属性访问：

class MyPlugin : PluginPackage() {
    override suspend fun onBotContextReady() {
        groupApi?.setGroupBan(groupId, userId, 600)
    }
}

群成员管理

setGroupKick

踢出群成员。

suspend fun setGroupKick(
    groupId: Long,
    userId: Long,
    rejectAddRequest: Boolean = false
): Boolean

groupId

Long

required

群号

userId

Long

required

要踢出的 QQ 号

rejectAddRequest

Boolean

是否拒绝此人的加群请求，默认 false

示例

groupApi?.setGroupKick(123456789L, 987654321L, rejectAddRequest = true)

setGroupBan

禁言群成员。

suspend fun setGroupBan(
    groupId: Long,
    userId: Long,
    duration: Int = 1800
): Boolean

groupId

Long

required

群号

userId

Long

required

要禁言的 QQ 号

duration

Int

禁言时长（秒），0 表示取消禁言，默认 1800 秒（30 分钟）

示例

// 禁言 10 分钟
groupApi?.setGroupBan(123456789L, 987654321L, 600)

// 解除禁言
groupApi?.setGroupBan(123456789L, 987654321L, 0)

setGroupWholeBan

全群禁言。

suspend fun setGroupWholeBan(
    groupId: Long,
    enable: Boolean = true
): Boolean

groupId

Long

required

群号

enable

Boolean

是否开启全群禁言，默认 true

示例

// 开启全群禁言
groupApi?.setGroupWholeBan(123456789L, true)

// 关闭全群禁言
groupApi?.setGroupWholeBan(123456789L, false)

setGroupAdmin

设置群管理员。

suspend fun setGroupAdmin(
    groupId: Long,
    userId: Long,
    enable: Boolean = true
): Boolean

groupId

Long

required

群号

userId

Long

required

QQ 号

enable

Boolean

true 设置管理员，false 取消管理员，默认 true

示例

// 设置管理员
groupApi?.setGroupAdmin(123456789L, 987654321L, true)

// 取消管理员
groupApi?.setGroupAdmin(123456789L, 987654321L, false)

群名片与头衔

setGroupCard

设置群名片。

suspend fun setGroupCard(
    groupId: Long,
    userId: Long,
    card: String
): Boolean

groupId

Long

required

群号

userId

Long

required

QQ 号

card

String

required

群名片，空字符串表示删除群名片

示例

// 设置群名片
groupApi?.setGroupCard(123456789L, 987654321L, "管理员")

// 删除群名片
groupApi?.setGroupCard(123456789L, 987654321L, "")

setGroupSpecialTitle

设置群头衔。

suspend fun setGroupSpecialTitle(
    groupId: Long,
    userId: Long,
    specialTitle: String,
    duration: Int = -1
): Boolean

groupId

Long

required

群号

userId

Long

required

QQ 号

specialTitle

String

required

头衔，空字符串表示删除头衔

duration

Int

有效期（秒），-1 表示永久，默认 -1

示例

// 设置头衔
groupApi?.setGroupSpecialTitle(123456789L, 987654321L, "群宠", -1)

// 删除头衔
groupApi?.setGroupSpecialTitle(123456789L, 987654321L, "")

群信息管理

setGroupName

设置群名。

suspend fun setGroupName(
    groupId: Long,
    groupName: String
): Boolean

groupId

Long

required

群号

groupName

String

required

新群名

示例

groupApi?.setGroupName(123456789L, "新的群名称")

setGroupPortrait

设置群头像。

suspend fun setGroupPortrait(
    groupId: Long,
    file: String,
    cache: Int = 1
): Boolean

groupId

Long

required

群号

file

String

required

图片文件路径

cache

Int

是否使用缓存，默认 1

示例

groupApi?.setGroupPortrait(123456789L, "C:/images/avatar.jpg")

setGroupLeave

退出群聊。

suspend fun setGroupLeave(
    groupId: Long,
    isDismiss: Boolean = false
): Boolean

groupId

Long

required

群号

isDismiss

Boolean

是否解散群（仅群主可用），默认 false

示例

// 退出群聊
groupApi?.setGroupLeave(123456789L, false)

// 解散群（群主）
groupApi?.setGroupLeave(123456789L, true)

群信息查询

getGroupInfo

获取群信息。

suspend fun getGroupInfo(
    groupId: Long,
    noCache: Boolean = false
): GetGroupInfoResponse?

groupId

Long

required

群号

noCache

Boolean

是否不使用缓存，默认 false

返回值

data class GetGroupInfoResponse(
    val status: String,
    val retcode: Int,
    val data: GroupInfo
)

data class GroupInfo(
    val groupId: Long,
    val groupName: String,
    val memberCount: Int,
    val maxMemberCount: Int
)

示例

val info = groupApi?.getGroupInfo(123456789L)
if (info != null) {
    logger.info("群名：${info.data.groupName}")
    logger.info("成员数：${info.data.memberCount}")
}

getGroupList

获取群列表。

suspend fun getGroupList(): GetGroupListResponse?

返回值

data class GetGroupListResponse(
    val status: String,
    val retcode: Int,
    val data: List<GroupInfo>
)

示例

val groupList = groupApi?.getGroupList()
groupList?.data?.forEach { group ->
    logger.info("群号：${group.groupId}，群名：${group.groupName}")
}

getGroupMemberInfo

获取群成员信息。

suspend fun getGroupMemberInfo(
    groupId: Long,
    userId: Long,
    noCache: Boolean = false
): GetGroupMemberInfoResponse?

groupId

Long

required

群号

userId

Long

required

QQ 号

noCache

Boolean

是否不使用缓存，默认 false

返回值

data class GroupMemberInfo(
    val groupId: Long,
    val userId: Long,
    val nickname: String,
    val card: String,
    val sex: String,
    val age: Int,
    val area: String,
    val joinTime: Long,
    val lastSentTime: Long,
    val level: String,
    val role: String,
    val unfriendly: Boolean,
    val title: String,
    val titleExpireTime: Long,
    val cardChangeable: Boolean
)

示例

val memberInfo = groupApi?.getGroupMemberInfo(123456789L, 987654321L)
if (memberInfo != null) {
    logger.info("昵称：${memberInfo.data.nickname}")
    logger.info("角色：${memberInfo.data.role}")
}

getGroupMemberList

获取群成员列表。

suspend fun getGroupMemberList(
    groupId: Long,
    noCache: Boolean = false
): GetGroupMemberListResponse?

groupId

Long

required

群号

noCache

Boolean

是否不使用缓存，默认 false

返回值

data class GetGroupMemberListResponse(
    val status: String,
    val retcode: Int,
    val data: List<GroupMemberInfo>
)

示例

val memberList = groupApi?.getGroupMemberList(123456789L)
memberList?.data?.forEach { member ->
    logger.info("成员：${member.nickname}（${member.userId}）")
}

getGroupInfoEx

获取群组额外信息。

suspend fun getGroupInfoEx(groupId: Long): GetGroupInfoExResponse?

groupId

Long

required

群号

示例

val extraInfo = groupApi?.getGroupInfoEx(123456789L)

群荣誉信息

getGroupHonorInfo

获取群荣誉信息。

suspend fun getGroupHonorInfo(
    groupId: Long,
    type: String = "all"
): GetGroupHonorInfoResponse?

groupId

Long

required

群号

type

String

荣誉类型：talkative、performer、legend、strong_newbie、emotion、all，默认 all

荣誉类型说明

类型	说明
`talkative`	龙王
`performer`	群聊之火
`legend`	群聊炽焰
`strong_newbie`	冒尖小春笋
`emotion`	快乐源泉
`all`	所有荣誉

示例

val honor = groupApi?.getGroupHonorInfo(123456789L, "talkative")

群请求处理

setGroupAddRequest

处理加群请求/邀请。

suspend fun setGroupAddRequest(
    flag: String,
    subType: String,
    approve: Boolean = true,
    reason: String = ""
): Boolean

flag

String

required

加群请求的 flag（从 GroupRequest 事件中获取）

subType

String

required

请求类型：add 或 invite

approve

Boolean

是否同意请求/邀请，默认 true

reason

String

拒绝理由（仅拒绝时有效）

示例

pluginContext.onRequest(
    filter = { it is GroupRequest }
) { event ->
    if (event is GroupRequest) {
        groupApi?.setGroupAddRequest(
            flag = event.flag,
            subType = event.subType,
            approve = true
        )
    }
}

getGroupSystemMsg

获取群系统消息。

suspend fun getGroupSystemMsg(): GetGroupSystemMsgResponse?

示例

val systemMsg = groupApi?.getGroupSystemMsg()

getGroupIgnoreAddRequest

获取群组忽略的通知。

suspend fun getGroupIgnoreAddRequest(
    groupId: Long
): GetGroupIgnoreAddRequestResponse?

groupId

Long

required

群号

示例

val ignoredRequests = groupApi?.getGroupIgnoreAddRequest(123456789L)

精华消息

getEssenceMsgList

获取精华消息列表。

suspend fun getEssenceMsgList(
    groupId: Long
): GetEssenceMsgListResponse?

groupId

Long

required

群号

示例

val essenceList = groupApi?.getEssenceMsgList(123456789L)

setEssenceMsg

设置精华消息。

suspend fun setEssenceMsg(messageId: Long): Boolean

messageId

Long

required

消息 ID

示例

groupApi?.setEssenceMsg(messageId)

deleteEssenceMsg

移出精华消息。

suspend fun deleteEssenceMsg(messageId: Long): Boolean

messageId

Long

required

消息 ID

示例

groupApi?.deleteEssenceMsg(messageId)

群公告

sendGroupNotice

发送群公告。

suspend fun sendGroupNotice(
    groupId: Long,
    content: String,
    image: String = ""
): Boolean

groupId

Long

required

群号

content

String

required

公告内容

image

String

公告图片，可选

示例

groupApi?.sendGroupNotice(
    groupId = 123456789L,
    content = "群规更新，请查看"
)

getGroupNotice

获取群公告列表。

suspend fun getGroupNotice(groupId: Long): GetGroupNoticeResponse?

groupId

Long

required

群号

示例

val notices = groupApi?.getGroupNotice(123456789L)

delGroupNotice

删除群公告。

suspend fun delGroupNotice(
    groupId: Long,
    noticeId: String
): Boolean

groupId

Long

required

群号

noticeId

String

required

公告 ID

示例

groupApi?.delGroupNotice(123456789L, "notice_id_123")

群消息相关

getGroupMsgHistory

获取群消息历史记录。

suspend fun getGroupMsgHistory(
    groupId: Long,
    messageSeq: Long? = null
): GetGroupMsgHistoryResponse?

groupId

Long

required

群号

messageSeq

Long

消息序号，不提供则从最新消息开始

示例

val history = groupApi?.getGroupMsgHistory(123456789L)
history?.data?.messages?.forEach { msg ->
    logger.info("消息：${msg.rawMessage}")
}

markGroupMsgAsRead

标记群聊消息已读。

suspend fun markGroupMsgAsRead(groupId: Long): Boolean

groupId

Long

required

群号

示例

groupApi?.markGroupMsgAsRead(123456789L)

群互动

groupPoke

群聊戳一戳。

suspend fun groupPoke(
    groupId: Long,
    userId: Long
): Boolean

groupId

Long

required

群号

userId

Long

required

要戳的 QQ 号

示例

groupApi?.groupPoke(123456789L, 987654321L)

getGroupAtAllRemain

获取群 @全体成员剩余次数。

suspend fun getGroupAtAllRemain(
    groupId: Long
): GetGroupAtAllRemainResponse?

groupId

Long

required

群号

示例

val remain = groupApi?.getGroupAtAllRemain(123456789L)
if (remain != null) {
    logger.info("剩余次数：${remain.data.remainCount}")
}

群特殊功能

sendGroupSign

群打卡。

suspend fun sendGroupSign(groupId: Long): Boolean

groupId

Long

required

群号

示例

groupApi?.sendGroupSign(123456789L)

setGroupSign

群签到。

suspend fun setGroupSign(groupId: Long): Boolean

groupId

Long

required

群号

示例

groupApi?.setGroupSign(123456789L)

getGroupShutList

获取群聊被禁言用户列表。

suspend fun getGroupShutList(
    groupId: Long
): GetGroupShutListResponse?

groupId

Long

required

群号

示例

val shutList = groupApi?.getGroupShutList(123456789L)
shutList?.data?.forEach { user ->
    logger.info("被禁言：${user.userId}")
}

sendGroupAiRecord

群聊发送 AI 语音。

suspend fun sendGroupAiRecord(
    groupId: Long,
    character: String,
    text: String
): Boolean

groupId

Long

required

群号

character

String

required

AI 角色

text

String

required

语音文本

示例

groupApi?.sendGroupAiRecord(
    groupId = 123456789L,
    character = "narrator",
    text = "欢迎加入本群"
)

完整示例

群管理机器人

class GroupManagerPlugin : PluginPackage() {
    override suspend fun onBotContextReady() {
        // 关键词禁言
        pluginContext.onGroupMessage(
            filter = Filters.groupKeyword("广告", "刷屏")
        ) { event ->
            if (event.sender.role in listOf("admin", "owner")) {
                return@onGroupMessage
            }
            
            groupApi?.setGroupBan(event.groupId, event.userId, 600)
            
            val reply = message {
                text("检测到违规内容，已禁言 10 分钟")
            }.build()
            messageApi?.sendGroupMessage(event.groupId, reply)
        }
        
        // 管理命令
        pluginContext.onGroupMessage(
            filter = Filters.groupStartsWith("/ban")
        ) { event ->
            if (event.sender.role !in listOf("admin", "owner")) {
                return@onGroupMessage
            }
            
            val atList = event.message.filterIsInstance<OB11Segment.At>()
            atList.forEach { at ->
                groupApi?.setGroupBan(
                    event.groupId,
                    at.data.qq.toLong(),
                    600
                )
            }
        }
    }
}

欢迎新成员

pluginContext.onNotice(
    filter = { it is GroupIncreaseNotice }
) { event ->
    if (event is GroupIncreaseNotice) {
        delay(1000)
        
        val welcome = message {
            at(event.userId)
            text(" 欢迎加入本群！\n")
            text("请阅读群公告，遵守群规")
        }.build()
        
        messageApi?.sendGroupMessage(event.groupId, welcome)
    }
}

群信息查询

pluginContext.onGroupMessage(
    filter = Filters.groupExact("/groupinfo")
) { event ->
    val info = groupApi?.getGroupInfo(event.groupId)
    
    if (info != null) {
        val msg = message {
            text("【群信息】\n")
            text("群名：${info.data.groupName}\n")
            text("成员数：${info.data.memberCount}\n")
            text("上限：${info.data.maxMemberCount}")
        }.build()
        
        messageApi?.sendGroupMessage(event.groupId, msg)
    }
}

设置精华消息

pluginContext.onGroupMessage(
    filter = Filters.groupStartsWith("/essence")
) { event ->
    if (event.sender.role in listOf("admin", "owner")) {
        val success = groupApi?.setEssenceMsg(event.messageId)
        
        if (success == true) {
            val reply = message {
                text("已设置为精华消息")
            }.build()
            messageApi?.sendGroupMessage(event.groupId, reply)
        }
    }
}

发送群公告

pluginContext.onGroupMessage(
    filter = Filters.groupStartsWith("/notice ")
) { event ->
    if (event.sender.role !in listOf("admin", "owner")) {
        return@onGroupMessage
    }
    
    val content = event.rawMessage.removePrefix("/notice ")
    val success = groupApi?.sendGroupNotice(event.groupId, content)
    
    if (success == true) {
        val reply = message {
            text("群公告已发送")
        }.build()
        messageApi?.sendGroupMessage(event.groupId, reply)
    }
}

注意事项

大部分操作需要机器人有管理员或群主权限
无权限时操作会失败，返回 false 或 null
禁言时长最长 30 天（2592000 秒）
群主无法被设置为管理员或禁言
设置群头像、群名等操作可能有频率限制

使用 noCache = true 获取最新信息
群名片和头衔修改可能有频率限制
API 调用建议使用 ?. 安全调用避免空指针
精华消息需要管理员权限
@全体成员有次数限制，建议先查询剩余次数
消息历史记录有数量限制

开始使用

插件开发

API 参考

协议文档

示例代码

​概述

​群成员管理

​setGroupKick

​setGroupBan

​setGroupWholeBan

​setGroupAdmin

​群名片与头衔

​setGroupCard

​setGroupSpecialTitle

​群信息管理

​setGroupName

​setGroupPortrait

​setGroupLeave

​群信息查询

​getGroupInfo

​getGroupList

​getGroupMemberInfo

​getGroupMemberList

​getGroupInfoEx

​群荣誉信息

​getGroupHonorInfo

​群请求处理

​setGroupAddRequest

​getGroupSystemMsg

​getGroupIgnoreAddRequest

​精华消息

​getEssenceMsgList

​setEssenceMsg

​deleteEssenceMsg

​群公告

​sendGroupNotice

​getGroupNotice

​delGroupNotice

​群消息相关

​getGroupMsgHistory

​markGroupMsgAsRead

​群互动

​groupPoke

​getGroupAtAllRemain

​群特殊功能

​sendGroupSign

​setGroupSign

​getGroupShutList

​sendGroupAiRecord

​完整示例

​群管理机器人

​欢迎新成员

​群信息查询

​设置精华消息

​发送群公告

​注意事项

概述

群成员管理

setGroupKick

setGroupBan

setGroupWholeBan

setGroupAdmin

群名片与头衔

setGroupCard

setGroupSpecialTitle

群信息管理

setGroupName

setGroupPortrait

setGroupLeave

群信息查询

getGroupInfo

getGroupList

getGroupMemberInfo

getGroupMemberList

getGroupInfoEx

群荣誉信息

getGroupHonorInfo

群请求处理

setGroupAddRequest

getGroupSystemMsg

getGroupIgnoreAddRequest

精华消息

getEssenceMsgList

setEssenceMsg

deleteEssenceMsg

群公告

sendGroupNotice

getGroupNotice

delGroupNotice

群消息相关

getGroupMsgHistory

markGroupMsgAsRead

群互动

groupPoke

getGroupAtAllRemain

群特殊功能

sendGroupSign

setGroupSign

getGroupShutList

sendGroupAiRecord

完整示例

群管理机器人

欢迎新成员

群信息查询

设置精华消息

发送群公告

注意事项