群组管理

群组（下文简称群）有固定的成员，适合班级群、项目群、兴趣群等场景。业务服务端可以按自己的业务关系建群，指定群主和初始成员，成员直接加入，不需要对方同意；也可以查询和修改应用内的任何群，封禁或解散违规的群。

本页先介绍群的基本概念，再说明群本身的接口。其他群组接口见：

群成员：添加和移出成员、设置管理员、禁言成员、修改群昵称；
群黑名单；
入群申请与邀请：用户在客户端申请加入、邀请他人的流程，以及查询这些记录；
用户的群：用户加入的群、用户的入群设置。

服务端不受群内角色的限制

用 App Token 调用时，你以应用管理者的身份操作，可以修改任何群、添加或移出任何成员，不受群主、管理员等角色的限制。只有几条规则对服务端同样有效：群主只能通过转让群主产生；群主不能被移出、禁言或拉入群黑名单，要处置群主请先转让。

建群不是幂等的

建群请求超时后重试，可能建出两个相同的群。建议把业务系统中的 ID（如班级 ID）写入群的自定义属性 attributes，重试前先按群主查询群列表，确认上次没有建成功再重试。

应用被限制为只读时，建群、添加成员、修改群资料和成员资料返回 403 app_unavailable；移出成员、禁言、全员禁言、群黑名单、转让群主、设置管理员、封禁和解封、解散等处置操作仍然可以使用，见限流与应用状态。

基本概念

群类型

类型	`type`	说明
私有群	`private`	默认类型。只能由成员邀请、通过入群链接或由服务端添加，非成员在客户端看不到这个群。适合同事群、家长群等
公开群	`public`	用户可以在客户端搜索到它，看到名称、头像、简介和人数，并申请加入；也可以由成员邀请加入。适合兴趣群、粉丝群

群创建后可以在两种类型之间切换。公开群改为私有群时，尚未处理的入群申请全部失效，即使之后又改回公开群也不会恢复；私有群改为公开群时，申请方式默认为需要审批。

成员角色

角色	`role`	说明
群主	`owner`	每个群一个。可以执行群内的全部管理操作，包括设置管理员、转让群主和解散群。群主不能被移出、禁言或拉入群黑名单；要退出群，须先把群主转让给其他成员
管理员	`admin`	每个群最多 20 个，由群主设置。可以修改群资料和设置（群类型除外）、审批入群申请、移出和禁言普通成员、管理群黑名单、开启全员禁言
普通成员	`member`	可以发言、修改自己的群昵称；能否邀请他人由群设置 `member_invite` 决定

以上是用户在客户端中的权限，服务端接口不受这些限制。

用户被删除后，系统会自动把他移出加入的全部群。他是群主的，群主自动转给加入最早的管理员，没有管理员时转给加入最早的普通成员；群里没有其他成员时解散该群。

加入群的方式

每个成员的 joined_via 记录了他是怎样加入的：

`joined_via`	方式
`create`	建群时加入：群主本人，以及建群时指定的初始成员
`server`	由服务端或控制台直接添加，见批量添加群成员
`invite`	被成员在客户端邀请加入。被邀请时是否需要本人确认由用户的入群设置决定
`apply`	在客户端申请加入公开群，按群的申请方式直接加入，或经群主、管理员审批后加入
`link`	通过群主或管理员生成的入群链接（或二维码）加入，私有群也可以这样加入

不论哪种方式，都要满足：群正常（未封禁、未解散）、用户不在群黑名单中、群人数未满、用户加入的群数未满。邀请和申请的完整流程见入群申请与邀请。

群设置

字段	取值	说明
`member_invite`	`free`（默认）、`approval`、`disabled`	普通成员能否邀请他人：`free` 可以直接邀请；`approval` 可以邀请，但要群主或管理员审批；`disabled` 不能邀请。群主和管理员不受这项设置的限制
`join_mode`	`approval`（默认）、`free`	公开群的申请方式：`approval` 需要群主或管理员审批；`free` 申请即加入。私有群不能申请加入，这个字段为 `null`，也不能设置
`mute_all`	`true`、`false`	全员禁言，开启后只有群主和管理员可以在客户端发言，见开启全员禁言
`max_members`	2 到 5000	群的人数上限（含群主）。应用的默认上限为运行策略中的 `max_group_members`（默认 500），且不超过应用套餐的群人数额度；没有单独设置时取应用的默认上限，单独设置后取两者中较小的一个。只能由服务端和控制台设置。调低到当前人数以下时不会移出成员，只是不能再加人

