群组管理

群组管理用于治理群与超级群（groupType=super）：查看群资料、成员与禁言状态，执行成员禁言/踢出、全员禁言、转让群主、解散和群资料编辑。禁言写入既有 Group.muted / group_mute_all，群消息发送路径会真实返回 1009。

概念​

能力行为错误/边界
成员禁言写成员 muted/mutedUntil；群消息发送返回 1009durationSec 1–2592000（缺省 3600）；群主不可被禁言
踢出成员清理管理员/禁言/成员资料，回调 group.updated(members_removed)群主需先转让；非成员返回 4xx
全员禁言与 Open API group.mute-all 同一份状态；群主/管理员/白名单豁免durationSec 1–2592000，缺省永久
转让群主toUserId 必须是成员；旧群主降为管理员回调 group.updated(owner_transferred)
解散群移除群与群级附属状态（禁言/白名单/成员资料/频道/扩展），消息历史保留回调 group.destroyed；不可恢复
群资料name/notice/joinPolicy/extname 1–64、notice ≤1000、ext ≤20 键
  • 群列表只返回基础字段；成员、禁言、扩展与群消息计数在详情接口。
  • 超级群沿用同一套群组接口，用 groupType=super 区分；rev22 起消息/会话的超级群类型为 SUPER_GROUP(10)（存量 2+super 可读），频道/用户组见超级群指南。
  • 所有写操作都会记录操作日志（admin.groups.*）。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#groups（tab #groups：群组）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。
  • 已开通 group（超级群还需 supergroup）服务，否则相关接口 1021。

步骤​

  1. 定位群

    群列表支持 keyword 模糊搜索与分页；拿到 groupId 后打开详情。

  2. 查看成员与禁言状态

    成员分页按 owner→admin→member 排序，返回 online/muted/mutedUntil/testUser。

  3. 处置违规成员

    先禁言（可恢复），严重违规再踢出；群主需先转让才能被踢出。

  4. 全群管控

    全员禁言用于临时止损；解散用于违规群，解散前确认消息保留但群关系不可恢复。

  5. 验证生效

    被禁言成员用客户端或 Open API 发群消息，应返回 1009；操作日志中可见对应 action。

参数表​

操作方法与路径请求体 / 参数
群列表GET /api/admin/apps/{appkey}/groupskeyword、offset、limit
群详情GET /api/admin/apps/{appkey}/groups/{groupId}—
成员分页GET /api/admin/apps/{appkey}/groups/{groupId}/memberskeyword、offset、limit
成员禁言POST /api/admin/apps/{appkey}/groups/{groupId}/members/{userId}/mute{muted,durationSec?,reason?}
踢出成员POST /api/admin/apps/{appkey}/groups/{groupId}/members/{userId}/remove{reason?}
全员禁言POST /api/admin/apps/{appkey}/groups/{groupId}/mute-all{muted,durationSec?}
转让群主POST /api/admin/apps/{appkey}/groups/{groupId}/transfer{toUserId}
解散群POST /api/admin/apps/{appkey}/groups/{groupId}/dismiss{reason?}
群资料POST /api/admin/apps/{appkey}/groups/{groupId}/profile{name?,notice?,joinPolicy?,ext?}

示例​

列表 → 详情 → 禁言成员 → 全员禁言​

Shell
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/groups?limit=20" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/groups/g_demo" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/groups/g_demo/members/bob/mute" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"muted":true,"durationSec":600,"reason":"刷屏"}'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/groups/g_demo/mute-all" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"muted":true,"durationSec":3600}'

转让群主 → 踢人 → 解散​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/groups/g_demo/transfer" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"toUserId":"bob"}'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/groups/g_demo/members/carol/remove" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"reason":"违规"}'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/groups/g_demo/dismiss" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"reason":"违规群"}'

常见问题​

为什么禁言群主返回 4xx？​

群主不可被禁言；如需限制，应先用转让接口更换群主。

解散后消息还能查吗？​

能。解散只移除群与群级附属状态，消息历史保留供审计；客户端无法再进入该群。

成员禁言和全员禁言冲突吗？​

不冲突。成员禁言是个人状态；全员禁言是群级开关，群主/管理员/白名单豁免。

超级群频道成员能在这里管吗？​

不能。本页管群成员；频道与用户组使用 supergroup.channel.* / supergroup.usergroup.*。

相关链接​