频道管理

2026-05-22

功能简介

频道（Channel）是社群内聊天互动的基本载体，功能类似传统群组，每个社群可包含多个频道。ZIM SDK 提供了完整的频道管理能力，支持以下功能：

创建/解散频道
更新频道名称、头像、公告
设置/删除频道自定义属性
查询频道信息及列表
设置频道禁言状态
监听频道列表变更与信息更新

前提条件

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

频道类型说明

类型	说明	加入方式	可见性
GENERAL	默认频道，创建社群时自动创建，社群级别的 Tips 和通知会发在此频道	自动加入	所有成员可见
PUBLIC	公开频道，需要创建社群之后再创建	自动加入	所有成员可见

说明

GENERAL 和 PUBLIC 功能完全一样，区别仅在于创建时机：GENERAL 在创建社群时自动创建，PUBLIC 需要在创建社群后手动创建。

创建频道

加入社群后，调用 createCommunityChannel 接口，传入频道基础信息 ZIMCommunityChannelInfo 与创建配置 ZIMCommunityChannelCreateConfig 在指定社群中创建频道。

说明

只有社群群主和管理员有权限创建频道。
创建社群时系统会自动创建一个类型为 GENERAL 的默认频道；开发者可以在此基础上创建更多公开频道（PUBLIC）。
channelID 支持开发者自定义，仅支持数字、英文字符及以下特殊字符：! # $ % & ( ) + - : ; < = . > ? @ [ ] ^ _ { } | ~，但不能以 # 开头。若不填，ZIM 服务端会创建以 #C 开头的 channelID 的频道。
创建成功后即已加入频道，无需再调用加入接口。

示例代码

import im.zego.zim.ZIM;
import im.zego.zim.callback.ZIMCommunityChannelCreatedCallback;
import im.zego.zim.entity.ZIMCommunityChannelCreateConfig;
import im.zego.zim.entity.ZIMCommunityChannelFullInfo;
import im.zego.zim.entity.ZIMCommunityChannelInfo;
import im.zego.zim.entity.ZIMError;
import im.zego.zim.enums.ZIMErrorCode;

ZIMCommunityChannelInfo channelInfo = new ZIMCommunityChannelInfo();
channelInfo.setChannelID("channel_001");    // 频道 ID，可自定义
channelInfo.setChannelName("公告频道"); //最大长度300字符，可配置
channelInfo.setChannelAvatarUrl("https://example.com/channel_avatar.png"); //最大长度100字符，可配置
channelInfo.setCommunityID(communityID);    // 所属社群 ID

ZIMCommunityChannelCreateConfig config = new ZIMCommunityChannelCreateConfig();
config.setChannelNotice("这是频道公告"); //最大长度500字符，可配置
HashMap<String, String> channelAttributes = new HashMap<>();
channelAttributes.put("type", "announcement");
config.setChannelAttributes(channelAttributes);

zim.createCommunityChannel(channelInfo, config, new ZIMCommunityChannelCreatedCallback() {
    @Override
    public void onCommunityChannelCreated(ZIMCommunityChannelFullInfo channelFullInfo, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 创建成功，channelFullInfo 包含频道完整信息
            // 通过 channelFullInfo.conversationID 可获取用于收发消息的会话 ID
        }
    }
});

import im.zego.zim.ZIM;
import im.zego.zim.callback.ZIMCommunityChannelCreatedCallback;
import im.zego.zim.entity.ZIMCommunityChannelCreateConfig;
import im.zego.zim.entity.ZIMCommunityChannelFullInfo;
import im.zego.zim.entity.ZIMCommunityChannelInfo;
import im.zego.zim.entity.ZIMError;
import im.zego.zim.enums.ZIMErrorCode;

ZIMCommunityChannelInfo channelInfo = new ZIMCommunityChannelInfo();
channelInfo.setChannelID("channel_001");    // 频道 ID，可自定义
channelInfo.setChannelName("公告频道"); //最大长度300字符，可配置
channelInfo.setChannelAvatarUrl("https://example.com/channel_avatar.png"); //最大长度100字符，可配置
channelInfo.setCommunityID(communityID);    // 所属社群 ID

ZIMCommunityChannelCreateConfig config = new ZIMCommunityChannelCreateConfig();
config.setChannelNotice("这是频道公告"); //最大长度500字符，可配置
HashMap<String, String> channelAttributes = new HashMap<>();
channelAttributes.put("type", "announcement");
config.setChannelAttributes(channelAttributes);

