聊天室管理

聊天室适合直播间、语聊房、大型活动的互动区：没有固定成员，不保存离线消息，一个聊天室的人数可以达到几十万。常见的用法是业务服务端在直播开始时创建聊天室、结束时解散，用户在客户端打开直播间时进入，离开页面时离开；你的服务端负责创建和解散聊天室、发送系统消息、处置违规的用户。

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

聊天室成员：查询在线成员，移出、禁言、封禁用户，管理白名单；
聊天室消息：发送消息、查询最近的消息、撤回消息。

服务端不受聊天室内身份的限制

用 App Token 调用时，你以应用管理者的身份操作，可以执行全部管理操作，不受所有者、管理员等身份的限制。只有一条规则对服务端同样有效：不能禁言、移出或封禁所有者，要处置所有者，请先转让或清空所有者。

创建聊天室不是幂等的

创建请求超时后重试，可能创建出两个聊天室。请以返回的 room_id 为准保存对应关系；重试前可以按所有者或名称前缀查询聊天室列表，确认上次没有创建成功，多创建的解散即可。

聊天室不存在时，接口返回 404 not_found。已解散的聊天室在解散后 30 天内仍可以查询，其他接口返回 404 not_found，details.reason 为 chatroom_dismissed，你可以据此区分“已解散”和“不存在”：

json

{
  "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 秒内重新连接并进入的，不会先离开再进入。所有者和管理员离开后仍保留身份。
被移出：用户被移出或封禁、聊天室被封禁或解散时，他的连接收到移出的通知，带原因 kicked（被移出）、banned（被封禁）、disabled（聊天室被封禁）或 dismissed（聊天室已解散），客户端不应自动重新进入。
进入的频率：每条连接每分钟最多进入 10 次；每个聊天室每秒最多进入 2000 人，超出时客户端收到限流的错误，等待 1 到 3 秒的随机时间后重试，直播开始时大量用户同时进入，会被分散到十几秒内完成。

在线人数不超过运行策略 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 条），三种优先级都计入。
下发时合并与限速：热闹的聊天室中，消息每 200 毫秒合并成一批推给客户端。每条连接从一个聊天室每秒最多收到 50 条、128 KB 普通和低优先级的内容，超出时先丢弃低优先级的，再丢弃普通的，等待超过 1 秒还没下发的也会丢弃；高优先级的内容先于其他内容下发，正常情况下不会被丢弃。连接的网络很差、积压过多时，这条连接只收到高优先级的内容。客户端会收到被丢弃的条数，可以显示“消息过多，已省略部分”。
不保证送达和顺序：聊天室消息只推给此刻在其中的连接，网络异常时可能丢失，不同用户发出的消息到达的先后可能略有不同。需要可靠送达的内容（如礼物结算）请用高优先级发送，并由你的业务另行保证。

聊天室自身的通知中，资料、禁言、白名单、属性的变化和消息撤回为高优先级，成员进出为低优先级。

资料与公告

字段	说明
`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 上传图片（创建聊天室前就可以上传），完成上传后得到图片的公开地址，在创建聊天室或修改资料时填进 avatar_url。图片会被缩放到长边不超过 640 像素，公开地址任何人都可以访问。上传后 24 小时内没有被任何聊天室使用的，以及被替换（改为其他地址或清空）、聊天室解散 7 天后的封面文件会被删除。
使用你自己的地址：服务端接口写入的 avatar_url 只检查格式，不会访问这个地址。用户在客户端创建聊天室或修改封面时，如果应用在运行策略中开启了 media_url_only，只能使用本应用的封面地址或 media_allowed_hosts 中主机的 https 地址，否则返回 400 invalid_argument，details.reason 为 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，格式见聊天室属性

请求示例

bash

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，响应体为聊天室对象。

json

{
  "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	否	下一页的游标，见分页

请求示例

bash

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

响应

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

json

{
  "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

请求示例

bash

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

响应

成功返回 200 OK，响应体为聊天室对象。

json

{
  "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`

请求示例

bash

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	在线人数

json

{
  "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`，不做任何修改

请求示例

bash

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` 不变，也不会通知成员

json

{
  "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` 时清空所有者

请求示例

bash

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 字段，含义同修改聊天室资料。

json

{
  "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

请求示例

bash

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

响应

成功返回 200 OK，响应体为聊天室对象，另加 changed 字段，含义同修改聊天室资料。

json

{
  "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

请求示例

bash

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	要设为管理员的用户名

请求示例

bash

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`

json

{
  "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	管理员的用户名

请求示例

bash

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

响应

成功返回 200 OK，字段同设置管理员。

json

{
  "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 个；不存在的键不出现在结果中。省略时返回全部属性

请求示例

bash

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	最近一次设置的时间

json

{
  "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`

请求示例

bash

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`）：写入后属性的个数或合计大小超出上限

json

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

部分键超出上限时：

json

{
  "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 个，重复的只处理一次

请求示例

bash

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 表示是否有键被删除。

json

{
  "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。

请求示例

bash

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 字段，含义同修改聊天室资料。

json

{
  "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

请求示例

bash

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 不会被复用；
解散后 30 天内仍可以查询聊天室信息（status 为 dismissed），其他接口返回 404 not_found，details.reason 为 chatroom_dismissed；30 天后聊天室的记录被删除。

重复解散同一个聊天室同样返回 204 No Content。

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

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`room_id`	String	聊天室 ID

请求示例

bash

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

响应

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

json

{
  "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	属性的个数

json

{
  "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
}

聊天室管理 ​

基本概念 ​

聊天室与群组的区别 ​

进入与离开 ​

身份 ​

在线人数 ​

消息的优先级与下发 ​

最近的消息 ​

资料与公告 ​

封面 ​

聊天室属性 ​

状态 ​

版本号 ​

创建聊天室 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

查询聊天室列表 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

查询聊天室信息 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

批量查询在线人数 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

修改聊天室资料 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

转让所有者 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

开启全员禁言 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

关闭全员禁言 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

设置管理员 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

取消管理员 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

查询聊天室属性 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

设置聊天室属性 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

聊天室管理

基本概念

聊天室与群组的区别

进入与离开

身份

在线人数

消息的优先级与下发

最近的消息

资料与公告

封面

聊天室属性

状态

版本号

创建聊天室

路径参数

请求体

请求示例

响应

错误

查询聊天室列表

路径参数

查询参数

请求示例

响应

错误

查询聊天室信息

路径参数

请求示例

响应

错误

批量查询在线人数

路径参数

请求体

请求示例

响应

错误

修改聊天室资料

路径参数

请求体

请求示例

响应

错误

转让所有者

路径参数

请求体

请求示例

响应

错误

开启全员禁言

路径参数

请求示例

响应

错误

关闭全员禁言

路径参数

请求示例

响应

错误

设置管理员

路径参数

请求示例

响应

错误

取消管理员

路径参数

请求示例

响应

错误

查询聊天室属性

路径参数

查询参数

请求示例

响应

错误

设置聊天室属性

路径参数

请求体

请求示例

响应

错误