聊天室管理

聊天室適合直播間、語聊房、大型活動的互動區：沒有固定成員，不儲存離線訊息，一個聊天室可以有幾十萬人。和群組的區別見聊天室與群組的區別。

典型的直播間流程：

1. 直播開始時，你的服務端建立聊天室，把 room_id 和直播間關聯起來；
2. 使用者在客戶端開啟直播間時用客戶端 SDK 進入，離開頁面時離開；
3. 直播中，你的服務端傳送系統訊息、處置違規使用者；
4. 直播結束時，你的服務端解散聊天室。

例如，為直播間 L-8812 建立聊天室，主播 zhangsan 是所有者：

curl -X POST "$IM_API/$ORG/$APP/chatrooms" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "周五晚间直播", "owner": "zhangsan", "attributes": { "live_id": "L-8812" } }'

要做什麼	見
建立、查詢、修改、解散聊天室，查線上人數	本頁
全員禁言、設管理員、語聊房的麥位等屬性、封禁聊天室	本頁：開啟全員禁言、設定管理員、聊天室屬性、封禁聊天室
查線上成員，移出、禁言、封禁使用者，白名單	聊天室成員
發系統訊息、查最近的訊息、撤回	聊天室訊息

服務端不受聊天室內身份的限制

用 App Token 呼叫時，你以應用管理者的身份操作，可以執行全部管理操作，不受所有者、管理員等身份的限制。只有一條規則對服務端同樣有效：不能禁言、移出或封禁所有者，要處置所有者，請先轉讓或清空所有者。

建立聊天室不是冪等的

建立請求超時後重試，可能建立出兩個聊天室。請以返回的 room_id 為準儲存對應關係；重試前可以按所有者或名稱字首查詢聊天室列表，確認上次沒有建立成功，多建立的解散即可。

聊天室不存在時，介面返回 404 not_found。已解散的聊天室在解散後 30 天內仍可以查詢，其他介面返回 404 not_found，details.reason 為 chatroom_dismissed，你可以據此區分“已解散”和“不存在”：

{
  "error": {
    "code": "not_found",
    "message": "聊天室已解散",
    "details": { "reason": "chatroom_dismissed" },
    "request_id": "BTIXR6TUFAL7HHCQWG6UXBTJEN"
  }
}

應用只讀時（見限流與應用狀態），建立聊天室、修改資料、設定屬性、加入白名單和傳送訊息返回 403 app_unavailable；解散、封禁和解封、轉讓所有者、全員禁言、設定管理員、移出、禁言和封禁使用者、移出白名單、刪除屬性、撤回訊息這些處置操作照常可用，使用者也仍能進入、離開和檢視。

基本概念

聊天室與群組的區別

	群組	聊天室
成員	固定成員，加入後一直是成員，離線也不例外	此刻在聊天室裡的使用者，隨長連線進入和離開，不儲存成員關係
人數	預設 500，最多 5000	預設 10 萬，最多 50 萬
訊息	儲存，離線後補齊，計未讀，有離線推送	不儲存，只推給此刻在聊天室裡的連線；剛進入的使用者只能檢視最近的幾十條
下發	每條訊息都送達	訊息過多時合併、限速，按優先順序丟棄
誰能加入	由服務端新增，或經邀請、申請加入	應用內的使用者知道聊天室 ID 就可以進入，除非被封禁
適合	班級群、專案群、興趣群	直播間、語聊房、活動互動區

雖然成員不儲存，聊天室的管理資料是持久的：所有者、管理員、禁言、封禁、白名單、公告和屬性都儲存在服務端，與使用者是否在聊天室裡無關。例如被禁言的使用者離開後再進入，仍在禁言中；管理員離開後再進入，仍是管理員。

聊天室訊息不進入使用者的會話，不計未讀數，不發離線推送，也不出現在訊息匯出中。

進入與離開

使用者在客戶端登入後，透過長連線進入聊天室（由客戶端 SDK 完成），進入後這條連線開始收到聊天室的訊息和通知。服務端沒有把使用者“拉進”聊天室的介面；你可以查詢某個使用者是否在聊天室裡，或移出使用者。

進入的條件：

• 聊天室存在且正常（沒有被封禁或解散）；
• 使用者沒有被這個聊天室封禁；
• 聊天室沒有滿員（所有者和管理員不受人數上限限制）；
• 同一條長連線最多同時在 10 個聊天室中。

進入時可以帶一段最長 512 位元組的 ext（如“VIP3”），出現在成員進入的通知中。

• 多臺裝置：一個使用者可以用多臺裝置同時進入，任意一臺在裡面他就在聊天室裡；線上人數和成員列表按使用者算，不按裝置。
• 離開：主動離開立即生效；連線斷開（斷網、App 被關閉）15 秒後才算離開，所以網路切換時 15 秒內重連的不會先離開再進入。所有者和管理員離開後仍保留身份。
• 進入的頻率：每條連線每分鐘最多進入 10 次；每個聊天室每秒最多進入 2000 人。超出時客戶端收到限流錯誤，隨機等 1 到 3 秒重試，所以直播開始時的大量進入會分散到十幾秒內完成。

被移出時，使用者的連線收到移出通知和原因，客戶端不應自動重新進入：

原因	什麼時候
kicked	被移出
banned	被封禁
disabled	聊天室被封禁
dismissed	聊天室被解散

線上人數不超過執行策略 chatroom_member_notify_limit（預設 100）的聊天室，成員進入和離開時其他線上成員會收到通知；人數更多的聊天室不推送進出通知，需要顯示“某某進入直播間”時，請以低優先順序的自定義訊息自行控制頻率。