zim.createCommunityChannel(channelInfo, config, new ZIMCommunityChannelCreatedCallback() {
    @Override
    public void onCommunityChannelCreated(ZIMCommunityChannelFullInfo channelFullInfo, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 创建成功，channelFullInfo 包含频道完整信息
            // 通过 channelFullInfo.conversationID 可获取用于收发消息的会话 ID
        }
    }
});

解散频道

调用 dismissCommunityChannel 接口解散指定社群中的频道，频道解散后所有成员将无法再访问该频道。

注意

类型为 GENERAL 的默认频道不可解散。

示例代码

zim.dismissCommunityChannel(channelID, communityID, new ZIMCommunityChannelDismissedCallback() {
    @Override
    public void onCommunityChannelDismissed(String communityID, String channelID, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 解散成功
        }
    }
});

zim.dismissCommunityChannel(channelID, communityID, new ZIMCommunityChannelDismissedCallback() {
    @Override
    public void onCommunityChannelDismissed(String communityID, String channelID, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // 解散成功
        }
    }
});

更新频道资料

社群所有者和管理员可以更新频道的名称、头像和公告。

更新频道名称

调用 updateCommunityChannelName 接口更新频道名称。频道名称最大长度300字符，可配置。

示例代码

zim.updateCommunityChannelName("新的频道名称", channelID, communityID,
    new ZIMCommunityChannelNameUpdatedCallback() {
        @Override
        public void onCommunityChannelNameUpdated(String communityID, String channelID, String channelName, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 更新成功
            }
        }
    });

zim.updateCommunityChannelName("新的频道名称", channelID, communityID,
    new ZIMCommunityChannelNameUpdatedCallback() {
        @Override
        public void onCommunityChannelNameUpdated(String communityID, String channelID, String channelName, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 更新成功
            }
        }
    });

更新频道头像

调用 updateCommunityChannelAvatarUrl 接口更新频道头像。频道头像最大长度100字符，可配置。

示例代码

zim.updateCommunityChannelAvatarUrl("https://example.com/new_channel_avatar.png",
    channelID, communityID,
    new ZIMCommunityChannelAvatarUrlUpdatedCallback() {
        @Override
        public void onCommunityChannelAvatarUrlUpdated(String communityID, String channelID, String channelAvatarUrl, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 更新成功
            }
        }
    });

zim.updateCommunityChannelAvatarUrl("https://example.com/new_channel_avatar.png",
    channelID, communityID,
    new ZIMCommunityChannelAvatarUrlUpdatedCallback() {
        @Override
        public void onCommunityChannelAvatarUrlUpdated(String communityID, String channelID, String channelAvatarUrl, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 更新成功
            }
        }
    });

更新频道公告

调用 updateCommunityChannelNotice 接口更新频道公告内容。频道公告最大长度500字符，可配置。

示例代码

zim.updateCommunityChannelNotice("新的频道公告内容", channelID, communityID,
    new ZIMCommunityChannelNoticeUpdatedCallback() {
        @Override
        public void onCommunityChannelNoticeUpdated(String communityID, String channelID, String channelNotice, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 更新成功
            }
        }
    });

zim.updateCommunityChannelNotice("新的频道公告内容", channelID, communityID,
    new ZIMCommunityChannelNoticeUpdatedCallback() {
        @Override
        public void onCommunityChannelNoticeUpdated(String communityID, String channelID, String channelNotice, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 更新成功
            }
        }
    });

设置频道属性

频道属性以键值对形式存储，可用于扩展频道的自定义信息。

设置属性

调用 setCommunityChannelAttributes 接口，批量设置频道自定义属性。操作失败的键名将通过 errorKeys 返回。

示例代码

HashMap<String, String> channelAttributes = new HashMap<>();
channelAttributes.put("key1", "value1");
channelAttributes.put("key2", "value2");

zim.setCommunityChannelAttributes(channelAttributes, channelID, communityID,
    new ZIMCommunityChannelAttributesOperatedCallback() {
        @Override
        public void onCommunityChannelAttributesOperated(String communityID, String channelID, ArrayList<String> errorKeys, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 设置成功
            }
        }
    });

HashMap<String, String> channelAttributes = new HashMap<>();
channelAttributes.put("key1", "value1");
channelAttributes.put("key2", "value2");

