社群禁言

2026-05-22

说明

当前社群禁言功能仅支持对社群内的频道进行禁言操作，暂不支持社群级别的全局禁言。

用户登录 ZIM SDK 后，可通过 muteCommunityChannels 设置社群频道禁言状态，支持对多个频道批量设置。

前提条件

请参考实现基本消息收发完成 ZIM SDK 获取、初始化和用户登录。
请参考使用 Token 鉴权实现用户鉴权登录。
社群功能需要 ZIM SDK 3.0.0 及以上版本。
社群功能为旗舰版功能，使用前请联系 ZEGO 技术支持开通。
社群功能的 Token 生成方式与其他 ZIM 功能一致，无需额外权限声明。

功能说明

支持批量设置多个频道禁言状态，禁言配置通过 ZIMCommunityChannelMuteConfig 指定。
config.mode 可以决定禁言范围：NONE（不禁言，用于解除禁言）、NORMAL（禁言普通成员）、ALL（禁言包括管理员和群主在内的所有人）、CUSTOM（自定义角色范围，此时由 config.roles 控制）。
config 内填写 duration 指定禁言时长，单位秒，取值范围 1-2592001（约 30 天），或 -1 表示永久禁言。

设置成功后，可通过 ZIMCommunityChannelsMutedCallback 获取结果。

配置字段	说明
`mode`	禁言范围：`NONE`(0) 不禁言任何角色（用于解除禁言，isMute=true 且 mode=NONE 等价于取消禁言）、`NORMAL`(1) 禁言普通成员、`ALL`(2) 全员禁言、`CUSTOM`(3) 自定义角色范围
`roles`	当 `mode` 为 `Custom` 时生效，指定被禁言的角色列表
`duration`	禁言时长（秒），1-2592001 或 -1 表示永久禁言

channelIDs 和 communityID 是接口方法的直接参数，非 config 配置字段。

禁言机制说明

社群支持两种禁言维度，二者可叠加生效：

维度	接口	作用范围	说明
频道禁言	`muteCommunityChannels`	频道级别	对指定频道设置禁言，通过 `config.mode` 控制禁言角色范围
成员禁言	`muteCommunityMembers`	成员级别	对指定成员在指定频道（留空则对所有频道生效）设置禁言

当成员所在频道被设为禁言，且该成员也未被单独设为禁言时，以频道禁言配置为准。
当成员被单独设为禁言后，无论频道是否禁言，该成员都无法发送消息。
成员禁言的详细说明请参见社群成员管理 - 设置成员禁言。

示例代码

const channelIDs = ['channel_1', 'channel_2'];
const config: ZIMCommunityChannelMuteConfig = {
	duration: 3600,
	mode: 2, // "1: Normal" | "2: All" | "3: Custom"
	// roles: [101, 102], // 当 mode = 'Custom' 时传入
};

zim.muteCommunityChannels(true, channelIDs, communityID, config)
	.then((result: ZIMCommunityChannelsMutedResult) => {
		// result.errorChannelIDs 为操作失败的频道 ID 列表
	})
	.catch((err: ZIMError) => {
		// 操作失败
	});

const channelIDs = ['channel_1', 'channel_2'];
const config: ZIMCommunityChannelMuteConfig = {
	duration: 3600,
	mode: 2, // "1: Normal" | "2: All" | "3: Custom"
	// roles: [101, 102], // 当 mode = 'Custom' 时传入
};

zim.muteCommunityChannels(true, channelIDs, communityID, config)
	.then((result: ZIMCommunityChannelsMutedResult) => {
		// result.errorChannelIDs 为操作失败的频道 ID 列表
	})
	.catch((err: ZIMError) => {
		// 操作失败
	});

常见错误码

错误码	说明	处理建议
6001004	社群不存在	确认 communityID 是否正确
6001062	频道不存在	确认 channelID 是否正确
6001065	无法解散默认频道	默认频道不支持解散操作
6001007	社群权限错误	确认当前用户是否为管理员或所有者

查询频道禁言状态