身份

身份	role	說明
所有者	owner	每個聊天室最多一個，也可以沒有（由你的服務端管理）。在客戶端可以執行全部管理操作，包括修改人數上限、設定管理員、轉讓所有者和解散聊天室。沒有人能禁言、移出或封禁所有者
管理員	admin	每個聊天室最多 99 個，由所有者或服務端設定。在客戶端可以修改名稱、簡介、封面和公告，開啟全員禁言，禁言、移出、封禁普通使用者，管理白名單，傳送高優先順序的訊息，撤回普通使用者的訊息
普通使用者	member	其他使用者。可以進入、傳送普通和低優先順序的訊息、檢視成員和最近的訊息，在執行策略 recall_window_seconds（預設 120 秒）內撤回自己的訊息

• 身份與是否在聊天室裡無關：所有者和管理員不在聊天室裡時，仍然是所有者和管理員。
• 在客戶端，管理員不能處置其他管理員；解除禁言和封禁時，管理員只能解除管理員設定的，所有者和你的服務端設定的只有所有者和服務端能解除。
• 以上是使用者在客戶端中的許可權，服務端介面不受這些限制。
• 使用者被刪除後，他在各聊天室的管理員身份、禁言、封禁和白名單記錄隨之清除；他是所有者的，所有者被清空，不會自動轉給別人。

線上人數

聊天室資訊中的 member_count 是此刻在聊天室裡的使用者數，同一個使用者多臺裝置只計一次，包括連線斷開不到 15 秒的使用者。它最多快取 5 秒，是近似值，適合“12.3 萬人線上”這樣的展示。已封禁、已解散的聊天室為 0。需要同時顯示多個聊天室的人數時，使用批次查詢線上人數。

訊息的優先順序與下發

每條聊天室訊息都有一個優先順序，決定它在訊息過多時是否會被限流或丟棄：

優先順序	priority	用途	誰可以傳送
高	high	系統通知、管理員公告、禮物結算等不能丟的訊息	所有者、管理員，以及你的服務端
普通	normal	普通聊天，預設的優先順序	所有人
低	low	點贊、彈幕特效、進場特效等丟了無妨的高頻訊息	所有人

傳送時的限流：

額度	計入	超出時
每個聊天室每秒 chatroom_msg_per_second 條（執行策略，預設 40）	普通和低優先順序	普通的返回 429 rate_limited；低優先順序的被靜默丟棄（傳送仍算成功，響應中 dropped 為 true）
每個聊天室每秒 20 條	高優先順序	429 rate_limited
應用全部聊天室合計每秒 chatroom_msg_per_sec_limit 條（配額，預設 2000）	三種優先順序都計入	429 rate_limited

下發時：

• 合併與限速：熱鬧的聊天室中，訊息每 200 毫秒合併成一批推給客戶端。每條連線從一個聊天室每秒最多收到 50 條、128 KB 普通和低優先順序的內容，超出時先丟棄低優先順序的，再丟棄普通的，等待超過 1 秒還沒下發的也會丟棄；高優先順序的內容先於其他內容下發，正常情況下不會被丟棄。連線的網路很差、積壓過多時，這條連線只收到高優先順序的內容。客戶端會收到被丟棄的條數，可以顯示“訊息過多，已省略部分”。
• 不保證送達和順序：聊天室訊息只推給此刻在其中的連線，網路異常時可能丟失，不同使用者發出的訊息到達的先後可能略有不同。需要可靠送達的內容（如禮物結算）請用高優先順序傳送，並由你的業務另行保證。

聊天室自身的通知中，資料、禁言、白名單、屬性的變化和訊息撤回為高優先順序，成員進出為低優先順序。

最近的訊息

普通和高優先順序的訊息會儲存最近的 chatroom_history_size 條（執行策略，預設 50 條，可設 0 到 200，0 表示不儲存），只保留 24 小時，低優先順序的訊息不儲存。使用者剛進入聊天室時可以拉取它們，顯示最近的聊天；你的服務端可以查詢最近的訊息。

最近的訊息不是歷史訊息：不能向前翻頁，也不保證完整。聊天室被封禁或解散時，最近的訊息被清空。需要留存聊天室訊息的，請使用事件回撥中的聊天室訊息抄送。

資料與公告

欄位	說明
name	名稱，1 到 128 個字元，必填，不能包含控制字元，首尾的空白會被去掉
description	簡介，最長 512 個字元，可以換行
announcement	公告，最長 2048 個字元，可以換行。每次修改公告都會記錄修改時間 announcement_updated_at 和在客戶端修改它的使用者 announcement_updated_by，客戶端可以據此提示“公告已更新”
avatar_url	封面地址，見封面
max_members	人數上限，見下文
listed	是否出現在客戶端的聊天室列表中，預設 true。為 false 的聊天室只能按 ID 進入

人數上限：實際生效的上限（聊天室物件的 max_members）取聊天室自己的上限（1 到 500000，max_members_setting）與應用執行策略 max_chatroom_members（預設 100000，可設 10 到 500000）中較小的一個；聊天室沒有設定自己的上限時，跟隨執行策略。調低到當前人數以下時不會移出使用者，只是新使用者不能再進入。所有者和管理員不受人數上限的限制。

資料變化（包括全員禁言、所有者、管理員的變化）後，線上成員會實時收到通知，其中只帶變化的欄位。資料對應用內所有使用者可見；封禁原因 status_reason 只在服務端介面和控制檯中返回，客戶端看不到。