群状态

`status`	说明
`active`	正常
`disabled`	已封禁：成员保留，但不能发言、不能加入新成员，见封禁群
`dismissed`	已解散，不能恢复，见解散群

版本号

群带有两个版本号，每次变化加一：

info_version：群资料和设置的版本号。修改群资料和设置、转让群主、开启或关闭全员禁言、封禁、解封和解散都会让它加一。修改群资料和设置时可以在请求中带上读取到的 info_version（字段名为 version），防止覆盖别人同时做的修改，规则见并发修改。
member_version：成员列表的版本号。成员加入和离开，成员的角色、群昵称、成员属性、禁言状态变化时加一。查询群成员列表时可以带上保存的版本号，没有变化时不返回列表。

群头像

群头像 avatar_url 可以存放在本服务，也可以使用你自己的图片地址：

使用本服务的头像：以用途 group_avatar 上传图片（建群前就可以上传），完成上传后得到头像的公开地址，在创建群或修改群资料时填进 avatar_url。图片会被缩放到长边不超过 640 像素，公开地址任何人都可以直接访问。
头像文件的保留：服务按群资料中当前的 avatar_url 判断头像是否在使用。上传后 24 小时内没有被任何群使用的，以及被替换（改为其他地址或清空）7 天后的群头像文件会被删除。一个群头像文件只算作第一个用上它的群在使用。群解散后群头像保留，已解散的群仍显示原来的名称和头像。
使用你自己的地址：服务端接口写入的 avatar_url 只检查格式。成员在客户端建群或修改群头像时，如果应用在运行策略中开启了 media_url_only，只能使用本应用的头像地址或 media_allowed_hosts 中主机的 https 地址，否则返回 400 invalid_argument，details.reason 为 url_not_allowed，details.field 为 avatar_url。

群文件

群文件是群成员共享的文件，按上传时间倒序列在群里。与消息附件不同，群文件默认不过期，适合需要长期保存的资料：

上传：群成员可以在客户端上传群文件（用途 group_file，类型为图片、视频或文件），群被封禁时不能上传。应用可以在运行策略中关闭 group_file_enabled，这时只有你的服务端和控制台可以上传。服务端以用途 group_file 并带上 group_id 上传，不受成员身份、group_file_enabled 和封禁的限制，群不存在或已解散时返回 404 not_found。
下载和删除：在客户端只有当前的群成员能查看群文件列表和下载，成员离开后不能再下载；上传者本人、群主和管理员可以删除。你的服务端可以查看任何群的群文件列表、下载和删除，见下载与管理文件。
上限与保留：每个群最多 1000 个群文件，群文件计入应用的存储用量。默认一直保留，应用可以用运行策略 group_file_retention_days 设置保留天数。群解散时全部群文件被删除（通常在 1 分钟内），之后无法再下载。

创建群

创建一个群，指定群主和初始成员。群主和初始成员直接加入，不需要对方确认，不看用户的入群设置，也不调用加群前回调（它只对用户在客户端建群、邀请、申请和通过入群链接加入调用，见内容检查与加群前回调）。初始成员中有人加入失败（如用户不存在、已在群黑名单中、加入的群数已满）不影响建群，响应中逐个列出每个初始成员的结果。

建群后，群主和初始成员的在线设备会实时收到通知，群会话中会出现建群和成员加入的提示消息。这个接口按初始成员人数（至少 1）计入应用的调用额度，见限流与应用状态。

应用中未解散的群数不能超过应用套餐的群总数额度，见套餐与账单。群名称、简介、公告和头像要经过内容安全检查（你的服务端提交的默认只按平台规则检查，见服务端提交的内容）：不通过时不建群，返回 403 content_rejected；命中替换规则的，写入替换后的文本（命中的文字替换为 *），以响应为准。

POST/{org_name}/{app_name}/groups

路径参数

org_name、app_name 见接入概述。

请求体

