群成員

從你的服務端管理群成員。成員角色、加入方式、版本號等概念見群組管理。

要做什麼	介面
列出成員、禁言名單	查詢群成員列表
把人直接拉進群	批次新增群成員，不需要本人確認
踢人	批次移出群成員；不讓他再進來用群黑名單
改群暱稱、成員屬性（如學號、職務）	修改群成員資料
設定或取消管理員	設定群成員角色
禁言某個成員	禁言群成員；全員禁言見開啟全員禁言

例如，把 zhaoliu 和 zhouba 加入群：

bash

curl -X POST "$IM_API/$ORG/$APP/groups/99582624883802112/members/batch" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "usernames": ["zhaoliu", "zhouba"] }'

服務端新增不需要確認：不看使用者的入群設定和群的邀請設定。想讓使用者自己決定是否加入，請讓成員在客戶端邀請他，見入群申請與邀請。
通知：成員加入、離開，角色、群暱稱、禁言變化時，群的線上成員實時收到通知；加入和離開時群會話中出現提示訊息。每次變化 member_version 加一，一次批次操作只加一。

查詢群成員列表

分頁返回群的成員，每項帶使用者的暱稱和頭像，不必再逐個查詢使用者資料。可以只列出某種角色的成員，或只列出被禁言的成員（禁言名單）。

成員按固定順序返回（與加入時間無關）。
賬號剛被刪除、還沒被移出群的成員不在列表中，所以一頁可能少於 limit 條；是否還有下一頁只看 next_cursor。
已解散的群在成員被移出之前（解散後約 1 小時內）也能查。

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

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID

查詢引數

引數	型別	必填	說明
`role`	String	否	只列出這種角色的成員：`owner`、`admin` 或 `member`
`muted`	Boolean	否	為 `true` 時只列出當前被禁言的成員；預設 `false`
`known_version`	Number	否	你儲存的成員列表版本號。請求第一頁（不帶 `cursor`）時，與當前的 `member_version` 相同則只返回版本號和 `"not_modified": true`，不返回列表
`limit`	Number	否	每頁條數，預設 100，取值 1 到 500
`cursor`	String	否	下一頁的遊標，見分頁

請求示例

bash

curl -X GET "$IM_API/$ORG/$APP/groups/99582624883802112/members?limit=2" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`member_version`	Number	當前的成員列表版本號
`not_modified`	Boolean	為 `true` 時表示成員列表與 `known_version` 相同，響應中只有 `member_version` 和這個欄位
`member_count`	Number	群的成員總數（含群主），不受篩選條件影響
`items`	Array<Object>	本頁的成員，每項為群成員物件
`next_cursor`	String	下一頁的遊標，沒有下一頁時為 `null`

json

{
  "member_version": 18,
  "not_modified": false,
  "member_count": 3,
  "items": [
    {
      "username": "zhangsan",
      "nickname": "张三",
      "avatar_url": "https://cdn.example.com/avatar/zhangsan.png",
      "role": "owner",
      "group_nickname": "",
      "attributes": null,
      "muted": false,
      "muted_until": null,
      "joined_via": "create",
      "inviter": null,
      "joined_at": "2026-10-02T19:05:47.929Z"
    },
    {
      "username": "lisi",
      "nickname": "李四",
      "avatar_url": "https://cdn.example.com/avatar/lisi.png",
      "role": "member",
      "group_nickname": "李四爸爸",
      "attributes": {
        "relation": "父亲",
        "student_no": "20230512"
      },
      "muted": false,
      "muted_until": null,
      "joined_via": "create",
      "inviter": null,
      "joined_at": "2026-10-02T19:05:47.929Z"
    }
  ],
  "next_cursor": "9H7GjqY3MBC44LVD3-8KK34h7wBQEruWHZtZcFgxf11xvlhOrIFavUbSflQL6KuoIRlUZ_8q3QsEV7gmWm-j_WxPu_kFPboldMeSWhLbkx0BKBBE"
}

帶 known_version 且成員列表沒有變化時：

json

{
  "member_version": 18,
  "not_modified": true
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`role`、`muted`、`known_version` 的取值不合法，或 `limit` 超出範圍
404	`not_found`	群不存在

批次新增群成員

把一批使用者直接加入群，一次最多 100 個。

檢查嗎	專案
不檢查	本人確認、使用者的入群設定、群的邀請設定、使用者之間的黑名單、加群前回撥
檢查	不在群黑名單中；群人數沒超過 `max_members`（群組物件）；使用者加入的群數沒超過 `max_groups_per_user`（執行策略，預設 500，且不超過套餐額度）

逐個處理：某個人失敗不影響其他人，results 逐個列出結果，見批次介面。已經是成員的算成功。
加入後：joined_via 為 server；他們在本群沒處理的入群申請和邀請自動失效。
額度：按使用者名稱個數計入應用的呼叫額度，見限流與應用狀態。

POST/{org_name}/{app_name}/groups/{group_id}/members/batch

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID

請求體

欄位	型別	必填	說明
`usernames`	Array<String>	是	要新增的使用者名稱，1 到 100 個（不區分大小寫，重複的只處理一次）

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/groups/99582624883802112/members/batch" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["zhaoliu", "zhouba", "lisi", "sunqi", "nobody"]
  }'