建立和修改聊天室時，名稱、簡介和公告會經過內容安全檢查（你的服務端提交的預設只按平臺的規則檢查），只檢查本次真正修改的欄位：不透過的不寫入，返回 403 content_rejected，details.field 為不透過的欄位；命中替換規則的，寫入替換後的文字。

封面

封面 avatar_url 是 http 或 https 地址，最長 512 個字元，可以放在本服務，也可以用你自己的圖片地址。

用本服務的封面：以用途 chatroom_avatar、型別 image 上傳圖片（建立前就能傳），得到任何人都能訪問的公開地址（長邊縮放到不超過 640 畫素），在建立或修改資料時填進 avatar_url。

情況	封面檔案
上傳後 24 小時內沒有聊天室用上	刪除
被替換（改成其他地址或清空）	7 天后刪除
聊天室解散	7 天后刪除

用你自己的地址：服務端介面寫入的 avatar_url 只檢查格式，不會訪問。但使用者在客戶端建立聊天室或改封面時，如果應用在執行策略中開啟了 media_url_only，只能用本應用的封面地址或 media_allowed_hosts 中主機的 https 地址，否則返回 400 invalid_argument（url_not_allowed）。

聊天室屬性

屬性是聊天室的自定義鍵值對，全體成員可見，常用於儲存語聊房的麥位（如 seat_1 為 zhangsan）、直播間的玩法狀態、業務系統中的直播間 ID。每次變化都會實時通知線上成員，並讓 attributes_version 加一。

• 格式：每個聊天室最多 100 個鍵。鍵為 1 到 128 個字元，只能包含字母、數字和 _、-、.、:；值為字串，最長 4096 位元組，不能包含換行、回車、製表符以外的控制字元；全部鍵和值合計不超過 16 KB。一次最多設定或刪除 20 個鍵，一次設定的鍵和值合計不超過 16 KB。
• 誰能修改：使用者在聊天室裡時可以在客戶端設定和刪除屬性，但只能修改沒人設定過或自己設定的鍵；所有者和管理員可以覆蓋和刪除別人（包括你的服務端）設定的鍵。被禁言的使用者，以及全員禁言時不在白名單中的普通使用者，不能設定屬性。你的服務端可以設定和刪除任何鍵。
• 隨設定人離開而刪除：使用者在客戶端設定屬性時可以標記 auto_delete，這些鍵在他離開聊天室時自動刪除，麥位不會因為使用者掉線而一直被佔著。連線斷開 15 秒後才算離開，網路切換不會讓麥位丟失。服務端設定的屬性不能標記 auto_delete。
• 內容檢查：屬性的值不在設定前稽核，而是在設定之後經過內容安全檢查，違規的屬性會被刪除。
• 頻率：每個聊天室每秒最多 20 次屬性寫入（客戶端和服務端合計），超出返回 429 rate_limited，details.reason 為 room_attribute_rate。需要每秒變化多次的狀態（如實時點贊數）不適合放在屬性中，請用低優先順序的自定義訊息。

狀態

status	說明
active	正常
disabled	已封禁：線上使用者全部被移出，不能進入和傳送訊息，管理資料保留，見封禁聊天室
dismissed	已解散，不能恢復，見解散聊天室

版本號

聊天室帶有兩個版本號，每次變化加一：

• info_version：資料和設定的版本號。修改資料、開啟或關閉全員禁言、轉讓所有者、設定和取消管理員、封禁和解封都會讓它加一。修改資料時可以在請求中帶上讀取到的 info_version（欄位名為 version），防止覆蓋別人同時做的修改，規則見併發修改。
• attributes_version：屬性的版本號，屬性每變化一次加一。

建立聊天室

建立一個聊天室，可以指定所有者，也可以沒有所有者，由你的服務端管理。可以同時設定初始屬性，如業務系統中的直播間 ID。建立後使用者就可以進入，聊天室對應用內的所有使用者開放。

應用中未解散的聊天室（含已封禁的）數量有上限，由平臺為應用設定的配額（預設 1 萬個）和應用的套餐決定，取兩者中較小的一個；解散後不再計入。

POST/{org_name}/{app_name}/chatrooms

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
name	String	是	名稱，1 到 128 個字元，不能包含控制字元，首尾的空白會被去掉
owner	String	否	所有者的使用者名稱，必須是已存在的使用者，不要求他在聊天室裡。省略時沒有所有者
description	String	否	簡介，最長 512 個字元，可以換行。預設為空字串
avatar_url	String	否	封面地址，http 或 https 地址，最長 512 個字元，不能包含空白，見封面
announcement	String	否	公告，最長 2048 個字元，可以換行
max_members	Number	否	聊天室自己的人數上限，1 到 500000；省略或為 null 時跟隨執行策略，見資料與公告
listed	Boolean	否	是否出現在客戶端的聊天室列表中，預設 true
attributes	Object	否	初始屬性，鍵到字串值，最多 100 個鍵，鍵和值合計不超過 16 KB，格式見聊天室屬性

請求示例

curl -X POST "$IM_API/$ORG/$APP/chatrooms" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "周末音乐会",
    "owner": "zhangsan",
    "description": "每周六晚八点，现场演出",
    "avatar_url": "https://cdn.example.com/room/concert.png",
    "announcement": "欢迎来到直播间，请文明发言",
    "max_members": 50000,
    "attributes": { "live_id": "L-20261004", "theme": "night" }
  }'

響應

成功返回 201 Created，響應體為聊天室物件。