字段	类型	必填	说明
`owner`	String	是	群主的用户名，必须是已存在的用户
`type`	String	否	群类型：`private`（默认）或 `public`
`name`	String	否	群名称，最长 64 个字符，不能包含换行等控制字符，首尾的空白会被去掉。默认为空字符串
`avatar_url`	String	否	群头像地址，以 `http://` 或 `https://` 开头，不超过 512 字节，不能包含空白。可以是本服务的群头像地址，也可以是你自己的地址，见群头像。服务端只校验格式，不会访问这个地址
`description`	String	否	群简介，最长 512 个字符，可以换行
`announcement`	String	否	群公告，最长 2048 个字符，可以换行
`attributes`	Object	否	自定义属性，字符串键值对，全体成员可见，可以用来保存业务系统中的 ID、群分类等。最多 32 项，JSON 编码后合计不超过 4 KB；键为 1 到 32 个字符，只能包含字母、数字和 `_`、`-`、`.`；值为字符串
`member_invite`	String	否	普通成员能否邀请他人：`free`（默认）、`approval` 或 `disabled`，见群设置
`join_mode`	String	否	公开群的申请方式：`approval`（默认）或 `free`。私有群不能设置
`max_members`	Number	否	群自己的人数上限，2 到 5000；省略或为 `null` 时使用应用的默认上限，见群设置
`members`	Array<String>	否	初始成员的用户名，最多 100 个，直接加入群，`joined_via` 为 `create`。重复的用户名只处理一次；包含群主本人时，这一项的结果为 `already_member`

请求示例

bash

curl -X POST "$IM_API/$ORG/$APP/groups" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "zhangsan",
    "type": "private",
    "name": "三年级二班家长群",
    "description": "家校沟通",
    "announcement": "本周五下午家长会",
    "attributes": { "class_id": "C-302" },
    "member_invite": "disabled",
    "max_members": 200,
    "members": ["lisi", "wangwu", "nobody", "zhangsan"]
  }'

响应

成功返回 201 Created，响应体为群组对象，另加一个字段：

字段	类型	说明
`results`	Array<Object>	每个初始成员的结果，按请求中的顺序排列，格式见批量操作结果。没有初始成员时为空数组

json

