群組管理

從你的服務端建群和管理群。群有固定的成員，適合班級群、專案群、興趣群。你可以按業務關係建群，指定群主和初始成員，成員直接加入、不需要對方同意；也可以查詢和修改應用內的任何群，封禁或解散違規的群。

例如，為一個班級建家長群，zhangsan 是群主：

bash

curl -X POST "$IM_API/$ORG/$APP/groups" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "owner": "zhangsan", "name": "三年级二班家长群", "members": ["lisi", "wangwu"], "attributes": { "class_id": "C-302" } }'

響應中的 group_id 就是群聊的會話 ID，可以直接用來傳送訊息。

要做什麼	見
建群、查群、改群資料	本頁：建立群、查詢群列表、修改群資料和設定
轉讓群主、全員禁言、封禁、解散	本頁：轉讓群主、開啟全員禁言、封禁群、解散群
加人、踢人、設管理員、禁言成員、改群暱稱	群成員
不讓某人再進群	群黑名單
使用者在客戶端申請入群、邀請他人	入群申請與邀請
查使用者加入了哪些群、使用者的入群設定	使用者的群

服務端不受群內角色的限制

用 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 上傳圖片（建群前就能傳），得到一個任何人都能訪問的公開地址（長邊縮放到不超過 640 畫素），在建立群或修改群資料時填進 avatar_url。頭像檔案按“是否正在被群使用”保留：

情況	檔案
上傳後 24 小時內沒有群用上	刪除
被替換（改成其他地址或清空）	7 天后刪除
多個群用了同一個檔案	只算第一個用上它的群在使用
群解散	保留，已解散的群仍顯示原來的名稱和頭像

用你自己的地址：服務端介面寫入的 avatar_url 只檢查格式。但成員在客戶端建群或改群頭像時，如果應用在執行策略中開啟了 media_url_only，只能用本應用的頭像地址或 media_allowed_hosts 中主機的 https 地址，否則返回 400 invalid_argument（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 分鐘內），之後無法下載。

建立群

建立一個群，指定群主和初始成員。

直接加入：群主和初始成員不需要確認，不看使用者的入群設定，也不呼叫加群前回撥（它只對客戶端的建群、邀請、申請、入群連結呼叫，見內容檢查與加群前回撥）。
個別成員失敗不影響建群：如使用者不存在、在群黑名單中、加入的群數已滿，響應的 results 逐個列出結果。
通知：群主和初始成員的線上裝置實時收到通知，群會話中出現建群和成員加入的提示。
額度：按初始成員人數（至少 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 小時後分批移出，`member_count` 變為 0，群黑名單和申請記錄隨之刪除
群檔案	全部刪除（通常 1 分鐘內），無法再下載；群頭像保留
群的記錄	永久保留，仍可查詢群資訊，群 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
}

群組管理 ​

基本概念 ​

群型別 ​

成員角色 ​

加入群的方式 ​

群設定 ​

群狀態 ​

版本號 ​

群頭像 ​

群檔案 ​

建立群 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢群列表 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢群資訊 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

修改群資料和設定 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

轉讓群主 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

開啟全員禁言 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

關閉全員禁言 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

封禁群 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

解封群 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

解散群 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

資料結構 ​

群組物件 ​

群組管理

基本概念

群型別

成員角色

加入群的方式

群設定

群狀態

版本號

群頭像

群檔案

建立群

路徑引數

請求體

請求示例

響應

錯誤

查詢群列表

路徑引數

查詢引數

請求示例

響應

錯誤

查詢群資訊

路徑引數

請求示例

響應

錯誤

修改群資料和設定

路徑引數

請求體

請求示例

響應

錯誤

轉讓群主

路徑引數

請求體

請求示例

響應

錯誤

開啟全員禁言

路徑引數

請求示例

響應

錯誤

關閉全員禁言

路徑引數

請求示例

響應

錯誤

封禁群

路徑引數

請求體

請求示例

響應

錯誤

解封群

路徑引數

請求示例

響應

錯誤

解散群

路徑引數

請求體

請求示例

響應

錯誤

資料結構

群組物件