{
  "room_id": "100310941534519296",
  "name": "周末音乐会",
  "description": "每周六晚八点，现场演出",
  "avatar_url": "https://cdn.example.com/room/concert.png",
  "announcement": "欢迎来到直播间，请文明发言",
  "announcement_updated_at": "2026-10-04T19:19:52.149Z",
  "announcement_updated_by": null,
  "owner": "zhangsan",
  "admins": [],
  "max_members": 50000,
  "mute_all": false,
  "listed": true,
  "status": "active",
  "disabled_by": null,
  "member_count": 0,
  "info_version": 1,
  "attributes_version": 1,
  "created_at": "2026-10-04T19:19:52.149Z",
  "status_reason": null,
  "max_members_setting": 50000,
  "created_via": "openapi",
  "created_by": null,
  "dismissed_at": null,
  "attribute_count": 2
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	缺少 name，或欄位取值不合法；屬性的鍵或值不合法時 details.reason 為 invalid_attribute_key 或 invalid_attribute_value，details.key 指出鍵；屬性合計超過 16 KB 時為 attributes_too_large
403	content_rejected	名稱、簡介或公告沒有透過內容稽核，details.field 為欄位名
403	app_unavailable	應用處於只讀狀態，不能建立聊天室
404	not_found	owner 指定的使用者不存在
409	limit_exceeded	details.reason 為 chatroom_limit：應用中未解散的聊天室數已達上限

查詢聊天室列表

分頁列出應用內的聊天室，可以按狀態、所有者篩選，按名稱字首搜尋。預設只列出未解散的聊天室（含已封禁的），按建立時間從新到舊排列；按名稱字首搜尋時按名稱排列。每項帶當前的線上人數。

GET/{org_name}/{app_name}/chatrooms

路徑引數

org_name、app_name 見接入概述。

查詢引數

引數	型別	必填	說明
status	String	否	只列出這種狀態的聊天室：active、disabled 或 dismissed。省略時列出 active 和 disabled 的；已解散的聊天室在解散 30 天后不再出現
owner	String	否	只列出這個使用者擔任所有者的聊天室；使用者不存在時返回空列表
name_prefix	String	否	按名稱的字首搜尋，最長 128 個字元；% 和 _ 按普通字元匹配
limit	Number	否	每頁條數，預設 20，取值 1 到 100
cursor	String	否	下一頁的遊標，見分頁

請求示例

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

響應

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

{
  "items": [
    {
      "room_id": "100310941534519296",
      "name": "周末音乐会",
      "description": "每周六晚八点，现场演出",
      "avatar_url": "https://cdn.example.com/t100308694423568384/a100308695405035520/r/100313154805825536_r8g57ewc.jpg",
      "announcement": "今晚 8 点开播，请文明发言",
      "announcement_updated_at": "2026-10-04T19:21:44.379Z",
      "announcement_updated_by": null,
      "owner": "zhangsan",
      "admins": ["lisi"],
      "max_members": 100000,
      "mute_all": false,
      "listed": true,
      "status": "active",
      "disabled_by": null,
      "member_count": 4,
      "info_version": 21,
      "attributes_version": 8,
      "created_at": "2026-10-04T19:19:52.149Z",
      "status_reason": null,
      "max_members_setting": null,
      "created_via": "openapi",
      "created_by": null,
      "dismissed_at": null,
      "attribute_count": 3
    }
  ],
  "next_cursor": null
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	status 的取值不合法、name_prefix 超過 128 個字元、limit 超出範圍，或 cursor 無效

查詢聊天室資訊

返回一個聊天室的全部資訊，包括當前的線上人數。已解散的聊天室在解散後 30 天內也可以查詢，status 為 dismissed。

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

路徑引數

org_name、app_name 見接入概述。

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

請求示例

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

響應

成功返回 200 OK，響應體為聊天室物件。

{
  "room_id": "100310941534519296",
  "name": "周末音乐会",
  "description": "每周六晚八点，现场演出",
  "avatar_url": "https://cdn.example.com/t100308694423568384/a100308695405035520/r/100313154805825536_r8g57ewc.jpg",
  "announcement": "今晚 8 点开播，请文明发言",
  "announcement_updated_at": "2026-10-04T19:21:44.379Z",
  "announcement_updated_by": null,
  "owner": "zhangsan",
  "admins": ["lisi"],
  "max_members": 100000,
  "mute_all": false,
  "listed": true,
  "status": "active",
  "disabled_by": null,
  "member_count": 4,
  "info_version": 21,
  "attributes_version": 8,
  "created_at": "2026-10-04T19:19:52.149Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "created_by": null,
  "dismissed_at": null,
  "attribute_count": 3
}

錯誤

HTTP 狀態碼	code	說明
404	not_found	聊天室不存在，或 room_id 的格式不對

批次查詢線上人數

一次查詢最多 100 個聊天室的線上人數，適合在聊天室列表頁上顯示人數。線上人數的含義見線上人數。

POST/{org_name}/{app_name}/chatrooms/online-counts

路徑引數

org_name、app_name 見接入概述。

請求體

欄位	型別	必填	說明
room_ids	Array<String>	是	聊天室 ID，最多 100 個，重複的只返回一次。格式不對的 ID 被忽略；為空陣列時返回空的 items

請求示例

curl -X POST "$IM_API/$ORG/$APP/chatrooms/online-counts" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "room_ids": ["100310941534519296", "100311027031212032", "123"]
  }'

響應

成功返回 200 OK，items 中每項為一個聊天室的線上人數，按請求中的順序排列。不存在和已解散的聊天室不在結果中，已封禁的為 0。

欄位	型別	說明
room_id	String	聊天室 ID
member_count	Number	線上人數

{
  "items": [
    { "room_id": "100310941534519296", "member_count": 6 },
    { "room_id": "100311027031212032", "member_count": 0 }
  ]
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	room_ids 超過 100 個

修改聊天室資料

修改聊天室的名稱、簡介、封面、公告、人數上限和是否列出。只修改請求中出現的欄位，沒有出現的欄位保持不變；請求中的值都與原值相同（或沒有任何欄位）時不做任何修改，changed 為 false。修改後線上成員會實時收到通知。

被封禁的聊天室也可以修改，便於清除違規的名稱、公告和封面。所有者用轉讓所有者修改，屬性用設定聊天室屬性修改，這個介面不接受 owner、attributes 欄位。

PATCH/{org_name}/{app_name}/chatrooms/{room_id}

路徑引數

org_name、app_name 見接入概述。

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

請求體

各欄位的格式要求與建立聊天室相同。

欄位	型別	必填	說明
name	String	否	名稱，1 到 128 個字元，不能清空
description	String	否	簡介，最長 512 個字元；傳空字串表示清空
avatar_url	String	否	封面地址；傳空字串表示清空。替換或清空本服務的封面後，原來的封面檔案在 7 天后刪除
announcement	String	否	公告，最長 2048 個字元；傳空字串表示清空。公告變化時 announcement_updated_at 更新為當前時間
max_members	Number	否	聊天室自己的人數上限，1 到 500000；為 null 時清除，改為跟隨執行策略
listed	Boolean	否	是否出現在客戶端的聊天室列表中
version	Number	否	讀取到的 info_version。帶上時，與當前的 info_version 不一致則返回 409 version_conflict，不做任何修改

請求示例

curl -X PATCH "$IM_API/$ORG/$APP/chatrooms/100310941534519296" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "announcement": "今晚 8 点开播，请文明发言",
    "max_members": null,
    "version": 2
  }'

響應

成功返回 200 OK，響應體為修改後的聊天室物件，另加一個欄位：

欄位	型別	說明
changed	Boolean	這次請求是否改變了聊天室。為 false 時 info_version 不變，也不會通知成員

{
  "room_id": "100310941534519296",
  "name": "周末音乐会",
  "description": "每周六晚八点，现场演出",
  "avatar_url": "https://cdn.example.com/room/concert.png",
  "announcement": "今晚 8 点开播，请文明发言",
  "announcement_updated_at": "2026-10-04T19:21:44.379Z",
  "announcement_updated_by": null,
  "owner": "zhangsan",
  "admins": ["lisi"],
  "max_members": 100000,
  "mute_all": false,
  "listed": true,
  "status": "active",
  "disabled_by": null,
  "member_count": 6,
  "info_version": 3,
  "attributes_version": 1,
  "created_at": "2026-10-04T19:19:52.149Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "created_by": null,
  "dismissed_at": null,
  "attribute_count": 2,
  "changed": true
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	欄位取值不合法，如名稱為空；請求中包含不能修改的欄位（如 owner、attributes）
403	content_rejected	名稱、簡介或公告沒有透過內容稽核，details.field 為欄位名
403	app_unavailable	應用處於只讀狀態，不能修改資料
404	not_found	聊天室不存在或已解散
409	version_conflict	version 與當前的 info_version 不一致，details.info_version 為當前值，請重新查詢後再決定是否修改

轉讓所有者

把所有者轉給應用內的任意一個使用者，不要求他此刻在聊天室裡，也不需要他同意；也可以清空所有者，由你的服務端管理。轉讓後：

誰	變化
原所有者	變為普通使用者
新所有者	原來是管理員的不再佔管理員名額；原來被禁言、被封禁的自動解除（沒有人能禁言、封禁所有者）
聊天室	info_version 加一，線上成員實時收到通知

指定的就是當前所有者時不做任何改變，changed 為 false。被封禁的聊天室也可以轉讓，便於處置所有者本人的違規行為。

PUT/{org_name}/{app_name}/chatrooms/{room_id}/owner

路徑引數

org_name、app_name 見接入概述。

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

請求體

欄位	型別	必填	說明
username	String	是	新所有者的使用者名稱，必須是已存在的使用者；為 null 時清空所有者

請求示例

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

響應

成功返回 200 OK，響應體為轉讓後的聊天室物件，另加 changed 欄位，含義同修改聊天室資料。

{
  "room_id": "100310941534519296",
  "name": "周末音乐会",
  "description": "每周六晚八点，现场演出",
  "avatar_url": "https://cdn.example.com/room/concert.png",
  "announcement": "今晚 8 点开播，请文明发言",
  "announcement_updated_at": "2026-10-04T19:21:44.379Z",
  "announcement_updated_by": null,
  "owner": "zhaoliu",
  "admins": ["lisi"],
  "max_members": 100000,
  "mute_all": false,
  "listed": true,
  "status": "active",
  "disabled_by": null,
  "member_count": 4,
  "info_version": 12,
  "attributes_version": 8,
  "created_at": "2026-10-04T19:19:52.149Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "created_by": null,
  "dismissed_at": null,
  "attribute_count": 3,
  "changed": true
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	請求體中沒有 username 欄位
404	not_found	聊天室不存在或已解散；username 指定的使用者不存在

開啟全員禁言

開啟後，只有所有者、管理員和白名單中的使用者可以在客戶端傳送訊息和設定屬性，其他使用者傳送時返回 403 chatroom_muted，details.reason 為 all。被單獨禁言的使用者即使是管理員或在白名單中也不能發言。

線上成員會實時收到通知。已經開啟時再次呼叫不做任何改變，changed 為 false。被封禁的聊天室也可以設定。

提示

禁言只限制使用者在客戶端發言。你的服務端傳送訊息時不受禁言和全員禁言的限制。

PUT/{org_name}/{app_name}/chatrooms/{room_id}/mute-all

路徑引數

org_name、app_name 見接入概述。

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

請求示例

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

響應

成功返回 200 OK，響應體為聊天室物件，另加 changed 欄位，含義同修改聊天室資料。

{
  "room_id": "100310941534519296",
  "name": "周末音乐会",
  "description": "每周六晚八点，现场演出",
  "avatar_url": "https://cdn.example.com/room/concert.png",
  "announcement": "今晚 8 点开播，请文明发言",
  "announcement_updated_at": "2026-10-04T19:21:44.379Z",
  "announcement_updated_by": null,
  "owner": "zhangsan",
  "admins": ["lisi"],
  "max_members": 100000,
  "mute_all": true,
  "listed": true,
  "status": "active",
  "disabled_by": null,
  "member_count": 6,
  "info_version": 8,
  "attributes_version": 1,
  "created_at": "2026-10-04T19:19:52.149Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "created_by": null,
  "dismissed_at": null,
  "attribute_count": 2,
  "changed": true
}

錯誤

HTTP 狀態碼	code	說明
404	not_found	聊天室不存在或已解散

關閉全員禁言

關閉全員禁言，所有使用者恢復發言。單獨禁言的使用者仍然不能發言，要另行解除禁言。沒有開啟時呼叫不做任何改變，changed 為 false。

DELETE/{org_name}/{app_name}/chatrooms/{room_id}/mute-all

路徑引數

org_name、app_name 見接入概述。

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

請求示例

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

響應

成功返回 200 OK，響應體與開啟全員禁言相同，其中 mute_all 為 false。

錯誤

HTTP 狀態碼	code	說明
404	not_found	聊天室不存在或已解散

設定管理員

把一個使用者設為聊天室的管理員，不要求他此刻在聊天室裡。每個聊天室最多 99 個管理員。他已經是管理員或是所有者時不做任何改變，changed 為 false。被禁言的使用者也可以設為管理員，禁言照常有效；正在被這個聊天室封禁的使用者不能設為管理員，請先解除封禁。

設定後 info_version 加一，線上成員實時收到通知，其中帶完整的管理員列表。

PUT/{org_name}/{app_name}/chatrooms/{room_id}/admins/{username}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
room_id	String	聊天室 ID
username	String	要設為管理員的使用者名稱

請求示例

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

響應

成功返回 200 OK：

欄位	型別	說明
changed	Boolean	這次請求是否改變了管理員
info_version	Number	聊天室當前的 info_version

{
  "changed": true,
  "info_version": 2
}

錯誤

HTTP 狀態碼	code	說明
403	permission_denied	details.reason 為 target_banned：這個使用者正在被聊天室封禁
404	not_found	聊天室不存在或已解散，或使用者不存在
409	limit_exceeded	details.reason 為 admin_limit：管理員已滿 99 人

取消管理員

取消一個使用者的管理員身份，他變為普通使用者。他不是管理員時不做任何改變，changed 為 false。封禁管理員時，他的管理員身份會自動取消，不必先呼叫這個介面。

DELETE/{org_name}/{app_name}/chatrooms/{room_id}/admins/{username}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
room_id	String	聊天室 ID
username	String	管理員的使用者名稱

請求示例

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

響應

成功返回 200 OK，欄位同設定管理員。

{
  "changed": true,
  "info_version": 17
}

錯誤

HTTP 狀態碼	code	說明
404	not_found	聊天室不存在或已解散，或使用者不存在

查詢聊天室屬性

返回聊天室的全部屬性，或其中指定的幾個鍵。

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

路徑引數

org_name、app_name 見接入概述。

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

查詢引數

引數	型別	必填	說明
keys	String	否	只返回這些鍵，用逗號分隔，最多 100 個；不存在的鍵不出現在結果中。省略時返回全部屬性

請求示例

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

響應

成功返回 200 OK：

欄位	型別	說明
attributes	Object	鍵到屬性的物件，沒有屬性時為空物件。每個屬性的欄位見下表
attributes_version	Number	屬性的版本號

屬性的欄位	型別	說明
value	String	值
owner	String	最近一次設定這個鍵的使用者名稱；由你的服務端或控制檯設定的，或設定人已被刪除的，為 null
auto_delete	Boolean	是否在設定人離開聊天室時自動刪除
updated_at	String	最近一次設定的時間

{
  "attributes": {
    "game_state": {
      "value": "round-2",
      "owner": null,
      "auto_delete": false,
      "updated_at": "2026-10-04T19:24:10.996Z"
    },
    "live_id": {
      "value": "L-20261004",
      "owner": null,
      "auto_delete": false,
      "updated_at": "2026-10-04T19:19:52.149Z"
    },
    "seat_1": {
      "value": "wangwu",
      "owner": null,
      "auto_delete": false,
      "updated_at": "2026-10-04T19:24:10.996Z"
    },
    "seat_2": {
      "value": "zhengshi",
      "owner": "zhengshi",
      "auto_delete": true,
      "updated_at": "2026-10-04T19:24:35.088Z"
    },
    "theme": {
      "value": "day",
      "owner": null,
      "auto_delete": false,
      "updated_at": "2026-10-04T19:24:10.996Z"
    }
  },
  "attributes_version": 3
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	keys 中有不合法的鍵（details.reason 為 invalid_attribute_key），或超過 100 個
404	not_found	聊天室不存在或已解散

設定聊天室屬性

新增或覆蓋一批屬性，一次最多 20 個鍵。服務端可以覆蓋任何人設定的鍵，覆蓋後這些鍵的 owner 變為 null、auto_delete 變為 false。值與原來相同、原來也是由服務端設定的鍵不算變化。有鍵被寫入時 attributes_version 加一，線上成員實時收到通知。

寫入後屬性的個數超過 100 個或合計超過 16 KB 的鍵不寫入，在 failed 中返回，其他鍵照常寫入。被封禁的聊天室也可以設定。

PUT/{org_name}/{app_name}/chatrooms/{room_id}/attributes

路徑引數

org_name、app_name 見接入概述。

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

請求體

欄位	型別	必填	說明
attributes	Object	是	要設定的屬性，鍵到字串值，1 到 20 個鍵，鍵和值合計不超過 16 KB，格式見聊天室屬性
auto_delete	Boolean	否	只能為 false（預設）。服務端設定的屬性不能隨設定人離開而刪除，為 true 時返回 400 invalid_argument，details.reason 為 auto_delete_not_allowed

請求示例

curl -X PUT "$IM_API/$ORG/$APP/chatrooms/100310941534519296/attributes" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "theme": "day",
      "seat_1": "wangwu",
      "game_state": "round-2"
    }
  }'

響應

成功返回 200 OK：

欄位	型別	說明
changed	Boolean	是否有鍵被寫入
attributes_version	Number	屬性的版本號：有變化時為變化後的版本號，否則為當前的版本號
failed	Object	沒有寫入的鍵，鍵到失敗原因（code 和 details）；都寫入時為空物件。目前只有 limit_exceeded（details.reason 為 attribute_limit）：寫入後屬性的個數或合計大小超出上限

{
  "changed": true,
  "attributes_version": 2,
  "failed": {}
}

部分鍵超出上限時：

{
  "changed": true,
  "attributes_version": 5,
  "failed": {
    "big4": {
      "code": "limit_exceeded",
      "details": { "reason": "attribute_limit" }
    }
  }
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	attributes 為空或超過 20 個鍵；鍵或值不合法（details.reason 為 invalid_attribute_key 或 invalid_attribute_value，details.key 指出鍵）；鍵和值合計超過 16 KB（attributes_too_large，details.max_bytes 為 16384）；auto_delete 為 true（auto_delete_not_allowed）
403	app_unavailable	應用處於只讀狀態，不能設定屬性
404	not_found	聊天室不存在或已解散
429	rate_limited	details.reason 為 room_attribute_rate：這個聊天室每秒的屬性寫入已達 20 次

刪除聊天室屬性

刪除一批屬性，一次最多 20 個鍵。服務端可以刪除任何人設定的鍵，不存在的鍵忽略。有鍵被刪除時 attributes_version 加一，線上成員實時收到通知。應用處於只讀狀態時也可以刪除。

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

路徑引數

org_name、app_name 見接入概述。

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

請求體

欄位	型別	必填	說明
keys	Array<String>	是	要刪除的鍵，1 到 20 個，重複的只處理一次

請求示例

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100310941534519296/attributes/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["game_state", "seat_2"]
  }'

響應

成功返回 200 OK，欄位同設定聊天室屬性，其中 changed 表示是否有鍵被刪除。

{
  "changed": true,
  "attributes_version": 8,
  "failed": {}
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	keys 為空或超過 20 個，或其中有不合法的鍵
404	not_found	聊天室不存在或已解散
429	rate_limited	details.reason 為 room_attribute_rate：這個聊天室每秒的屬性寫入已達 20 次

封禁聊天室

暫時停用一個聊天室，用於處置違規的直播間，之後可以解封。封禁時：

	結果
線上使用者	全部被移出（原因 disabled）；封禁期間進入返回 403 chatroom_disabled
訊息	最近的訊息被清空；誰都不能發訊息，包括你的服務端（403 chatroom_disabled）
客戶端的管理操作	全部不能用
你的服務端	仍可修改資料和公告、轉讓所有者、設定管理員、禁言、封禁和管理白名單、設定和刪除屬性（清除違規內容），也可以解散

封禁後 status 變為 disabled，disabled_by 為 tenant，info_version 加一。解封后資料、管理員、名單和屬性都保持原樣，使用者重新進入即可。

被平臺封禁的聊天室

disabled_by 為 platform 的聊天室是被平臺以違反法律法規或平臺規則為由封禁的。這樣的聊天室你不能解封、不能解散；再次呼叫封禁不會改變它，直接返回當前資訊。

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

路徑引數

org_name、app_name 見接入概述。

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

請求體

請求體可以省略。

欄位	型別	必填	說明
reason	String	否	封禁原因，最長 256 個字元，不能包含控制字元。儲存在聊天室物件的 status_reason 中，只在服務端介面和控制檯中可見，客戶端看不到

對已經由你封禁的聊天室再次呼叫時，只用新的 reason 替換原來的原因（省略時清空原因），info_version 不變，也不會通知使用者；原因有變化時 changed 為 true，沒有變化時為 false。

請求示例

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100311027198984192/disable" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "直播内容违规，调查中"
  }'

響應

成功返回 200 OK，響應體為封禁後的聊天室物件，另加 changed 欄位，含義同修改聊天室資料。

{
  "room_id": "100311027198984192",
  "name": "周末音乐会 · 彩排",
  "description": "",
  "avatar_url": "",
  "announcement": "",
  "announcement_updated_at": null,
  "announcement_updated_by": null,
  "owner": null,
  "admins": [],
  "max_members": 100000,
  "mute_all": false,
  "listed": true,
  "status": "disabled",
  "disabled_by": "tenant",
  "member_count": 0,
  "info_version": 2,
  "attributes_version": 0,
  "created_at": "2026-10-04T19:20:12.573Z",
  "status_reason": "直播内容违规，调查中",
  "max_members_setting": null,
  "created_via": "openapi",
  "created_by": null,
  "dismissed_at": null,
  "attribute_count": 0,
  "changed": true
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	reason 超過 256 個字元或包含控制字元
404	not_found	聊天室不存在或已解散

解封聊天室

解除你對聊天室的封禁，聊天室恢復正常，使用者可以重新進入。status 變為 active，status_reason 被清空，info_version 加一。聊天室沒有被封禁時呼叫不做任何改變，changed 為 false。

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

路徑引數

org_name、app_name 見接入概述。

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

請求示例

curl -X POST "$IM_API/$ORG/$APP/chatrooms/100311027198984192/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	聊天室不存在或已解散

解散聊天室

解散一個聊天室，不能恢復，通常在直播結束時呼叫。解散後：

	結果
線上使用者	全部被移出（原因 dismissed），任何人都不能再進入
管理資料	管理員、禁言、封禁、白名單、屬性和最近的訊息隨後刪除
計數與 ID	不再計入應用的聊天室數；ID 不會複用
查詢	30 天內仍可查詢聊天室資訊（status 為 dismissed），其他介面返回 404 not_found（chatroom_dismissed）；30 天后記錄刪除

重複解散同一個聊天室同樣返回 204 No Content。

DELETE/{org_name}/{app_name}/chatrooms/{room_id}

路徑引數

org_name、app_name 見接入概述。

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

請求示例

curl -X DELETE "$IM_API/$ORG/$APP/chatrooms/100311027031212032" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 204 No Content，沒有響應體。解散後查詢這個聊天室：

{
  "room_id": "100311027031212032",
  "name": "新品发布会互动区",
  "description": "",
  "avatar_url": "",
  "announcement": "",
  "announcement_updated_at": null,
  "announcement_updated_by": null,
  "owner": null,
  "admins": [],
  "max_members": 100000,
  "mute_all": false,
  "listed": false,
  "status": "dismissed",
  "disabled_by": null,
  "member_count": 0,
  "info_version": 1,
  "attributes_version": 0,
  "created_at": "2026-10-04T19:20:12.533Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "created_by": null,
  "dismissed_at": "2026-10-04T19:27:20.733Z",
  "attribute_count": 0
}

錯誤

HTTP 狀態碼	code	說明
403	permission_denied	聊天室被平臺封禁（disabled_by 為 platform），不能解散
404	not_found	聊天室不存在

資料結構

聊天室物件

服務端介面返回的聊天室物件包含以下全部欄位。客戶端看到的聊天室資訊不含 status_reason、max_members_setting、created_via、created_by、dismissed_at 和 attribute_count。

欄位	型別	說明
room_id	String	聊天室 ID，由系統生成，建立後不變
name	String	名稱
description	String	簡介，沒有時為空字串
avatar_url	String	封面地址，沒有時為空字串
announcement	String	公告，沒有時為空字串
announcement_updated_at	String	公告最近一次修改的時間，從未設定過公告時為 null
announcement_updated_by	String	最近一次在客戶端修改公告的使用者名稱；由服務端或控制檯修改、或修改人已被刪除時為 null
owner	String	所有者的使用者名稱；沒有所有者或所有者已被刪除時為 null
admins	Array<String>	管理員的使用者名稱，按設定的先後排列，沒有時為空陣列
max_members	Number	實際生效的人數上限：聊天室自己的上限與執行策略 max_chatroom_members 中較小的一個
mute_all	Boolean	是否開啟了全員禁言
listed	Boolean	是否出現在客戶端的聊天室列表中
status	String	狀態：active 正常，disabled 已封禁，dismissed 已解散
disabled_by	String	封禁方：tenant 由你（服務端或控制檯）封禁，platform 由平臺封禁；未封禁時為 null
member_count	Number	線上人數，近似值，見線上人數；已封禁、已解散的為 0
info_version	Number	資料和設定的版本號，見版本號
attributes_version	Number	屬性的版本號
created_at	String	建立時間
status_reason	String	封禁原因，可為 null。只在服務端介面和控制檯中返回
max_members_setting	Number	聊天室自己設定的人數上限，沒有設定時為 null
created_via	String	建立方式：openapi 服務端介面，console 控制檯，client 使用者在客戶端建立
created_by	String	在客戶端建立這個聊天室的使用者名稱；由服務端或控制檯建立、或建立人已被刪除時為 null
dismissed_at	String	解散時間，未解散時為 null
attribute_count	Number	屬性的個數

{
  "room_id": "100310941534519296",
  "name": "周末音乐会",
  "description": "每周六晚八点，现场演出",
  "avatar_url": "https://cdn.example.com/t100308694423568384/a100308695405035520/r/100313154805825536_r8g57ewc.jpg",
  "announcement": "今晚 8 点开播，请文明发言",
  "announcement_updated_at": "2026-10-04T19:21:44.379Z",
  "announcement_updated_by": null,
  "owner": "zhangsan",
  "admins": ["lisi"],
  "max_members": 100000,
  "mute_all": false,
  "listed": true,
  "status": "active",
  "disabled_by": null,
  "member_count": 4,
  "info_version": 21,
  "attributes_version": 8,
  "created_at": "2026-10-04T19:19:52.149Z",
  "status_reason": null,
  "max_members_setting": null,
  "created_via": "openapi",
  "created_by": null,
  "dismissed_at": null,
  "attribute_count": 3
}