{
  "group_id": "99582624883802112",
  "type": "private",
  "name": "三年级二班家长群",
  "avatar_url": "",
  "description": "家校沟通",
  "announcement": "本周五下午家长会",
  "announcement_updated_at": "2026-10-02T19:05:47.929Z",
  "announcement_updated_by": null,
  "attributes": {
    "class_id": "C-302"
  },
  "owner": "zhangsan",
  "member_invite": "disabled",
  "join_mode": null,
  "mute_all": false,
  "max_members": 200,
  "member_count": 3,
  "status": "active",
  "disabled_by": null,
  "info_version": 1,
  "member_version": 2,
  "created_at": "2026-10-02T19:05:47.929Z",
  "status_reason": null,
  "max_members_setting": 200,
  "created_via": "openapi",
  "dismissed_at": null,
  "results": [
    { "username": "lisi", "status": "joined" },
    { "username": "wangwu", "status": "joined" },
    { "username": "nobody", "code": "not_found", "message": "用户不存在" },
    { "username": "zhangsan", "status": "already_member" }
  ]
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	缺少 `owner`；字段取值不合法；为私有群设置了 `join_mode`；`members` 超过 100 个
403	`app_unavailable`	应用处于只读状态，不能建群
403	`content_rejected`	群资料未通过内容安全检查，`details.field` 为 `name`、`description`、`announcement` 或 `avatar_url`，`details.reason` 说明原因，见调用方看到的错误
404	`not_found`	`owner` 指定的用户不存在
409	`limit_exceeded`	`details.reason` 为 `user_group_limit`：群主加入的群数已达上限（应用运行策略 `max_groups_per_user`，默认 500，且不超过套餐的额度），不建群
409	`limit_exceeded`	`details.reason` 为 `app_group_limit`：应用中未解散的群数已达套餐的群总数额度，见套餐与账单

查询群列表

按创建时间从新到旧分页列出应用内的群，可以按类型、状态、群主筛选，按名称前缀搜索。已解散的群也在列表中，可以用 status 筛选掉。

GET/{org_name}/{app_name}/groups

路径参数

org_name、app_name 见接入概述。

查询参数

参数	类型	必填	说明
`type`	String	否	只列出这种类型的群：`private` 或 `public`
`status`	String	否	只列出这种状态的群：`active`、`disabled` 或 `dismissed`
`owner`	String	否	只列出这个用户担任群主的群；用户不存在时返回空列表
`name_prefix`	String	否	按群名称的前缀搜索，不区分大小写；`%` 和 `_` 按普通字符匹配
`limit`	Number	否	每页条数，默认 20，取值 1 到 100
`cursor`	String	否	下一页的游标，见分页

请求示例

bash

curl -X GET "$IM_API/$ORG/$APP/groups?owner=zhangsan&status=active&limit=20" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，items 中每项为一个群组对象，next_cursor 为下一页的游标，没有下一页时为 null。

json

{
  "items": [
    {
      "group_id": "99582624883802112",
      "type": "private",
      "name": "三年级二班家长群",
      "avatar_url": "https://cdn.example.com/group/c302.png",
      "description": "家校沟通",
      "announcement": "家长会改到周六上午 9 点，请准时参加",
      "announcement_updated_at": "2026-10-02T19:16:49.151Z",
      "announcement_updated_by": null,
      "attributes": {
        "class_id": "C-302",
        "term": "2026-autumn"
      },
      "owner": "zhangsan",
      "member_invite": "disabled",
      "join_mode": null,
      "mute_all": false,
      "max_members": 500,
      "member_count": 3,
      "status": "active",
      "disabled_by": null,
      "info_version": 17,
      "member_version": 18,
      "created_at": "2026-10-02T19:05:47.929Z",
      "status_reason": null,
      "max_members_setting": null,
      "created_via": "openapi",
      "dismissed_at": null
    }
  ],
  "next_cursor": null
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`type`、`status` 的取值不合法，或 `limit` 超出范围

查询群信息

返回一个群的全部信息。已解散的群也可以查询，status 为 dismissed。

GET/{org_name}/{app_name}/groups/{group_id}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求示例

bash

curl -X GET "$IM_API/$ORG/$APP/groups/99582624883802112" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，响应体为群组对象。

json

{
  "group_id": "99582624883802112",
  "type": "private",
  "name": "三年级二班家长群",
  "avatar_url": "https://cdn.example.com/group/c302.png",
  "description": "家校沟通",
  "announcement": "家长会改到周六上午 9 点，请准时参加",
  "announcement_updated_at": "2026-10-02T19:16:49.151Z",
  "announcement_updated_by": null,
  "attributes": {
    "class_id": "C-302",
    "term": "2026-autumn"
  },
  "owner": "zhangsan",
  "member_invite": "disabled",
  "join_mode": null,
  "mute_all": false,
  "max_members": 500,
  "member_count": 3,
  "status": "active",
  "disabled_by": null,
  "info_version": 17,
  "member_version": 18,
  "created_at": "2026-10-02T19:05:47.929Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "dismissed_at": null
}

错误

HTTP 状态码	`code`	说明
404	`not_found`	群不存在，或 `group_id` 的格式不对

修改群资料和设置

修改群的名称、头像、简介、公告、自定义属性和各项设置。只修改请求中出现的字段，没有出现的字段保持不变。修改后群的在线成员会实时收到通知；修改群名称和公告时，群会话中会出现相应的提示消息。

被封禁的群也可以修改，便于清除违规的名称、公告和头像。群主不能用这个接口修改，请使用转让群主。

修改的名称、简介、公告和头像要经过内容安全检查，只检查与原值不同、不为空的字段：不通过时不做任何修改，返回 403 content_rejected；命中替换规则的，写入替换后的文本。

PATCH/{org_name}/{app_name}/groups/{group_id}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求体

至少包含一个要修改的字段。各字段的格式要求与创建群相同。

字段	类型	必填	说明
`type`	String	否	群类型：`private` 或 `public`。公开群改为私有群时 `join_mode` 变为 `null`，尚未处理的入群申请全部失效；私有群改为公开群时 `join_mode` 默认为 `approval`，可以在同一个请求中另行指定
`name`	String	否	群名称，最长 64 个字符；传空字符串表示清空
`avatar_url`	String	否	群头像地址；传空字符串表示清空。替换或清空本服务的群头像后，原来的头像文件在 7 天后删除，见群头像
`description`	String	否	群简介，最长 512 个字符
`announcement`	String	否	群公告，最长 2048 个字符。公告变化时 `announcement_updated_at` 更新为当前时间
`attributes`	Object	否	按项合并：对象中出现的键被新增或覆盖，值为 `null` 的键被删除，没有出现的键保持不变。整个字段为 `null` 时清空全部自定义属性。合并后的结果须满足项数和大小的上限
`member_invite`	String	否	普通成员能否邀请他人：`free`、`approval` 或 `disabled`
`join_mode`	String	否	公开群的申请方式：`approval` 或 `free`。私有群不能设置
`max_members`	Number	否	群自己的人数上限，2 到 5000；为 `null` 时清除，改为使用应用的默认上限
`version`	Number	否	读取到的 `info_version`。带上时，与当前的 `info_version` 不一致则返回 `409 version_conflict`，不做任何修改

请求示例

bash

curl -X PATCH "$IM_API/$ORG/$APP/groups/99582624883802112" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "三年级二班家长群",
    "announcement": "家长会改到周六上午 9 点，请准时参加",
    "attributes": { "term": "2026-autumn", "grade": null },
    "max_members": null,
    "version": 16
  }'

响应

成功返回 200 OK，响应体为修改后的群组对象，另加一个字段：

字段	类型	说明
`changed`	Boolean	这次请求是否改变了群。请求中的值都与原值相同时为 `false`，`info_version` 不变，也不会通知成员

json

{
  "group_id": "99582624883802112",
  "type": "private",
  "name": "三年级二班家长群",
  "avatar_url": "https://cdn.example.com/group/c302.png",
  "description": "家校沟通",
  "announcement": "家长会改到周六上午 9 点，请准时参加",
  "announcement_updated_at": "2026-10-02T19:16:49.151Z",
  "announcement_updated_by": null,
  "attributes": {
    "class_id": "C-302",
    "term": "2026-autumn"
  },
  "owner": "zhangsan",
  "member_invite": "disabled",
  "join_mode": null,
  "mute_all": false,
  "max_members": 500,
  "member_count": 3,
  "status": "active",
  "disabled_by": null,
  "info_version": 17,
  "member_version": 18,
  "created_at": "2026-10-02T19:05:47.929Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "dismissed_at": null,
  "changed": true
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	没有任何要修改的字段；字段取值不合法；为私有群设置了 `join_mode`；请求中包含不能修改的字段（如 `owner`）
403	`app_unavailable`	应用处于只读状态，不能修改群资料
403	`content_rejected`	修改的群资料未通过内容安全检查，`details.field` 为 `name`、`description`、`announcement` 或 `avatar_url`
404	`not_found`	群不存在或已解散
409	`version_conflict`	`version` 与当前的 `info_version` 不一致，请重新查询后再决定是否修改

转让群主

把群主转给群里的另一个成员。转让后：

原群主变为普通成员；
新群主原来是管理员的，不再占用管理员名额；原来被禁言的，禁言自动解除；
原群主生成的入群链接失效；
info_version 和 member_version 各加一，群的在线成员实时收到通知，群会话中出现群主变更的提示消息。

被封禁的群也可以转让，便于处置群主本人的违规行为。

PUT/{org_name}/{app_name}/groups/{group_id}/owner

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求体

字段	类型	必填	说明
`username`	String	是	新群主的用户名，必须是这个群的成员。指定的就是当前群主时不做任何改变，`changed` 为 `false`

请求示例

bash

curl -X PUT "$IM_API/$ORG/$APP/groups/99582624883802112/owner" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "wangwu"
  }'

响应

成功返回 200 OK，响应体为转让后的群组对象，另加 changed 字段，含义同修改群资料和设置。

json

{
  "group_id": "99582624883802112",
  "type": "private",
  "name": "三年级二班家长群",
  "avatar_url": "https://cdn.example.com/group/c302.png",
  "description": "家校沟通",
  "announcement": "家长会改到周六上午 9 点，请准时参加",
  "announcement_updated_at": "2026-10-02T19:16:49.151Z",
  "announcement_updated_by": null,
  "attributes": {
    "class_id": "C-302",
    "term": "2026-autumn"
  },
  "owner": "wangwu",
  "member_invite": "disabled",
  "join_mode": null,
  "mute_all": false,
  "max_members": 500,
  "member_count": 3,
  "status": "active",
  "disabled_by": null,
  "info_version": 18,
  "member_version": 19,
  "created_at": "2026-10-02T19:05:47.929Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "dismissed_at": null,
  "changed": true
}

错误

HTTP 状态码	`code`	说明
403	`not_group_member`	指定的用户不是这个群的成员
404	`not_found`	群不存在或已解散；`username` 指定的用户不存在（省略 `username` 时同样返回这个错误）

开启全员禁言

开启后只有群主和管理员可以在客户端发言，普通成员发送群消息时返回 403 group_muted。全员禁言对群主和管理员的豁免不包括单独禁言：被禁言的管理员仍然不能发言。

群的在线成员会实时收到通知，群会话中出现开启全员禁言的提示消息。已经开启时再次调用不做任何改变，changed 为 false。被封禁的群也可以设置。

提示

禁言只限制用户在客户端发言。服务端以成员的身份发送消息时不受群内禁言和全员禁言的限制。

PUT/{org_name}/{app_name}/groups/{group_id}/mute-all

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求示例

bash

curl -X PUT "$IM_API/$ORG/$APP/groups/99582624883802112/mute-all" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，响应体为群组对象，另加 changed 字段，含义同修改群资料和设置。

json

{
  "group_id": "99582624883802112",
  "type": "private",
  "name": "三年级二班家长群",
  "avatar_url": "https://cdn.example.com/group/c302.png",
  "description": "家校沟通",
  "announcement": "家长会改到周六上午 9 点，请准时参加",
  "announcement_updated_at": "2026-10-02T19:16:49.151Z",
  "announcement_updated_by": null,
  "attributes": {
    "class_id": "C-302",
    "term": "2026-autumn"
  },
  "owner": "wangwu",
  "member_invite": "disabled",
  "join_mode": null,
  "mute_all": true,
  "max_members": 500,
  "member_count": 3,
  "status": "active",
  "disabled_by": null,
  "info_version": 19,
  "member_version": 19,
  "created_at": "2026-10-02T19:05:47.929Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "dismissed_at": null,
  "changed": true
}

错误

HTTP 状态码	`code`	说明
404	`not_found`	群不存在或已解散

关闭全员禁言

关闭全员禁言，普通成员恢复发言。单独禁言的成员仍然不能发言，要另行解除禁言。没有开启时调用不做任何改变，changed 为 false。

DELETE/{org_name}/{app_name}/groups/{group_id}/mute-all

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求示例

bash

curl -X DELETE "$IM_API/$ORG/$APP/groups/99582624883802112/mute-all" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，响应体与开启全员禁言相同，其中 mute_all 为 false。

错误

HTTP 状态码	`code`	说明
404	`not_found`	群不存在或已解散

封禁群

暂时停用一个群，用于处置违规的群，之后可以解封。封禁期间：

成员保留，仍然可以在客户端查看群和历史消息、退出群；
成员不能在客户端发言（返回 403 group_disabled），不能邀请他人、申请加入、审批申请或通过入群链接加入，服务端也不能添加成员；
客户端不能修改群资料和设置、群昵称，不能转让群主和设置管理员；尚未处理的入群申请和邀请暂停，解封后尚未过期的恢复有效；
服务端仍然可以修改群资料和成员的群昵称（用于清除违规内容）、转让群主、设置管理员、移出成员、禁言、管理群黑名单、解散群，也可以向群发送消息。

封禁后 status 变为 disabled，disabled_by 为 tenant，群的在线成员实时收到通知，群会话中出现群被封禁的提示消息。

被平台封禁的群

disabled_by 为 platform 的群是被平台以违反法律法规或平台规则为由封禁的。这样的群你不能解封、不能解散，也不能向它发送消息；再次调用封禁不会改变它，直接返回当前信息。

POST/{org_name}/{app_name}/groups/{group_id}/disable

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求体

请求体可以省略。

字段	类型	必填	说明
`reason`	String	否	封禁原因，最长 256 个字符，不能包含换行等控制字符。保存在群组对象的 `status_reason` 中，只在服务端接口和控制台中可见，客户端看不到

对已经由你封禁的群再次调用时，只用新的 reason 替换原来的原因（省略时清空原因），changed 为 false，info_version 不变，也不会通知成员。

请求示例

bash

curl -X POST "$IM_API/$ORG/$APP/groups/99582624883802112/disable" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "群公告含违规广告"
  }'