zim.setCommunityChannelAttributes(channelAttributes, channelID, communityID,
    new ZIMCommunityChannelAttributesOperatedCallback() {
        @Override
        public void onCommunityChannelAttributesOperated(String communityID, String channelID, ArrayList<String> errorKeys, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 设置成功
            }
        }
    });

删除属性

调用 deleteCommunityChannelAttributes 接口，按键名批量删除频道属性。

示例代码

ArrayList<String> keys = new ArrayList<>();
keys.add("key1");
keys.add("key2");

zim.deleteCommunityChannelAttributes(keys, channelID, communityID,
    new ZIMCommunityChannelAttributesOperatedCallback() {
        @Override
        public void onCommunityChannelAttributesOperated(String communityID, String channelID, ArrayList<String> errorKeys, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 删除成功
            }
        }
    });

ArrayList<String> keys = new ArrayList<>();
keys.add("key1");
keys.add("key2");

zim.deleteCommunityChannelAttributes(keys, channelID, communityID,
    new ZIMCommunityChannelAttributesOperatedCallback() {
        @Override
        public void onCommunityChannelAttributesOperated(String communityID, String channelID, ArrayList<String> errorKeys, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 删除成功
            }
        }
    });

查询频道信息

调用 queryCommunityChannelsInfo 接口，批量查询指定频道的完整信息，包括频道名称、头像、公告、禁言状态等。查询失败的频道 ID 将通过 errorChannelIDs 返回。

示例代码

ArrayList<String> channelIDs = new ArrayList<>();
channelIDs.add("channel_001");
channelIDs.add("channel_002");

zim.queryCommunityChannelsInfo(channelIDs, communityID,
    new ZIMCommunityChannelsInfoQueriedCallback() {
        @Override
        public void onCommunityChannelsInfoQueried(String communityID, ArrayList<ZIMCommunityChannelFullInfo> channelInfos, ArrayList<String> errorChannelIDs, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // channelInfos 包含各频道的完整信息
            }
        }
    });

ArrayList<String> channelIDs = new ArrayList<>();
channelIDs.add("channel_001");
channelIDs.add("channel_002");

zim.queryCommunityChannelsInfo(channelIDs, communityID,
    new ZIMCommunityChannelsInfoQueriedCallback() {
        @Override
        public void onCommunityChannelsInfoQueried(String communityID, ArrayList<ZIMCommunityChannelFullInfo> channelInfos, ArrayList<String> errorChannelIDs, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // channelInfos 包含各频道的完整信息
            }
        }
    });

查询频道列表

调用 queryCommunityChannelList 接口，分页拉取指定社群中的所有频道列表。返回的频道对象 ZIMCommunityChannel 中的 conversationID 字段，即是后续收发消息时所需的会话 ID。

分页规则与查询社群列表一致：首次将 config.nextFlag 设为 0，后续将返回的 nextFlag 传入下次请求，直到返回 0 为止。count 取值范围 1-100，推荐值 20。

示例代码

ZIMCommunityChannelListQueryConfig config = new ZIMCommunityChannelListQueryConfig();
config.setNextFlag(0);

zim.queryCommunityChannelList(communityID, 100, config,
    new ZIMCommunityChannelListQueriedCallback() {
        @Override
        public void onCommunityChannelListQueried(String communityID, ArrayList<ZIMCommunityChannel> channelList, long nextFlag, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                for (ZIMCommunityChannel channel : channelList) {
                    // channel.getBaseInfo().getChannelID()：频道 ID
                    // channel.getBaseInfo().getChannelName()：频道名称
                    // channel.getConversationID()：用于收发消息的会话 ID
                }
            }
        }
    });

ZIMCommunityChannelListQueryConfig config = new ZIMCommunityChannelListQueryConfig();
config.setNextFlag(0);

zim.queryCommunityChannelList(communityID, 100, config,
    new ZIMCommunityChannelListQueriedCallback() {
        @Override
        public void onCommunityChannelListQueried(String communityID, ArrayList<ZIMCommunityChannel> channelList, long nextFlag, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                for (ZIMCommunityChannel channel : channelList) {
                    // channel.getBaseInfo().getChannelID()：频道 ID
                    // channel.getBaseInfo().getChannelName()：频道名称
                    // channel.getConversationID()：用于收发消息的会话 ID
                }
            }
        }
    });

设置频道禁言

调用 muteCommunityChannels 接口，批量设置指定频道的禁言状态。禁言配置通过 ZIMCommunityChannelMuteConfig 传入。

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

