logo文档中心
登录/注册控制台
文档
ZIM 客户端 API
ZPNs 客户端 API
ZIM Audio 客户端 API
服务端 API
即时通讯
macOS: Objective-C
产品简介
概述
计费说明
基本概念介绍
客户端 SDK
下载
发布日志
升级指南
错误码
快速开始
实现基本消息收发
连接至 ZEGO 文档 MCP 服务link
功能指引
用户
房间
群组
消息
会话
社群
缓存管理
内容审核
呼叫邀请
离线推送
最佳实践
迁移方案
常见问题link
当前页

频道管理

2026-05-22

功能简介

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

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

前提条件

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

频道类型说明

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

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

创建频道

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

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

ZIMCommunityChannelCreateConfig *config = [[ZIMCommunityChannelCreateConfig alloc] init];
config.channelNotice = @"这是频道公告"; //最大长度500字符，可配置
config.channelAttributes = @{@"type": @"announcement"};

[zim createCommunityChannel:channelInfo config:config callback:^(ZIMCommunityChannelFullInfo * _Nonnull channelFullInfo, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 创建成功
    }
}];

解散频道

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

注意
  • 类型为 GENERAL 的默认频道不可解散。
[zim dismissCommunityChannel:channelID communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull channelID, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 解散成功
    }
}];

更新频道资料

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

更新频道名称

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

[zim updateCommunityChannelName:@"新的频道名称" channelID:channelID communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull channelID, NSString * _Nonnull channelName, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 更新成功
    }
}];

更新频道头像

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

[zim updateCommunityChannelAvatarUrl:@"https://example.com/new_channel_avatar.png" channelID:channelID communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull channelID, NSString * _Nonnull channelAvatarUrl, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 更新成功
    }
}];

更新频道公告

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

[zim updateCommunityChannelNotice:@"新的频道公告内容" channelID:channelID communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull channelID, NSString * _Nonnull channelNotice, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 更新成功
    }
}];

设置频道属性

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

设置属性

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

NSDictionary<NSString *, NSString *> *channelAttributes = @{@"key1": @"value1", @"key2": @"value2"};

[zim setCommunityChannelAttributes:channelAttributes channelID:channelID communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull channelID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 设置成功
    }
}];

删除属性

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

NSArray<NSString *> *keys = @[@"key1", @"key2"];

[zim deleteCommunityChannelAttributes:keys channelID:channelID communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull channelID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 删除成功
    }
}];

查询频道信息

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

NSArray<NSString *> *channelIDs = @[@"channel_001", @"channel_002"];

[zim queryCommunityChannelsInfoByChannelIDs:channelIDs communityID:communityID callback:^(NSString * _Nonnull communityID, NSArray<ZIMCommunityChannelFullInfo *> * _Nonnull channelInfos, NSArray<NSString *> * _Nonnull errorChannelIDs, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 查询成功
    }
}];

查询频道列表

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

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

ZIMCommunityChannelListQueryConfig *config = [[ZIMCommunityChannelListQueryConfig alloc] init];
config.nextFlag = 0;

[zim queryCommunityChannelList:communityID count:100 config:config callback:^(NSString * _Nonnull communityID, NSArray<ZIMCommunityChannel *> * _Nonnull channelList, long long nextFlag, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 查询成功，channelList 为频道列表
    }
}];

设置频道禁言

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

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

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

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

NSArray<NSString *> *channelIDs = @[@"channel_001", @"channel_002"];

ZIMCommunityChannelMuteConfig *config = [[ZIMCommunityChannelMuteConfig alloc] init];
config.duration = 3600;
config.mode = ZIMCommunityChannelMuteModeAll;

[zim muteCommunityChannels:YES channelIDs:channelIDs communityID:communityID config:config callback:^(NSString * _Nonnull communityID, BOOL isMute, NSArray<NSString *> * _Nonnull errorChannelIDs, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // 禁言设置成功
    }
}];

监听频道变更

频道列表变更

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

- (void)zim:(ZIM *)zim communityChannelListChangedWithResult:(ZIMCommunityChannelListChangedEventResult *)result {
    NSString *communityID = result.communityID;
    for (ZIMCommunityChannelChangeInfo *changeInfo in result.changeInfoList) {
        // changeInfo.action：变更类型
        // changeInfo.channel：变更的频道信息
    }
}

频道信息更新

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

- (void)zim:(ZIM *)zim communityChannelInfoUpdatedWithResult:(ZIMCommunityChannelInfoUpdatedEventResult *)result {
    NSString *communityID = result.communityID;
    for (ZIMCommunityChannelFullInfoUpdateInfo *updateInfo in result.updateInfoList) {
        // updateInfo.channelInfo：更新后的频道完整信息
    }
}

相关参考

上一篇

社群成员管理

下一篇

频道消息管理

当前页

返回到顶部