响应

成功返回 200 OK，响应体为封禁后的群组对象，另加 changed 字段，含义同修改群资料和设置。

json

{
  "group_id": "99582624883802112",
  "type": "private",
  "name": "三年级二班家长群",
  "avatar_url": "https://cdn.example.com/group/c302.png",
  "description": "家校沟通",
  "announcement": "家长会改到周六上午 9 点，请准时参加",
  "announcement_updated_at": "2026-10-02T19:16:49.151Z",
  "announcement_updated_by": null,
  "attributes": {
    "class_id": "C-302",
    "term": "2026-autumn"
  },
  "owner": "zhangsan",
  "member_invite": "disabled",
  "join_mode": null,
  "mute_all": false,
  "max_members": 500,
  "member_count": 3,
  "status": "disabled",
  "disabled_by": "tenant",
  "info_version": 22,
  "member_version": 21,
  "created_at": "2026-10-02T19:05:47.929Z",
  "status_reason": "群公告含违规广告",
  "max_members_setting": null,
  "created_via": "openapi",
  "dismissed_at": null,
  "changed": true
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`reason` 超过 256 个字符或包含控制字符
404	`not_found`	群不存在或已解散

解封群

解除你对群的封禁，群恢复正常：成员可以重新发言，尚未过期的入群申请和邀请恢复有效。status 变为 active，status_reason 被清空，群的在线成员实时收到通知。群没有被封禁时调用不做任何改变，changed 为 false。

POST/{org_name}/{app_name}/groups/{group_id}/enable

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求示例

bash

curl -X POST "$IM_API/$ORG/$APP/groups/99582624883802112/enable" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，响应体为解封后的群组对象，另加 changed 字段，结构与封禁群相同，其中 status 为 active，disabled_by 和 status_reason 为 null。

错误

HTTP 状态码	`code`	说明
403	`permission_denied`	群被平台封禁（`disabled_by` 为 `platform`），只能由平台解封
404	`not_found`	群不存在或已解散

解散群

解散一个群，不能恢复。解散后：

群的 status 立即变为 dismissed，任何人都不能再加入或发言；群的在线成员实时收到通知，群会话中出现“群已解散”的提示消息；
尚未处理的入群申请和邀请立即失效；
解散时的成员会收到“群聊已解散”的离线推送（App 不在前台时）；成员对这个群设置的会话免打扰随之删除；
群的全部群文件被删除（通常在 1 分钟内），之后无法再下载；群头像保留；
成员会保留约 1 小时，之后被分批移出，member_count 变为 0，群黑名单和入群申请的记录随之删除；
群的记录永久保留，仍然可以查询群信息，群 ID 不会被复用；不能再修改这个群，相关接口返回 404 not_found。

重复解散同一个群同样返回 204 No Content。

DELETE/{org_name}/{app_name}/groups/{group_id}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求体

请求体可以省略。

字段	类型	必填	说明
`reason`	String	否	解散原因，最长 256 个字符，不能包含控制字符。只记录在控制台的操作日志中，不会展示给成员

请求示例

bash

curl -X DELETE "$IM_API/$ORG/$APP/groups/99582553119260672" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "班级已毕业"
  }'

