功能概述

房间内成员封禁功能允许您对指定成员进行限制，具有以下特点：

• 可设置精确的封禁时长
• 被封禁成员的音视频流将不会被广播到房间内其他成员

当某成员被封禁后：

• 被封禁成员 仍可发布 自己的音视频流
• 被封禁成员 可以正常接收 其他人的音视频内容
• 其他成员 无法接收 被封禁成员的音视频内容
  • 新建立的订阅请求能成功，但不会收到实际的音视频数据
  • 已建立的订阅连接会保持最后一帧画面，声音将立即中断

应用场景

此功能适用于需要临时限制特定用户行为但不希望将其完全踢出房间的情况，如直播课堂临时禁言、多人会议管控等场景。

接口地址信息

• 请求方法：POST

• URL：

  网易云信为该功能提供以下两个 API 请求地址，使用 V2 地址需在请求 Body 中指定 cid，使用 V3 地址需在 URL 中指定 cname，您可以根据业务需求调用任一接口。

  • https://rtc.yunxinapi.com/v2/api/right/change
  • https://rtc.yunxinapi.com/v3/api/right/change?cname={cname}

URL 中参数说明：

参数名称	类型	示例	描述
cname	String	abc	房间名称。 仅在调用 V3 接口时需要设置。

接口请求频率

默认上限为 50 次/秒，若请求频率超出限制，可能会返回 429 错误码。
若您需要上调上限，请参考如何处理调用服务端 RESTful API 超出频率限制。

请求参数

• 请求中 Header 的设置请参考请求结构描述。

• 请求中 Body 须为 JSON 格式，参数说明如下：

参数名称	类型	是否必选	示例	描述
cid	Number	必选，仅适用于 V2 接口	1345315683331808	房间 ID。该 ID 为创建房间接口调用成功后返回的房间 ID，仅在调用 V2 接口时需要设置。
uid	Number	必选	999911110	被封禁权限的用户 ID。
audioRight	Number	必选	1	音频封禁状态： 1：禁止音频被订阅。 2：允许音频被订阅。
audioDuration	Number	可选	86400	设置音频封禁状态时长。单位为秒，取值范围为 0 ~ 2147483647，默认值为 0。 若时长设为 0，则表示一直维持封禁状态，直到被封禁成员重新加入房间后解禁。 当被封禁成员在房间内即可生效；若被封禁成员退出并重新加入房间，只要未超时，则仍旧生效。
videoRight	Number	必选	1	视频封禁状态： 1：禁止视频被订阅。 2：允许视频被订阅。
videoDuration	Number	可选	86400	设置视频封禁状态时长。单位为秒，取值范围为 0 ~ 2147483647，默认值为 0。 若时长设为 0，则表示一直维持封禁状态，直到被封禁成员重新加入房间后解禁。 当被封禁成员在房间内即可生效；若被封禁成员退出并重新加入房间，只要未超时，则仍旧生效。

返回参数

参数名称	类型	示例	描述
code	Number	200	业务错误码，200 表示请求成功。
errmsg	String	-	错误信息。
requestId	String	f8f274c1-0e9f-4583-a243-c61c06a19475	请求 ID。若请求出现问题，可以提供此 ID 给技术支持进行排查。

示例

请求示例

{
    "cid": 1345315683331808,
    "uid": 999911110,
    "audioDuration": 86400,
    "audioRight": 0
}

返回示例

{
    "code":200，
    "errmsg":""
}

错误码

• header 中的状态码：

  状态码列表请参考 header 中的 HTTP 状态码。

• body 中的错误码（code）：

错误码	说明
200	API 调用成功。
400	请求无效，比如房间已关闭。
401	接口鉴权失败。请检查请求 header 中的 CheckSum 字段是否正确。
404	cid 对应的房间不存在，请检查 cid 正确性。
429	请求个数超过频控限制。
500	调用失败，可能是以下原因： 设置封禁状态的 uid 不在房间中。 参数设置错误。