聊天室成員

聊天室的成員就是此刻在聊天室裡的使用者：在客戶端進入後成為成員，離開或連線斷開 15 秒後就不再是，成員關係不儲存。進入與離開、身份、全員禁言等概念見聊天室管理。

處置直播間裡搗亂的使用者，按想要的效果選：

想要	用什麼	能留在聊天室	能發言	能再進來
不讓他說話	禁言使用者	能	不能	—
讓他離開一次	移出聊天室成員	不能	—	能，立刻
一段時間內進不來	封禁使用者（自動移出）	不能	—	到期後才能
全員禁言時讓嘉賓仍能發言	加入白名單	能	能	—

例如，封禁 troll 一小時：

bash

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/bans" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "usernames": ["troll"], "duration_seconds": 3600, "reason": "刷屏" }'

查詢線上成員、判斷某個使用者是否在聊天室裡，見查詢聊天室成員列表和查詢使用者是否在聊天室裡。

禁言、封禁與白名單

三個名單儲存在服務端，與使用者是否在聊天室裡無關：可以對此刻不在聊天室裡的使用者操作，使用者離開後再進入，名單照樣有效。

名單	效果	時長	每個聊天室的上限
禁言	不能在客戶端傳送訊息、設定屬性；仍然可以進入聊天室、接收訊息、刪除自己設定的屬性。傳送時返回 `403 chatroom_muted`，`details.reason` 為 `member`，`details.muted_until` 為到期時間	1 秒到 10 年，或永久；到期自動解除	1 萬個未到期的禁言
封禁	使用者此刻在聊天室裡的全部連線被立即移出，封禁期間不能進入，進入時返回 `403 permission_denied`，`details.reason` 為 `chatroom_banned`，`details.expires_at` 為到期時間。封禁管理員時，他同時不再是管理員	1 秒到 10 年，或永久；到期自動解除	1 萬個未到期的封禁
白名單	全員禁言時仍然可以傳送訊息、設定屬性，適合直播間的嘉賓。被單獨禁言時照樣不能發言	一直有效，直到移出白名單	500 人

三個名單互相獨立：同一個使用者可以既在白名單中又被禁言（這時不能發言）；封禁不會把他移出白名單。所有者和管理員本來就不受全員禁言限制，也能加入白名單，在他們不再是所有者或管理員後起作用。
所有者受保護：誰都不能禁言、移出或封禁所有者，你的服務端也不能（permission_denied，owner_protected）。要處置所有者，先轉讓或清空所有者。管理員可以被你的服務端禁言、移出、封禁。
和全域性禁言獨立：聊天室禁言與使用者的全域性禁言（room 場景）任意一個生效都不能在聊天室發言。你的服務端以他的身份傳送訊息不受限制。
通知：禁言、解除禁言和白名單變化實時通知線上成員，被禁言者的客戶端據此禁用輸入框；禁言到期自動解除時不發通知，客戶端按到期時間在本地恢復。被移出、被封禁的使用者收到移出通知（原因 kicked、banned，封禁另帶到期時間）。
生效時間：移出和封禁通常 1 秒內生效。

名單的批次介面

移出、禁言、解除禁言、封禁、解除封禁、加入和移出白名單都是批次介面，一次最多 100 個使用者，逐個處理，某個使用者失敗不影響其他使用者，響應中逐個列出結果，格式見批次操作結果。這些介面按使用者名稱個數計入應用的 OpenAPI 呼叫額度，見限流與應用狀態。

被封禁的聊天室也可以操作這些名單。應用被限制為只讀時，只有加入白名單返回 403 app_unavailable，其他名單操作和移出仍然可以使用。

查詢聊天室成員列表

分頁返回此刻在聊天室裡的使用者，按進入時間從早到晚排列，每項帶使用者的暱稱、頭像和在聊天室中的身份。

翻頁期間一直在聊天室裡的使用者恰好出現一次；翻頁期間離開又重新進入的使用者進入時間變了，可能在後面的頁中再出現一次，請按使用者名稱去重。賬號已被刪除的使用者不在列表中，所以一頁的條數可能少於 limit，是否還有下一頁以 next_cursor 為準。

GET/{org_name}/{app_name}/chatrooms/{room_id}/members

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

查詢引數

引數	型別	必填	說明
`limit`	Number	否	每頁條數，預設 20，取值 1 到 1000
`cursor`	String	否	下一頁的遊標，見分頁

請求示例

bash

curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/members?limit=3" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 中每項為一個成員物件，next_cursor 為下一頁的遊標，沒有下一頁時為 null。

json

{
  "items": [
    {
      "username": "zhangsan",
      "nickname": "张三",
      "avatar_url": "https://cdn.example.com/avatar/zhangsan.png",
      "role": "owner",
      "joined_at": "2026-10-04T19:20:32.763Z"
    },
    {
      "username": "lisi",
      "nickname": "李四",
      "avatar_url": "https://cdn.example.com/avatar/lisi.png",
      "role": "admin",
      "joined_at": "2026-10-04T19:20:33.019Z"
    },
    {
      "username": "wangwu",
      "nickname": "王五",
      "avatar_url": "https://cdn.example.com/avatar/wangwu.png",
      "role": "member",
      "joined_at": "2026-10-04T19:20:33.319Z"
    }
  ],
  "next_cursor": "1791141633319:100310462331092992"
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`limit` 超出範圍，或 `cursor` 無效
404	`not_found`	聊天室不存在或已解散
500	`internal`	`details.reason` 為 `dependency_unavailable`：暫時無法讀取成員，按 `Retry-After` 響應頭等待後重試

查詢使用者是否在聊天室裡

判斷一個使用者此刻是否在聊天室裡，並返回他的進入時間和在聊天室中的身份。使用者的任意一臺裝置在聊天室裡就算在其中；連線斷開不到 15 秒的仍算在其中。

GET/{org_name}/{app_name}/chatrooms/{room_id}/members/{username}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID
`username`	String	使用者名稱

請求示例

bash

curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/members/lisi" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
`in_room`	Boolean	此刻是否在聊天室裡
`joined_at`	String	這一次進入的時間；不在聊天室裡時為 `null`
`role`	String	在聊天室中的身份：`owner`、`admin` 或 `member`，不在聊天室裡時同樣返回

json

{
  "in_room": true,
  "joined_at": "2026-10-04T19:20:33.019Z",
  "role": "admin"
}

使用者不在聊天室裡時：

json

{
  "in_room": false,
  "joined_at": null,
  "role": "member"
}

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	聊天室不存在或已解散，或使用者不存在
500	`internal`	`details.reason` 為 `dependency_unavailable`：暫時無法讀取成員，按 `Retry-After` 響應頭等待後重試

移出聊天室成員

把一批使用者移出聊天室，一次最多 100 個。被移出的使用者的全部連線收到移出的通知（原因 kicked），客戶端不會自動重新進入；線上人數不超過執行策略 chatroom_member_notify_limit（預設 100）的聊天室，其他線上成員會收到他離開的通知。他設定的隨設定人離開而刪除的屬性（如麥位）隨之刪除。

移出只是讓使用者離開，他可以立刻重新進入；要讓他一段時間內進不來，請封禁，封禁時會自動移出，不必先呼叫這個介面。可以移出管理員，不能移出所有者。使用者此刻不在聊天室裡時視為成功，結果為 not_in_room。

POST/{org_name}/{app_name}/chatrooms/{room_id}/members/batch-delete

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

請求體

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

請求示例

bash

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

響應

成功返回 200 OK：

欄位	型別	說明
`changed`	Boolean	是否有人被移出
`results`	Array<Object>	每個使用者的結果，按請求中的順序排列，見批次操作結果。成功的 `result` 為 `removed`（已移出）或 `not_in_room`（原本就不在聊天室裡）

json

{
  "changed": true,
  "results": [
    { "username": "sunqi", "result": "removed" },
    { "username": "wujiu", "result": "not_in_room" },
    {
      "username": "zhangsan",
      "code": "permission_denied",
      "message": "不能处置所有者",
      "details": { "reason": "owner_protected" }
    },
    { "username": "nobody", "code": "not_found", "message": "用户不存在" }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`usernames` 為空或超過 100 個
404	`not_found`	聊天室不存在或已解散
500	`internal`	`details.reason` 為 `dependency_unavailable`：暫時無法移出，沒有使用者被移出，按 `Retry-After` 響應頭等待後重試

查詢禁言名單

分頁列出聊天室中未到期的禁言，按固定的順序返回（與禁言的時間無關）。已經到期的禁言不在列表中。

GET/{org_name}/{app_name}/chatrooms/{room_id}/mutes

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

查詢引數

引數	型別	必填	說明
`limit`	Number	否	每頁條數，預設 20，取值 1 到 100
`cursor`	String	否	下一頁的遊標，見分頁

請求示例

bash

curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/mutes" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 中每項為一個禁言名單項，next_cursor 為下一頁的遊標，沒有下一頁時為 null。

json

{
  "items": [
    {
      "username": "zhaoliu",
      "nickname": "赵六",
      "avatar_url": "https://cdn.example.com/avatar/zhaoliu.png",
      "muted_until": null,
      "reason": "",
      "created_by": null,
      "created_by_role": "server",
      "created_at": "2026-10-04T19:23:02.395Z"
    },
    {
      "username": "wujiu",
      "nickname": "吴九",
      "avatar_url": "https://cdn.example.com/avatar/wujiu.png",
      "muted_until": "2026-10-04T19:33:02.351Z",
      "reason": "刷屏",
      "created_by": null,
      "created_by_role": "server",
      "created_at": "2026-10-04T19:23:02.351Z"
    }
  ],
  "next_cursor": null
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`limit` 超出範圍，或 `cursor` 無效
404	`not_found`	聊天室不存在或已解散

禁言使用者

禁止一批使用者在這個聊天室發言，一次最多 100 個，可以指定時長，也可以永久禁言，到期自動解除。禁言的效果見禁言、封禁與白名單。聊天室的線上成員會實時收到通知，其中帶每個人的到期時間。

對已被禁言的使用者再次禁言時，按新的時長重新計算到期時間（可以延長，也可以縮短）。以下情況視為重複提交，不做任何改變，結果為 unchanged：已經永久禁言時再次永久禁言；限時禁言的新到期時間與原來的相差不超過 1 分鐘（如超時重試）。

POST/{org_name}/{app_name}/chatrooms/{room_id}/mutes

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

請求體

欄位	型別	必填	說明
`usernames`	Array<String>	是	要禁言的使用者名稱，1 到 100 個（不區分大小寫，重複的只處理一次）
`duration_seconds`	Number	否	禁言時長，單位為秒，1 到 315360000（10 年）。省略或為 `null` 表示永久禁言
`reason`	String	否	禁言原因，最長 256 個字元，不能包含控制字元。顯示在禁言名單中，聊天室的所有者和管理員在客戶端檢視禁言名單時也能看到

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/mutes" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["wujiu", "sunqi", "zhangsan", "nobody"],
    "duration_seconds": 600,
    "reason": "刷屏"
  }'

響應

成功返回 200 OK，欄位同移出聊天室成員，其中 changed 表示是否有人被禁言或修改了禁言時長。成功的 result 為 muted（已禁言）或 unchanged（重複提交，沒有變化）。

json

{
  "changed": true,
  "results": [
    { "username": "wujiu", "result": "muted" },
    { "username": "sunqi", "result": "muted" },
    {
      "username": "zhangsan",
      "code": "permission_denied",
      "message": "不能处置所有者",
      "details": { "reason": "owner_protected" }
    },
    { "username": "nobody", "code": "not_found", "message": "用户不存在" }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`usernames` 為空或超過 100 個；`duration_seconds` 超出範圍；`reason` 超過 256 個字元或包含控制字元
404	`not_found`	聊天室不存在或已解散

解除禁言

提前解除一批使用者在這個聊天室的禁言，一次最多 100 個。聊天室的線上成員會實時收到通知。使用者沒有被禁言（或禁言已到期）時視為成功，結果為 unchanged。全員禁言要另行關閉。

POST/{org_name}/{app_name}/chatrooms/{room_id}/mutes/batch-delete

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

請求體

欄位	型別	必填	說明
`usernames`	Array<String>	是	要解除禁言的使用者名稱，1 到 100 個

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/mutes/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["sunqi", "zhouba", "nobody"]
  }'

響應

成功返回 200 OK，欄位同移出聊天室成員，其中 changed 表示是否有人被解除禁言。成功的 result 為 unmuted（已解除）或 unchanged（原本就沒有被禁言）。

json

{
  "changed": true,
  "results": [
    { "username": "sunqi", "result": "unmuted" },
    { "username": "zhouba", "result": "unchanged" },
    { "username": "nobody", "code": "not_found", "message": "用户不存在" }
  ]
}

錯誤

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

查詢封禁名單

分頁列出聊天室中未到期的封禁，按固定的順序返回（與封禁的時間無關）。已經到期的封禁不在列表中。

GET/{org_name}/{app_name}/chatrooms/{room_id}/bans

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

查詢引數

引數	型別	必填	說明
`limit`	Number	否	每頁條數，預設 20，取值 1 到 100
`cursor`	String	否	下一頁的遊標，見分頁

請求示例

bash

curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/bans" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 中每項為一個封禁名單項，next_cursor 為下一頁的遊標，沒有下一頁時為 null。

json

{
  "items": [
    {
      "username": "zhouba",
      "nickname": "周八",
      "avatar_url": "https://cdn.example.com/avatar/zhouba.png",
      "expires_at": "2026-10-04T20:23:28.148Z",
      "reason": "发布广告",
      "created_by": null,
      "created_by_role": "server",
      "created_at": "2026-10-04T19:23:28.148Z"
    },
    {
      "username": "wujiu",
      "nickname": "吴九",
      "avatar_url": "https://cdn.example.com/avatar/wujiu.png",
      "expires_at": "2026-10-04T20:23:28.148Z",
      "reason": "发布广告",
      "created_by": null,
      "created_by_role": "server",
      "created_at": "2026-10-04T19:23:28.148Z"
    }
  ],
  "next_cursor": null
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`limit` 超出範圍，或 `cursor` 無效
404	`not_found`	聊天室不存在或已解散

封禁使用者

把一批使用者加入聊天室的封禁名單，一次最多 100 個，可以指定時長，也可以永久封禁，到期自動解除。封禁後：

使用者此刻在聊天室裡的全部連線被立即移出，收到移出的通知（原因 banned，帶到期時間），封禁期間不能進入；線上人數不超過執行策略 chatroom_member_notify_limit（預設 100）的聊天室，其他線上成員會收到他離開的通知；
被封禁的管理員同時不再是管理員，info_version 加一，線上成員收到管理員變化的通知；
他設定的隨設定人離開而刪除的屬性隨之刪除。

對已在封禁中的使用者再次封禁不修改原來的記錄（包括時長和原因），結果為 unchanged；要修改時長，請先解除封禁再封禁。

POST/{org_name}/{app_name}/chatrooms/{room_id}/bans

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

請求體

欄位	型別	必填	說明
`usernames`	Array<String>	是	要封禁的使用者名稱，1 到 100 個（不區分大小寫，重複的只處理一次）
`duration_seconds`	Number	否	封禁時長，單位為秒，1 到 315360000（10 年）。省略或為 `null` 表示永久封禁
`reason`	String	否	封禁原因，最長 256 個字元，不能包含控制字元。顯示在封禁名單中；被封禁的使用者進入時收到的錯誤不帶原因

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/bans" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["zhouba", "wujiu", "zhangsan"],
    "duration_seconds": 3600,
    "reason": "发布广告"
  }'

響應

成功返回 200 OK，欄位同移出聊天室成員，其中 changed 表示是否有人被封禁。成功的 result 為 banned（已封禁）或 unchanged（原本就在封禁中）。

json

{
  "changed": true,
  "results": [
    { "username": "zhouba", "result": "banned" },
    { "username": "wujiu", "result": "banned" },
    {
      "username": "zhangsan",
      "code": "permission_denied",
      "message": "不能处置所有者",
      "details": { "reason": "owner_protected" }
    }
  ]
}

被封禁的使用者在封禁期間進入聊天室時，客戶端收到的錯誤：

json

{
  "code": "permission_denied",
  "message": "你已被该聊天室封禁",
  "details": { "reason": "chatroom_banned", "expires_at": "2026-10-04T20:23:28.148Z" },
  "request_id": "DTEVSNARBKXWTGBVZF3IA37RV3"
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`usernames` 為空或超過 100 個；`duration_seconds` 超出範圍；`reason` 超過 256 個字元或包含控制字元
404	`not_found`	聊天室不存在或已解散

解除封禁

提前解除一批使用者在這個聊天室的封禁，一次最多 100 個，解除後他們可以重新進入。這個操作不會通知使用者。使用者沒有被封禁（或封禁已到期）時視為成功，結果為 unchanged。

POST/{org_name}/{app_name}/chatrooms/{room_id}/bans/batch-delete

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

請求體

欄位	型別	必填	說明
`usernames`	Array<String>	是	要解除封禁的使用者名稱，1 到 100 個

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/bans/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["wujiu", "sunqi"]
  }'

響應

成功返回 200 OK，欄位同移出聊天室成員，其中 changed 表示是否有人被解除封禁。成功的 result 為 unbanned（已解除）或 unchanged（原本就沒有被封禁）。

json

{
  "changed": true,
  "results": [
    { "username": "wujiu", "result": "unbanned" },
    { "username": "sunqi", "result": "unchanged" }
  ]
}

錯誤

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

查詢白名單

分頁列出聊天室的白名單，按固定的順序返回（與加入的時間無關）。

GET/{org_name}/{app_name}/chatrooms/{room_id}/allowlist

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

查詢引數

引數	型別	必填	說明
`limit`	Number	否	每頁條數，預設 20，取值 1 到 100
`cursor`	String	否	下一頁的遊標，見分頁

請求示例

bash

curl -X GET "$IM_API/$ORG/$APP/chatrooms/100310941534519296/allowlist" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，items 中每項為一個白名單項，next_cursor 為下一頁的遊標，沒有下一頁時為 null。

json

{
  "items": [
    {
      "username": "lisi",
      "nickname": "李四",
      "avatar_url": "https://cdn.example.com/avatar/lisi.png",
      "created_by": null,
      "created_at": "2026-10-04T19:22:36.168Z"
    },
    {
      "username": "wujiu",
      "nickname": "吴九",
      "avatar_url": "https://cdn.example.com/avatar/wujiu.png",
      "created_by": null,
      "created_at": "2026-10-04T19:22:36.168Z"
    },
    {
      "username": "zhengshi",
      "nickname": "郑十",
      "avatar_url": "https://cdn.example.com/avatar/zhengshi.png",
      "created_by": null,
      "created_at": "2026-10-04T19:22:36.168Z"
    }
  ],
  "next_cursor": null
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`limit` 超出範圍，或 `cursor` 無效
404	`not_found`	聊天室不存在或已解散

加入白名單

把一批使用者加入聊天室的白名單，一次最多 100 個，每個聊天室最多 500 人。白名單的效果見禁言、封禁與白名單。聊天室的線上成員會實時收到通知。已經在白名單中的使用者視為成功，結果為 unchanged。應用處於只讀狀態時不能加入白名單。

POST/{org_name}/{app_name}/chatrooms/{room_id}/allowlist

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

請求體

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

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/allowlist" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["wujiu", "zhengshi", "lisi", "nobody"]
  }'

響應

成功返回 200 OK，欄位同移出聊天室成員，其中 changed 表示是否有人加入了白名單。成功的 result 為 added（已加入）或 unchanged（原本就在白名單中）。

json

{
  "changed": true,
  "results": [
    { "username": "wujiu", "result": "added" },
    { "username": "zhengshi", "result": "added" },
    { "username": "lisi", "result": "added" },
    { "username": "nobody", "code": "not_found", "message": "用户不存在" }
  ]
}

錯誤

HTTP 狀態碼	`code`	說明
400	`invalid_argument`	`usernames` 為空或超過 100 個
403	`app_unavailable`	應用處於只讀狀態，不能加入白名單
404	`not_found`	聊天室不存在或已解散

移出白名單

把一批使用者移出聊天室的白名單，一次最多 100 個。聊天室的線上成員會實時收到通知。不在白名單中的使用者視為成功，結果為 unchanged。

POST/{org_name}/{app_name}/chatrooms/{room_id}/allowlist/batch-delete

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
`room_id`	String	聊天室 ID

請求體

欄位	型別	必填	說明
`usernames`	Array<String>	是	要移出白名單的使用者名稱，1 到 100 個

請求示例

bash

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/allowlist/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["zhengshi", "zhouba"]
  }'

響應

成功返回 200 OK，欄位同移出聊天室成員，其中 changed 表示是否有人被移出白名單。成功的 result 為 removed（已移出）或 unchanged（原本就不在白名單中）。

json

{
  "changed": true,
  "results": [
    { "username": "zhengshi", "result": "removed" },
    { "username": "zhouba", "result": "unchanged" }
  ]
}

錯誤

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

資料結構

成員物件

欄位	型別	說明
`username`	String	使用者名稱
`nickname`	String	使用者資料中的暱稱，沒有時為空字串
`avatar_url`	String	使用者資料中的頭像地址，沒有時為空字串
`role`	String	在聊天室中的身份：`owner` 所有者，`admin` 管理員，`member` 普通使用者
`joined_at`	String	這一次進入聊天室的時間

json

{
  "username": "lisi",
  "nickname": "李四",
  "avatar_url": "https://cdn.example.com/avatar/lisi.png",
  "role": "admin",
  "joined_at": "2026-10-04T19:20:33.019Z"
}

禁言名單項

欄位	型別	說明
`username`	String	被禁言的使用者名稱
`nickname`	String	使用者資料中的暱稱，沒有時為空字串
`avatar_url`	String	使用者資料中的頭像地址，沒有時為空字串
`muted_until`	String	禁言的到期時間；永久禁言時為 `null`
`reason`	String	禁言原因，沒有時為空字串
`created_by`	String	在客戶端設定這條禁言的所有者或管理員的使用者名稱；由你的服務端或控制檯設定時為 `null`
`created_by_role`	String	設定人的身份：`owner` 所有者，`admin` 管理員，`server` 服務端或控制檯。在客戶端，管理員只能解除 `admin` 設定的禁言
`created_at`	String	這條禁言記錄的建立時間，修改禁言時長時不變

封禁名單項

欄位與禁言名單項相同，只是 muted_until 換為 expires_at：

欄位	型別	說明
`username`	String	被封禁的使用者名稱
`nickname`	String	使用者資料中的暱稱，沒有時為空字串
`avatar_url`	String	使用者資料中的頭像地址，沒有時為空字串
`expires_at`	String	封禁的到期時間；永久封禁時為 `null`
`reason`	String	封禁原因，沒有時為空字串
`created_by`	String	在客戶端設定這條封禁的所有者或管理員的使用者名稱；由你的服務端或控制檯設定時為 `null`
`created_by_role`	String	設定人的身份：`owner`、`admin` 或 `server`
`created_at`	String	封禁的時間

白名單項

欄位	型別	說明
`username`	String	使用者名稱
`nickname`	String	使用者資料中的暱稱，沒有時為空字串
`avatar_url`	String	使用者資料中的頭像地址，沒有時為空字串
`created_by`	String	在客戶端把他加入白名單的所有者或管理員的使用者名稱；由你的服務端或控制檯加入時為 `null`
`created_at`	String	加入白名單的時間

批次操作結果

移出、禁言、解除禁言、封禁、解除封禁、加入和移出白名單的 results 中，每項為一個使用者的結果。成功的項只有 username 和 result；失敗的項沒有 result，帶 code 和 message，部分錯誤另有 details。

欄位	型別	說明
`username`	String	使用者名稱（小寫）
`result`	String	成功時的結果，取值見各介面：`removed`、`not_in_room`、`muted`、`unmuted`、`banned`、`unbanned`、`added`、`unchanged`
`code`	String	失敗時的錯誤碼，見下表
`message`	String	失敗時的錯誤說明
`details`	Object	失敗的詳細原因，只有部分錯誤帶這個欄位

`code`	`details.reason`	說明
`not_found`		使用者不存在
`permission_denied`	`owner_protected`	目標使用者是所有者，不能禁言、移出或封禁
`limit_exceeded`	`mute_limit`	禁言名單已滿（1 萬個未到期的禁言）
`limit_exceeded`	`ban_limit`	封禁名單已滿（1 萬個未到期的封禁）
`limit_exceeded`	`allowlist_limit`	白名單已滿（500 人）

聊天室成員 ​

禁言、封禁與白名單 ​

名單的批次介面 ​

查詢聊天室成員列表 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢使用者是否在聊天室裡 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

移出聊天室成員 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢禁言名單 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

禁言使用者 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

解除禁言 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢封禁名單 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

封禁使用者 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

解除封禁 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢白名單 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

加入白名單 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

移出白名單 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

資料結構 ​

成員物件 ​

禁言名單項 ​

封禁名單項 ​

白名單項 ​

批次操作結果 ​

聊天室成員

禁言、封禁與白名單

名單的批次介面

查詢聊天室成員列表

路徑引數

查詢引數

請求示例

響應

錯誤

查詢使用者是否在聊天室裡

路徑引數

請求示例

響應

錯誤

移出聊天室成員

路徑引數

請求體

請求示例

響應

錯誤

查詢禁言名單

路徑引數

查詢引數

請求示例

響應

錯誤

禁言使用者

路徑引數

請求體

請求示例

響應

錯誤

解除禁言

路徑引數

請求體

請求示例

響應

錯誤

查詢封禁名單

路徑引數

查詢引數

請求示例

響應

錯誤

封禁使用者

路徑引數

請求體

請求示例

響應

錯誤

解除封禁

路徑引數

請求體

請求示例

響應

錯誤

查詢白名單

路徑引數

查詢引數

請求示例

響應

錯誤

加入白名單

路徑引數

請求體

請求示例

響應

錯誤

移出白名單

路徑引數

請求體

請求示例

響應

錯誤

資料結構

成員物件

禁言名單項

封禁名單項

白名單項

批次操作結果