响应

成功返回 204 No Content，没有响应体。解散后查询这个群：

json

{
  "group_id": "99582553119260672",
  "type": "private",
  "name": "三年级二班家长群",
  "avatar_url": "",
  "description": "家校沟通",
  "announcement": "本周五下午家长会",
  "announcement_updated_at": "2026-10-02T19:05:30.818Z",
  "announcement_updated_by": null,
  "attributes": {
    "class_id": "C-302"
  },
  "owner": "zhangsan",
  "member_invite": "disabled",
  "join_mode": null,
  "mute_all": false,
  "max_members": 2,
  "member_count": 3,
  "status": "dismissed",
  "disabled_by": null,
  "info_version": 3,
  "member_version": 2,
  "created_at": "2026-10-02T19:05:30.818Z",
  "status_reason": null,
  "max_members_setting": 2,
  "created_via": "openapi",
  "dismissed_at": "2026-10-02T19:11:18.070Z"
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`reason` 超过 256 个字符或包含控制字符
403	`permission_denied`	群被平台封禁（`disabled_by` 为 `platform`），不能解散
404	`not_found`	群不存在

数据结构

群组对象

服务端接口返回的群组对象包含以下全部字段。客户端看到的群信息不含 status_reason、max_members_setting、created_via 和 dismissed_at。

字段	类型	说明
`group_id`	String	群 ID，由系统生成，创建后不变
`type`	String	群类型：`private` 私有群，`public` 公开群
`name`	String	群名称，没有时为空字符串
`avatar_url`	String	群头像地址，没有时为空字符串
`description`	String	群简介，没有时为空字符串
`announcement`	String	群公告，没有时为空字符串
`announcement_updated_at`	String	公告最近一次修改的时间，从未设置过公告时为 `null`
`announcement_updated_by`	String	最近一次在客户端修改公告的用户名；由服务端或控制台修改、或修改人已被删除时为 `null`
`attributes`	Object	自定义属性，字符串键值对；没有时为 `null`
`owner`	String	群主的用户名。群主的账号刚被删除、系统尚未指定新群主时短暂为 `null`
`member_invite`	String	普通成员能否邀请他人：`free`、`approval` 或 `disabled`，见群设置
`join_mode`	String	公开群的申请方式：`approval` 或 `free`；私有群为 `null`
`mute_all`	Boolean	是否开启了全员禁言
`max_members`	Number	实际生效的人数上限：群自己的上限与应用默认上限（运行策略与套餐中较小的）中较小的一个
`member_count`	Number	当前的成员人数，含群主
`status`	String	群状态：`active` 正常，`disabled` 已封禁，`dismissed` 已解散
`disabled_by`	String	封禁方：`tenant` 由你（服务端或控制台）封禁，`platform` 由平台封禁；未封禁时为 `null`
`info_version`	Number	群资料和设置的版本号，见版本号
`member_version`	Number	成员列表的版本号
`created_at`	String	创建时间
`status_reason`	String	封禁原因，可为 `null`。只在服务端接口和控制台中返回
`max_members_setting`	Number	群自己设置的人数上限，没有设置时为 `null`
`created_via`	String	创建方式：`openapi` 服务端接口，`console` 控制台，`client` 用户在客户端创建
`dismissed_at`	String	解散时间，未解散时为 `null`

json

{
  "group_id": "99582688326844416",
  "type": "public",
  "name": "摄影爱好者",
  "avatar_url": "",
  "description": "分享作品，交流器材",
  "announcement": "",
  "announcement_updated_at": null,
  "announcement_updated_by": null,
  "attributes": null,
  "owner": "lisi",
  "member_invite": "approval",
  "join_mode": "approval",
  "mute_all": false,
  "max_members": 500,
  "member_count": 5,
  "status": "active",
  "disabled_by": null,
  "info_version": 12,
  "member_version": 5,
  "created_at": "2026-10-02T19:06:03.054Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "dismissed_at": null
}

群组管理 ​

基本概念 ​

群类型 ​

成员角色 ​

加入群的方式 ​

群设置 ​

群状态 ​

版本号 ​

群头像 ​

群文件 ​

创建群 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

查询群列表 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

查询群信息 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

修改群资料和设置 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

转让群主 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

开启全员禁言 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

关闭全员禁言 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

封禁群 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

解封群 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

解散群 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

数据结构 ​

群组对象 ​

群组管理

基本概念

群类型

成员角色

加入群的方式

群设置

群状态

版本号

群头像

群文件

创建群

路径参数

请求体

请求示例

响应

错误

查询群列表

路径参数

查询参数

请求示例

响应

错误

查询群信息

路径参数

请求示例

响应

错误

修改群资料和设置

路径参数

请求体

请求示例

响应

错误

转让群主

路径参数

请求体

请求示例

响应

错误

开启全员禁言

路径参数

请求示例

响应

错误

关闭全员禁言

路径参数

请求示例

响应

错误

封禁群

路径参数

请求体

请求示例

响应

错误

解封群

路径参数

请求示例

响应

错误

解散群

路径参数

请求体

请求示例

响应

错误

数据结构

群组对象