群管理与账号操作 API 详解
约 1170 字大约 4 分钟
2026-03-19
QQManage 群管理、好友管理、个人资料与组合 Sugar 的完整参数表、返回值和示例。
通过 api.qq.manage.xxx() 调用。源码:ncatbot/api/qq/manage.py。
群管理
set_group_kick()
async def set_group_kick(
self, group_id: Union[str, int], user_id: Union[str, int],
reject_add_request: bool = False,
) -> None:踢出群成员。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| user_id | str | int | 是 | 要踢出的用户 QQ 号 |
| reject_add_request | bool | 否 | 是否拒绝再次加群,默认 False |
await api.qq.manage.set_group_kick(123456, 654321)set_group_ban()
async def set_group_ban(
self, group_id: Union[str, int], user_id: Union[str, int],
duration: int = 1800,
) -> None:禁言群成员。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| user_id | str | int | 是 | 要禁言的用户 QQ 号 |
| duration | int | 否 | 禁言时长(秒),默认 1800;0 表示解除禁言 |
# 禁言 10 分钟
await api.qq.manage.set_group_ban(123456, 654321, duration=600)
# 解除禁言
await api.qq.manage.set_group_ban(123456, 654321, duration=0)set_group_whole_ban()
async def set_group_whole_ban(
self, group_id: Union[str, int], enable: bool = True,
) -> None:全员禁言开关。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| enable | bool | 否 | True 开启全员禁言,False 关闭,默认 True |
await api.qq.manage.set_group_whole_ban(123456) # 开启全员禁言
await api.qq.manage.set_group_whole_ban(123456, False) # 关闭全员禁言set_group_admin()
async def set_group_admin(
self, group_id: Union[str, int], user_id: Union[str, int],
enable: bool = True,
) -> None:设置或取消管理员。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| user_id | str | int | 是 | 目标用户 QQ 号 |
| enable | bool | 否 | True 设置管理员,False 取消,默认 True |
set_group_card()
async def set_group_card(
self, group_id: Union[str, int], user_id: Union[str, int],
card: str = "",
) -> None:设置群名片。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| user_id | str | int | 是 | 目标用户 QQ 号 |
| card | str | 否 | 群名片内容,空字符串表示删除群名片 |
await api.qq.manage.set_group_card(123456, 654321, card="新名片")set_group_name()
async def set_group_name(
self, group_id: Union[str, int], name: str,
) -> None:修改群名。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| name | str | 是 | 新群名 |
set_group_leave()
async def set_group_leave(
self, group_id: Union[str, int], is_dismiss: bool = False,
) -> None:退出群聊。群主可选择解散。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| is_dismiss | bool | 否 | 是否解散群(仅群主有效),默认 False |
set_group_special_title()
async def set_group_special_title(
self, group_id: Union[str, int], user_id: Union[str, int],
special_title: str = "",
) -> None:设置群成员专属头衔。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| user_id | str | int | 是 | 目标用户 QQ 号 |
| special_title | str | 否 | 专属头衔,空字符串表示删除 |
send_group_notice()
async def send_group_notice(
self, group_id: Union[str, int], content: str, image: str = "",
) -> None:发布群公告。image 可选,为图片路径或 URL。
delete_group_notice()
async def delete_group_notice(
self, group_id: Union[str, int], notice_id: str,
) -> None:删除群公告。
set_essence_msg()
async def set_essence_msg(self, message_id: Union[str, int]) -> None:设置精华消息。
delete_essence_msg()
async def delete_essence_msg(self, message_id: Union[str, int]) -> None:移除精华消息。
set_group_kick_members()
async def set_group_kick_members(
self, group_id: Union[str, int], user_ids: list,
reject_add_request: bool = False,
) -> None:批量踢出群成员。
set_group_remark()
async def set_group_remark(
self, group_id: Union[str, int], remark: str,
) -> None:设置群备注。
set_group_sign()
async def set_group_sign(self, group_id: Union[str, int]) -> None:群签到。
set_group_todo()
async def set_group_todo(
self, group_id: Union[str, int], message_id: Union[str, int],
) -> None:设置群代办(Todo)。
set_group_portrait()
async def set_group_portrait(
self, group_id: Union[str, int], file: str,
) -> None:设置群头像。file 为图片路径或 URL。
账号与好友操作
set_friend_add_request()
async def set_friend_add_request(
self, flag: str, approve: bool = True, remark: str = "",
) -> None:处理加好友请求。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| flag | str | 是 | 加好友请求标识(从事件中获取) |
| approve | bool | 否 | 是否同意,默认 True |
| remark | str | 否 | 好友备注(仅同意时有效) |
await api.qq.manage.set_friend_add_request(flag=event.flag, approve=True, remark="通过")set_group_add_request()
async def set_group_add_request(
self, flag: str, sub_type: str, approve: bool = True, reason: str = "",
) -> None:处理加群请求。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| flag | str | 是 | 加群请求标识(从事件中获取) |
| sub_type | str | 是 | 请求子类型:"add" 或 "invite" |
| approve | bool | 否 | 是否同意,默认 True |
| reason | str | 否 | 拒绝理由(仅拒绝时有效) |
await api.qq.manage.set_group_add_request(
flag=event.flag, sub_type="add", approve=False, reason="不满足条件"
)set_friend_remark()
async def set_friend_remark(
self, user_id: Union[str, int], remark: str,
) -> None:设置好友备注。
delete_friend()
async def delete_friend(self, user_id: Union[str, int]) -> None:删除好友。
个人资料
set_self_longnick()
async def set_self_longnick(self, long_nick: str) -> None:设置个性签名。
set_qq_avatar()
async def set_qq_avatar(self, file: str) -> None:设置 QQ 头像。file 为图片路径或 URL。
set_qq_profile()
async def set_qq_profile(
self, nickname: str = "", company: str = "", email: str = "",
college: str = "", personal_note: str = "",
) -> None:设置个人资料。
set_online_status()
async def set_online_status(
self, status: int, ext_status: int = 0, custom_status: str = "",
) -> None:设置在线状态。
组合 Sugar
kick_and_block()
async def kick_and_block(
self,
group_id: Union[str, int],
user_id: Union[str, int],
message_id: Optional[Union[str, int]] = None,
) -> None:组合操作:撤回消息 → 踢出用户 → 拒绝再次加群。如果 message_id 不为 None,先撤回该消息。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| group_id | str | int | 是 | 群号 |
| user_id | str | int | 是 | 目标用户 QQ 号 |
| message_id | str | int | None | 否 | 要撤回的消息 ID |
# 撤回违规消息并踢出用户
await api.qq.manage.kick_and_block(123456, 654321, message_id=msg_id)版权所有
版权归属:huan-yp