调用 queryCommunityChannelsInfo 接口，批量查询指定频道的完整信息，可获取频道的当前禁言状态。

channelInfos 返回 ZIMCommunityChannelFullInfo 列表，其中 muteInfo 包含频道禁言信息。
errorChannelIDs 返回查询失败的频道 ID 列表。

结果字段	说明
`baseInfo`	频道基本信息
`createTime`	频道创建时间
`creatorUserID`	频道创建者用户 ID
`channelNotice`	频道公告
`channelAttributes`	频道属性字典
`currentMemberCount`	当前频道成员数
`muteInfo`	频道禁言信息，包含 `mode`、`expiredTime`、`roles`

muteInfo 字段说明

字段	类型	说明
mode	ZIMCommunityChannelMuteMode	当前禁言模式：`NONE`(0)、`NORMAL`(1)、`ALL`(2)、`CUSTOM`(3)
expiredTime	long	禁言失效时间（毫秒），到期后自动解除禁言
roles	ArrayList<Integer>	当前被禁言的角色列表，仅当 mode 为 `CUSTOM` 时有值

示例代码

const channelIDs = ['channel_1', 'channel_2'];

zim.queryCommunityChannelsInfo(channelIDs, communityID)
    .then((result: ZIMCommunityChannelsInfoQueriedResult) => {
        const { channelInfos } = result;
        channelInfos.forEach((channelInfo) => {
            const muteInfo = channelInfo.muteInfo;
            // muteInfo.mode : 当前频道禁言模式
            // muteInfo.expiredTime : 禁言失效时间（毫秒）
            // muteInfo.roles : 当前被禁言的角色列表
        });
    })
    .catch((err: ZIMError) => {
        // 查询失败
    });

const channelIDs = ['channel_1', 'channel_2'];

zim.queryCommunityChannelsInfo(channelIDs, communityID)
    .then((result: ZIMCommunityChannelsInfoQueriedResult) => {
        const { channelInfos } = result;
        channelInfos.forEach((channelInfo) => {
            const muteInfo = channelInfo.muteInfo;
            // muteInfo.mode : 当前频道禁言模式
            // muteInfo.expiredTime : 禁言失效时间（毫秒）
            // muteInfo.roles : 当前被禁言的角色列表
        });
    })
    .catch((err: ZIMError) => {
        // 查询失败
    });

监听频道禁言变化事件

当频道资料（名称、头像、公告、属性、禁言状态等）发生变化时，SDK 会触发频道信息更新回调。可通过该回调获取 updateInfoList 中的 channelInfo.muteInfo，判断频道当前的禁言模式与禁言角色。

communityID：触发更新的社群 ID。
updateInfoList：变更后的频道完整信息列表。
channelInfo.muteInfo：包含 mode、expiredTime、roles 等禁言状态信息。

由于社群规模较大，SDK 可能只向活跃用户推送频道信息变化通知。若未收到推送，可通过 queryCommunityChannelsInfo 主动拉取最新频道信息。

示例代码

zim.on('communityChannelInfoUpdated', (zim, result) => {
    const communityID = result.communityID;
    result.updateInfoList.forEach((updateInfo) => {
        const channelInfo = updateInfo.channelInfo;
        const muteInfo = channelInfo.muteInfo;
        // muteInfo.mode : 当前频道禁言模式
        // muteInfo.expiredTime : 禁言失效时间（毫秒）
        // muteInfo.roles : 当前被禁言的角色列表
    });
});

zim.on('communityChannelInfoUpdated', (zim, result) => {
    const communityID = result.communityID;
    result.updateInfoList.forEach((updateInfo) => {
        const channelInfo = updateInfo.channelInfo;
        const muteInfo = channelInfo.muteInfo;
        // muteInfo.mode : 当前频道禁言模式
        // muteInfo.expiredTime : 禁言失效时间（毫秒）
        // muteInfo.roles : 当前被禁言的角色列表
    });
});

社群禁言

前提条件

功能说明

禁言机制说明

示例代码

查询频道禁言状态

muteInfo 字段说明

监听频道禁言变化事件

相关参考