配置字段	说明
`mode`	禁言范围。枚举值对照：`NONE`(0) = 不禁言、`NORMAL`(1) = 禁言普通成员、`ALL`(2) = 全员禁言、`CUSTOM`(3) = 自定义角色范围
`duration`	禁言时长（秒），取值范围 1-2592001（约 30 天），或 `-1` 表示永久禁言
`roles`	当 `mode` 为 `CUSTOM` 时，指定被禁言的角色列表

操作失败的频道 ID 将通过 errorChannelIDs 返回。详细操作请参考社群禁言。

示例代码

ArrayList<String> channelIDs = new ArrayList<>();
channelIDs.add("channel_001");
channelIDs.add("channel_002");

ZIMCommunityChannelMuteConfig config = new ZIMCommunityChannelMuteConfig();
config.setDuration(3600);  // 禁言 1 小时；-1 为永久禁言
config.setMode(ZIMCommunityChannelMuteMode.ALL);  // 禁言所有人

// isMute = true 为禁言，false 为解除禁言
zim.muteCommunityChannels(true, channelIDs, communityID, config,
    new ZIMCommunityChannelsMutedCallback() {
        @Override
        public void onCommunityChannelsMuted(String communityID, boolean isMute, ArrayList<String> errorChannelIDs, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 禁言设置成功
            }
        }
    });

ArrayList<String> channelIDs = new ArrayList<>();
channelIDs.add("channel_001");
channelIDs.add("channel_002");

ZIMCommunityChannelMuteConfig config = new ZIMCommunityChannelMuteConfig();
config.setDuration(3600);  // 禁言 1 小时；-1 为永久禁言
config.setMode(ZIMCommunityChannelMuteMode.ALL);  // 禁言所有人

// isMute = true 为禁言，false 为解除禁言
zim.muteCommunityChannels(true, channelIDs, communityID, config,
    new ZIMCommunityChannelsMutedCallback() {
        @Override
        public void onCommunityChannelsMuted(String communityID, boolean isMute, ArrayList<String> errorChannelIDs, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // 禁言设置成功
            }
        }
    });

监听频道变更

频道列表变更

当社群中频道被创建或解散，导致频道列表发生变化时，SDK 会触发 onCommunityChannelListChanged 回调。changeInfoList 包含各变更频道的变更类型及频道信息。

示例代码

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onCommunityChannelListChanged(ZIM zim, ZIMCommunityChannelListChangedEventResult result) {
        String communityID = result.getCommunityID();
        for (ZIMCommunityChannelChangeInfo changeInfo : result.getChangeInfoList()) {
            // changeInfo.action：变更类型（创建 / 解散）
            // changeInfo.channel：变更的频道信息
        }
    }
});

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onCommunityChannelListChanged(ZIM zim, ZIMCommunityChannelListChangedEventResult result) {
        String communityID = result.getCommunityID();
        for (ZIMCommunityChannelChangeInfo changeInfo : result.getChangeInfoList()) {
            // changeInfo.action：变更类型（创建 / 解散）
            // changeInfo.channel：变更的频道信息
        }
    }
});

频道信息更新

当频道资料（名称、头像、公告、属性、禁言状态等）发生变化时，SDK 会触发 onCommunityChannelInfoUpdated 回调。updateInfoList 包含变更后的频道完整信息。

示例代码

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onCommunityChannelInfoUpdated(ZIM zim, ZIMCommunityChannelInfoUpdatedEventResult result) {
        String communityID = result.getCommunityID();
        for (ZIMCommunityChannelFullInfoUpdateInfo updateInfo : result.getUpdateInfoList()) {
            // updateInfo.channelInfo：更新后的频道完整信息
        }
    }
});

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onCommunityChannelInfoUpdated(ZIM zim, ZIMCommunityChannelInfoUpdatedEventResult result) {
        String communityID = result.getCommunityID();
        for (ZIMCommunityChannelFullInfoUpdateInfo updateInfo : result.getUpdateInfoList()) {
            // updateInfo.channelInfo：更新后的频道完整信息
        }
    }
});

频道管理

功能简介

前提条件

频道类型说明

创建频道

解散频道

更新频道资料

更新频道名称

更新频道头像

更新频道公告

设置频道属性

设置属性

删除属性

查询频道信息

查询频道列表

设置频道禁言

监听频道变更

频道列表变更

频道信息更新

相关参考