響應

成功返回 200 OK：

欄位	型別	說明
`changed`	Boolean	是否有人加入了群
`member_version`	Number	成員列表的版本號：有人加入時為加入後的新版本號，否則為當前的版本號
`results`	Array<Object>	每個使用者的結果，按請求中的順序排列，見批次操作結果。成功的 `status` 為 `joined`（已加入）或 `already_member`（原本就是成員）

json

{
  "changed": true,
  "member_version": 24,
  "results": [
    { "username": "zhaoliu", "status": "joined" },
    { "username": "zhouba", "status": "joined" },
    { "username": "lisi", "status": "already_member" },
    {
      "username": "sunqi",
      "code": "permission_denied",
      "message": "该用户在群黑名单中",
      "details": { "reason": "group_blacklisted" }
    },
    { "username": "nobody", "code": "not_found", "message": "用户不存在" }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`usernames` 為空或超過 100 個
403	`group_disabled`	群已被封禁，不能加人；`details.disabled_by` 為封禁方
403	`app_unavailable`	應用處於只讀狀態，不能加人
404	`not_found`	群不存在或已解散

批次移出群成員

把一批成員移出群，一次最多 100 個。

不能移出群主，要先轉讓群主。已經不是成員的算成功。
還能再進來：被移出的人之後可以再被新增或邀請。不想讓他回來，把他拉入群黑名單（拉黑會自動移出，不用先調這個介面）。
被移出的人：和線上成員一起實時收到通知，群會話中出現提示；App 不在前臺時收到“你已被移出群聊”的離線推送；他對這個群的會話免打擾刪除；不能再檢視和下載群檔案，他上傳的群檔案留在群裡。
被封禁的群也能移出成員。按使用者名稱個數計入呼叫額度。

POST/{org_name}/{app_name}/groups/{group_id}/members/batch-delete

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID

請求體

欄位	型別	必填	說明
`usernames`	Array<String>	是	要移出的使用者名稱，1 到 100 個（不區分大小寫，重複的只處理一次）

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/groups/99582624883802112/members/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["zhouba", "zhangsan", "wujiu"]
  }'

響應

成功返回 200 OK，欄位同批次新增群成員，其中 changed 表示是否有人被移出。成功的 status 為 removed（已移出）或 not_member（原本就不是成員）。

json

{
  "changed": true,
  "member_version": 25,
  "results": [
    { "username": "zhouba", "status": "removed" },
    { "username": "zhangsan", "code": "permission_denied", "message": "不能移出群主" },
    { "username": "wujiu", "status": "not_member" }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`usernames` 為空或超過 100 個
404	`not_found`	群不存在或已解散

查詢群成員

查詢一個使用者在群裡的資訊。

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

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID
`username`	String	使用者名稱

請求示例

bash

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

響應

成功返回 200 OK，響應體為群成員物件。

json

{
  "username": "wangwu",
  "nickname": "王五",
  "avatar_url": "https://cdn.example.com/avatar/wangwu.png",
  "role": "admin",
  "group_nickname": "",
  "attributes": null,
  "muted": false,
  "muted_until": null,
  "joined_via": "create",
  "inviter": null,
  "joined_at": "2026-10-02T19:05:47.929Z"
}

錯誤

HTTP 狀態碼	`code`	說明
403	`not_group_member`	這個使用者不是群成員
404	`not_found`	群不存在，或使用者不存在

修改群成員資料

修改成員在本群的群暱稱和成員屬性，只改請求中出現的欄位。兩者對群內全部成員可見，使用者自己也能在客戶端改。被封禁的群也能改，便於清除違規的群暱稱。

內容安全：群暱稱經過內容安全檢查（預設只按平臺規則，見服務端提交的內容），沒變或清空時不檢查；成員屬性不檢查。不透過時什麼都不改，返回 403 content_rejected；命中替換規則的寫入替換後的群暱稱。

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

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID
`username`	String	成員的使用者名稱

請求體

至少包含一個欄位。

欄位	型別	必填	說明
`group_nickname`	String	否	群暱稱，最長 64 個字元，不能包含換行等控制字元，首尾的空白會被去掉；傳空字串表示清除
`attributes`	Object	否	成員屬性，字串鍵值對，如學號、職務。按項合併：出現的鍵被新增或覆蓋，值為 `null` 的鍵被刪除，沒有出現的鍵保持不變；整個欄位為 `null` 時清空全部成員屬性。合併後最多 16 項，JSON 編碼後合計不超過 1 KB；鍵為 1 到 32 個字元，只能包含字母、數字和 `_`、`-`、`.`

請求示例

bash

curl -X PATCH "$IM_API/$ORG/$APP/groups/99582624883802112/members/lisi" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_nickname": "李四爸爸",
    "attributes": { "student_no": "20230512", "relation": "父亲" }
  }'

響應

成功返回 200 OK：

欄位	型別	說明
`member`	Object	修改後的群成員物件
`changed`	Boolean	這次請求是否改變了成員。與原值相同時為 `false`，`member_version` 不變，也不會通知成員
`member_version`	Number	成員列表的版本號：有變化時為變化後的新版本號，否則為當前的版本號

json

{
  "member": {
    "username": "lisi",
    "nickname": "李四",
    "avatar_url": "https://cdn.example.com/avatar/lisi.png",
    "role": "member",
    "group_nickname": "李四爸爸",
    "attributes": {
      "relation": "父亲",
      "student_no": "20230512"
    },
    "muted": false,
    "muted_until": null,
    "joined_via": "create",
    "inviter": null,
    "joined_at": "2026-10-02T19:05:47.929Z"
  },
  "changed": true,
  "member_version": 23
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	沒有要修改的欄位，或欄位不合法（如群暱稱過長、成員屬性超過上限）；請求中包含其他欄位（如 `role`，設定角色請用設定群成員角色）
403	`not_group_member`	這個使用者不是群成員
403	`app_unavailable`	應用處於只讀狀態，不能修改
403	`content_rejected`	群暱稱未透過內容安全檢查，`details.field` 為 `group_nickname`，`details.reason` 說明原因，見呼叫方看到的錯誤
404	`not_found`	群不存在或已解散，或使用者不存在

設定群成員角色

把成員設為管理員，或把管理員改回普通成員。每個群最多 20 個管理員。群主只能透過轉讓群主產生，不能用這個介面設定或改變。

管理員被改回普通成員時，他生成的入群連結隨之失效。被封禁的群也可以設定。

PUT/{org_name}/{app_name}/groups/{group_id}/members/{username}/role

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID
`username`	String	成員的使用者名稱

請求體

欄位	型別	必填	說明
`role`	String	是	`admin` 管理員，或 `member` 普通成員。與當前角色相同時不做任何改變，`changed` 為 `false`

請求示例

bash

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

響應

成功返回 200 OK，欄位同修改群成員資料。

json

{
  "member": {
    "username": "wangwu",
    "nickname": "王五",
    "avatar_url": "https://cdn.example.com/avatar/wangwu.png",
    "role": "admin",
    "group_nickname": "",
    "attributes": null,
    "muted": false,
    "muted_until": null,
    "joined_via": "create",
    "inviter": null,
    "joined_at": "2026-10-02T19:05:47.929Z"
  },
  "changed": true,
  "member_version": 7
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`role` 不是 `admin` 或 `member`；目標使用者是群主
403	`not_group_member`	這個使用者不是群成員
404	`not_found`	群不存在或已解散，或使用者不存在
409	`limit_exceeded`	`details.reason` 為 `admin_limit`：管理員已有 20 個

禁言群成員

禁止一個成員在本群發言，可以限時或永久，到期自動解除。被禁言的成員仍能看群訊息，傳送時返回 403 group_muted。

誰能被禁言：管理員也可以，而且不享有全員禁言對管理員的豁免；群主不能被禁言。
隻影響本群：要禁止他在所有會話發言，用全域性禁言。你的服務端以他的身份傳送訊息不受限制。
再次禁言：按新時長重新計算到期時間（可以延長也可以縮短）。已經永久禁言再永久禁言，或新到期時間與原來相差不超過 1 分鐘（如超時重試），算重複提交，changed 為 false。
被封禁的群也能禁言。

PUT/{org_name}/{app_name}/groups/{group_id}/members/{username}/mute

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID
`username`	String	成員的使用者名稱

請求體

請求體可以省略，省略時永久禁言。

欄位	型別	必填	說明
`duration_seconds`	Number	否	禁言時長，單位為秒，1 到 315360000（10 年）。省略或為 `null` 表示永久禁言

請求示例

bash

curl -X PUT "$IM_API/$ORG/$APP/groups/99582624883802112/members/sunqi/mute" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duration_seconds": 3600
  }'

響應

成功返回 200 OK，欄位同修改群成員資料。永久禁言時 muted 為 true、muted_until 為 null。

json

{
  "member": {
    "username": "sunqi",
    "nickname": "孙七",
    "avatar_url": "https://cdn.example.com/avatar/sunqi.png",
    "role": "member",
    "group_nickname": "",
    "attributes": null,
    "muted": true,
    "muted_until": "2026-10-02T20:07:35.934Z",
    "joined_via": "server",
    "inviter": null,
    "joined_at": "2026-10-02T19:06:42.699Z"
  },
  "changed": true,
  "member_version": 8
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`duration_seconds` 超出範圍
403	`permission_denied`	目標使用者是群主，不能禁言
403	`not_group_member`	這個使用者不是群成員
404	`not_found`	群不存在或已解散，或使用者不存在

解除群成員禁言

提前解除成員在本群的禁言。成員沒有被禁言（或禁言已到期）時不做任何改變，changed 為 false。全員禁言要另行關閉。被封禁的群也可以解除。

DELETE/{org_name}/{app_name}/groups/{group_id}/members/{username}/mute

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`group_id`	String	群 ID
`username`	String	成員的使用者名稱

請求示例

bash

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

響應

成功返回 200 OK，欄位同修改群成員資料。

json

{
  "member": {
    "username": "zhaoliu",
    "nickname": "赵六",
    "avatar_url": "https://cdn.example.com/avatar/zhaoliu.png",
    "role": "member",
    "group_nickname": "",
    "attributes": null,
    "muted": false,
    "muted_until": null,
    "joined_via": "server",
    "inviter": null,
    "joined_at": "2026-10-02T19:06:42.699Z"
  },
  "changed": true,
  "member_version": 10
}

錯誤

HTTP 狀態碼	`code`	說明
403	`not_group_member`	這個使用者不是群成員
404	`not_found`	群不存在或已解散，或使用者不存在

資料結構

群成員物件

欄位	型別	說明
`username`	String	使用者名稱
`nickname`	String	使用者資料中的暱稱，沒有時為空字串
`avatar_url`	String	使用者資料中的頭像地址，沒有時為空字串
`role`	String	角色：`owner` 群主，`admin` 管理員，`member` 普通成員
`group_nickname`	String	本群的群暱稱，沒有時為空字串
`attributes`	Object	成員屬性，字串鍵值對；沒有時為 `null`
`muted`	Boolean	當前是否被禁言（不含全員禁言）
`muted_until`	String	禁言的到期時間；永久禁言或沒有被禁言時為 `null`
`joined_via`	String	加入方式：`create`、`server`、`invite`、`apply` 或 `link`，見加入群的方式
`inviter`	String	邀請人的使用者名稱：被邀請加入時為邀請人，透過入群連結加入時為生成連結的人；其他方式或邀請人已被刪除時為 `null`
`joined_at`	String	加入群的時間

json

{
  "username": "sunqi",
  "nickname": "孙七",
  "avatar_url": "https://cdn.example.com/avatar/sunqi.png",
  "role": "member",
  "group_nickname": "",
  "attributes": null,
  "muted": false,
  "muted_until": null,
  "joined_via": "invite",
  "inviter": "lisi",
  "joined_at": "2026-10-02T19:10:46.913Z"
}

批次操作結果

建立群的 results、批次新增群成員和批次移出群成員的 results 中，每項為一個使用者的結果。成功的項只有 username 和 status；失敗的項沒有 status，帶 code 和 message，部分錯誤另有 details。

欄位	型別	說明
`username`	String	使用者名稱（小寫）
`status`	String	成功時的結果：`joined` 已加入，`already_member` 原本就是成員，`removed` 已移出，`not_member` 原本就不是成員
`code`	String	失敗時的錯誤碼，見下表
`message`	String	失敗時的錯誤說明
`details`	Object	失敗的詳細原因，只有部分錯誤帶這個欄位

`code`	`details.reason`	說明
`not_found`		使用者不存在
`permission_denied`	`group_blacklisted`	使用者在群黑名單中，不能加入
`permission_denied`		不能移出群主
`limit_exceeded`	`group_member_limit`	群人數已達上限
`limit_exceeded`	`user_group_limit`	這個使用者加入的群數已達上限

群成員 ​

查詢群成員列表 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

批次新增群成員 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

批次移出群成員 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢群成員 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

修改群成員資料 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

設定群成員角色 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

禁言群成員 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

解除群成員禁言 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

資料結構 ​

群成員物件 ​

批次操作結果 ​

群成員

查詢群成員列表

路徑引數

查詢引數

請求示例

響應

錯誤

批次新增群成員

路徑引數

請求體

請求示例

響應

錯誤

批次移出群成員

路徑引數

請求體

請求示例

響應

錯誤

查詢群成員

路徑引數

請求示例

響應

錯誤

修改群成員資料

路徑引數

請求體

請求示例

響應

錯誤

設定群成員角色

路徑引數

請求體

請求示例

響應

錯誤

禁言群成員

路徑引數

請求體

請求示例

響應

錯誤

解除群成員禁言

路徑引數

請求示例

響應

錯誤

資料結構

群成員物件

批次操作結果