聊天室成员

聊天室的成员就是此刻在聊天室里的用户：用户在客户端通过长连接进入后成为成员，离开或连接断开 15 秒后就不再是成员，成员关系不保存。本页的接口用来查询在线成员、判断某个用户是否在聊天室里、把用户移出聊天室，以及管理禁言、封禁和白名单三个名单。聊天室的基本概念（进入与离开、身份、全员禁言）见聊天室管理。

禁言、封禁与白名单

三个名单保存在服务端，与用户是否在聊天室里无关：可以对此刻不在聊天室里的用户操作，用户离开后再进入，名单照样有效。

名单	效果	时长	每个聊天室的上限
禁言	不能在客户端发送消息、设置属性；仍然可以进入聊天室、接收消息、删除自己设置的属性。发送时返回 `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，details.reason 为 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 人）

聊天室成员 ​

禁言、封禁与白名单 ​

名单的批量接口 ​

查询聊天室成员列表 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

查询用户是否在聊天室里 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

移出聊天室成员 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

查询禁言名单 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

禁言用户 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

解除禁言 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

查询封禁名单 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

封禁用户 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

解除封禁 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

查询白名单 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

加入白名单 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

移出白名单 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

数据结构 ​

成员对象 ​

禁言名单项 ​

封禁名单项 ​

白名单项 ​

批量操作结果 ​

聊天室成员

禁言、封禁与白名单

名单的批量接口

查询聊天室成员列表

路径参数

查询参数

请求示例

响应

错误

查询用户是否在聊天室里

路径参数

请求示例

响应

错误

移出聊天室成员

路径参数

请求体

请求示例

响应

错误

查询禁言名单

路径参数

查询参数

请求示例

响应

错误

禁言用户

路径参数

请求体

请求示例

响应

错误

解除禁言

路径参数

请求体

请求示例

响应

错误

查询封禁名单

路径参数

查询参数

请求示例

响应

错误

封禁用户

路径参数

请求体

请求示例

响应

错误

解除封禁

路径参数

请求体

请求示例

响应

错误

查询白名单

路径参数

查询参数

请求示例

响应

错误

加入白名单

路径参数

请求体

请求示例

响应

错误

移出白名单

路径参数

请求体

请求示例

响应

错误

数据结构

成员对象

禁言名单项

封禁名单项

白名单项

批量操作结果