A Channel is the basic carrier of chat interactions within a Community, functioning similarly to a traditional group. Each Community can contain multiple Channels. ZIM SDK provides comprehensive Channel management capabilities, supporting the following features:
Create/dismiss Channels
Update Channel name, avatar, and notice
Set/delete Channel custom attributes
Query Channel information and list
Set Channel mute status
Listen for Channel list changes and information updates
Community features require ZIM SDK 3.0.0 or later.
Community is a premium feature. Please contact ZEGOCLOUD Technical Support for activation before use.
The Token generation method for Community features is the same as for other ZIM features, with no additional permission declarations required.
Channel Type Description
Type
Description
Join Method
Visibility
GENERAL
Default Channel, automatically created when a Community is created. Community-level Tips and notifications are sent in this Channel
Auto-join
Visible to all members
PUBLIC
Public Channel, needs to be created after the Community is created
Auto-join
Visible to all members
Note
GENERAL and PUBLIC have identical functionality. The only difference is the creation timing: GENERAL is automatically created when the Community is created, while PUBLIC must be manually created after the Community is established.
Only the Community owner and admins have permission to create Channels.
When a Community is created, the system automatically creates a default Channel of type GENERAL. Developers can create additional public Channels (PUBLIC) on top of this.
channelID supports custom definition. Only numbers, English characters, and the following special characters are supported: ! # $ % & ( ) + - : ; < = . > ? @ [ ] ^ _ { } | ~, but it cannot start with #. If left blank, the ZIM server will create a Channel with a channelID starting with #C.
After successful creation, you are automatically joined to the Channel without needing to call the join API.
Example code
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"); // Channel ID, customizable
channelInfo.setChannelName("Announcements"); // Max length 300 characters, configurable
channelInfo.setChannelAvatarUrl("https://example.com/channel_avatar.png"); // Max length 100 characters, configurable
channelInfo.setCommunityID(communityID); // Parent Community ID
ZIMCommunityChannelCreateConfig config = new ZIMCommunityChannelCreateConfig();
config.setChannelNotice("This is the Channel notice"); // Max length 500 characters, configurable
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) {
// Created successfully; channelFullInfo contains complete Channel information
// channelFullInfo.conversationID can be used to get the conversation ID for sending and receiving messages
}
}
});
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"); // Channel ID, customizable
channelInfo.setChannelName("Announcements"); // Max length 300 characters, configurable
channelInfo.setChannelAvatarUrl("https://example.com/channel_avatar.png"); // Max length 100 characters, configurable
channelInfo.setCommunityID(communityID); // Parent Community ID
ZIMCommunityChannelCreateConfig config = new ZIMCommunityChannelCreateConfig();
config.setChannelNotice("This is the Channel notice"); // Max length 500 characters, configurable
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) {
// Created successfully; channelFullInfo contains complete Channel information
// channelFullInfo.conversationID can be used to get the conversation ID for sending and receiving messages
}
}
});
ZIMCommunityChannelInfo channelInfo = ZIMCommunityChannelInfo()
..channelID = 'channel_001'
..channelName = 'Announcements' // Max length 300 characters, configurable
..channelAvatarUrl = 'https://example.com/channel_avatar.png' // Max length 100 characters, configurable
..communityID = communityID;
ZIMCommunityChannelCreateConfig config = ZIMCommunityChannelCreateConfig()
..channelNotice = 'This is the Channel notice' // Max length 500 characters, configurable
..channelAttributes = {'type': 'announcement'};
try {
ZIMCommunityChannelCreatedResult result =
await ZIM.getInstance()!.createCommunityChannel(channelInfo, config);
// result.channelFullInfo contains complete Channel information
} on PlatformException catch (onError) {
// Creation failed
}
ZIMCommunityChannelInfo channelInfo = ZIMCommunityChannelInfo()
..channelID = 'channel_001'
..channelName = 'Announcements' // Max length 300 characters, configurable
..channelAvatarUrl = 'https://example.com/channel_avatar.png' // Max length 100 characters, configurable
..communityID = communityID;
ZIMCommunityChannelCreateConfig config = ZIMCommunityChannelCreateConfig()
..channelNotice = 'This is the Channel notice' // Max length 500 characters, configurable
..channelAttributes = {'type': 'announcement'};
try {
ZIMCommunityChannelCreatedResult result =
await ZIM.getInstance()!.createCommunityChannel(channelInfo, config);
// result.channelFullInfo contains complete Channel information
} on PlatformException catch (onError) {
// Creation failed
}
Dismiss a Channel
Call the dismissCommunityChannelByChannelID API to dismiss a Channel in the specified Community. After dismissal, all members will no longer be able to access the Channel.
Warning
The default Channel of type GENERAL cannot be dismissed.
Example code
zim.dismissCommunityChannel(channelID, communityID, new ZIMCommunityChannelDismissedCallback() {
@Override
public void onCommunityChannelDismissed(String communityID, String channelID, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// Dismissed successfully
}
}
});
zim.dismissCommunityChannel(channelID, communityID, new ZIMCommunityChannelDismissedCallback() {
@Override
public void onCommunityChannelDismissed(String communityID, String channelID, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
// Dismissed successfully
}
}
});
Call the queryCommunityChannelsInfoByChannelIDs API to batch query the complete information of specified Channels, including name, avatar, notice, mute status, etc. Failed Channel IDs will be returned through errorChannelIDs.
Example code
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 contains complete information for each Channel
}
}
});
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 contains complete information for each Channel
}
}
});
const channelIDs = ['channel_001', 'channel_002'];
zim.queryCommunityChannelsInfo(channelIDs, communityID)
.then((result: ZIMCommunityChannelsInfoQueriedResult) => {
// result.channelInfos contains complete information for each Channel
})
.catch((err: ZIMError) => {
// Query failed
});
const channelIDs = ['channel_001', 'channel_002'];
zim.queryCommunityChannelsInfo(channelIDs, communityID)
.then((result: ZIMCommunityChannelsInfoQueriedResult) => {
// result.channelInfos contains complete information for each Channel
})
.catch((err: ZIMError) => {
// Query failed
});
Example code
List<String> channelIDs = ['channel_001', 'channel_002'];
try {
ZIMCommunityChannelsInfoQueriedResult result =
await ZIM.getInstance()!.queryCommunityChannelsInfo(channelIDs, communityID);
// result.channelInfos contains complete information for each Channel
} on PlatformException catch (onError) {
// Query failed
}
List<String> channelIDs = ['channel_001', 'channel_002'];
try {
ZIMCommunityChannelsInfoQueriedResult result =
await ZIM.getInstance()!.queryCommunityChannelsInfo(channelIDs, communityID);
// result.channelInfos contains complete information for each Channel
} on PlatformException catch (onError) {
// Query failed
}
Query Channel List
Call the queryCommunityChannelListByCommunityID API to retrieve all Channel lists in the specified Community in pages. The conversationID field in the returned ZIMCommunityChannel object is the conversation ID needed for subsequent message sending and receiving.
Pagination rules are the same as querying the Community list: for the first query, set config.nextFlag to 0, then pass the returned nextFlag to the next request until it returns 0. The count range is 1-100, with a recommended value of 20.
Example code
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(): Channel ID
// channel.getBaseInfo().getChannelName(): Channel name
// channel.getConversationID(): Conversation ID for sending and receiving messages
}
}
}
});
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(): Channel ID
// channel.getBaseInfo().getChannelName(): Channel name
// channel.getConversationID(): Conversation ID for sending and receiving messages
}
}
}
});
Example code
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) {
// Queried successfully; channelList is the Channel list
}
}];
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) {
// Queried successfully; channelList is the Channel list
}
}];
When a Channel is created or dismissed in a Community, causing the Channel list to change, the SDK will trigger the communityChannelListChangedWithResult callback. changeInfoList contains the change type and Channel information for each changed Channel.
Example code
zim.setEventHandler(new ZIMEventHandler() {
@Override
public void onCommunityChannelListChanged(ZIM zim, ZIMCommunityChannelListChangedEventResult result) {
String communityID = result.getCommunityID();
for (ZIMCommunityChannelChangeInfo changeInfo : result.getChangeInfoList()) {
// changeInfo.action: change type (create/dismiss)
// changeInfo.channel: changed Channel information
}
}
});
zim.setEventHandler(new ZIMEventHandler() {
@Override
public void onCommunityChannelListChanged(ZIM zim, ZIMCommunityChannelListChangedEventResult result) {
String communityID = result.getCommunityID();
for (ZIMCommunityChannelChangeInfo changeInfo : result.getChangeInfoList()) {
// changeInfo.action: change type (create/dismiss)
// changeInfo.channel: changed Channel information
}
}
});
Example code
- (void)zim:(ZIM *)zim communityChannelListChangedWithResult:(ZIMCommunityChannelListChangedEventResult *)result {
NSString *communityID = result.communityID;
for (ZIMCommunityChannelChangeInfo *changeInfo in result.changeInfoList) {
// changeInfo.action: change type
// changeInfo.channel: changed Channel information
}
}
- (void)zim:(ZIM *)zim communityChannelListChangedWithResult:(ZIMCommunityChannelListChangedEventResult *)result {
NSString *communityID = result.communityID;
for (ZIMCommunityChannelChangeInfo *changeInfo in result.changeInfoList) {
// changeInfo.action: change type
// changeInfo.channel: changed Channel information
}
}
Example code
void onCommunityChannelListChanged(zim::ZIM *zim,
const zim::ZIMCommunityChannelListChangedEventResult &result) override {
std::string communityID = result.communityID;
for (const auto &changeInfo : result.changeInfoList) {
// changeInfo contains Channel change information
}
}
void onCommunityChannelListChanged(zim::ZIM *zim,
const zim::ZIMCommunityChannelListChangedEventResult &result) override {
std::string communityID = result.communityID;
for (const auto &changeInfo : result.changeInfoList) {
// changeInfo contains Channel change information
}
}
Example code
zim.on('communityChannelListChanged', (zim, result) => {
const communityID = result.communityID;
for (const changeInfo of result.changeInfoList) {
// changeInfo.action: change type
// changeInfo.channel: changed Channel information
}
});
zim.on('communityChannelListChanged', (zim, result) => {
const communityID = result.communityID;
for (const changeInfo of result.changeInfoList) {
// changeInfo.action: change type
// changeInfo.channel: changed Channel information
}
});
Example code
ZIMEventHandler.onCommunityChannelListChanged =
(ZIM zim, ZIMCommunityChannelListChangedEventResult result) {
for (final changeInfo in result.changeInfoList) {
// changeInfo contains Channel change information
}
};
ZIMEventHandler.onCommunityChannelListChanged =
(ZIM zim, ZIMCommunityChannelListChangedEventResult result) {
for (final changeInfo in result.changeInfoList) {
// changeInfo contains Channel change information
}
};
Channel Information Updates
When Channel profile (name, avatar, notice, attributes, mute status, etc.) changes, the SDK will trigger the communityChannelInfoUpdatedWithResult callback. updateInfoList contains the updated complete Channel information.
Example code
zim.setEventHandler(new ZIMEventHandler() {
@Override
public void onCommunityChannelInfoUpdated(ZIM zim, ZIMCommunityChannelInfoUpdatedEventResult result) {
String communityID = result.getCommunityID();
for (ZIMCommunityChannelFullInfoUpdateInfo updateInfo : result.getUpdateInfoList()) {
// updateInfo.channelInfo: updated complete Channel information
}
}
});
zim.setEventHandler(new ZIMEventHandler() {
@Override
public void onCommunityChannelInfoUpdated(ZIM zim, ZIMCommunityChannelInfoUpdatedEventResult result) {
String communityID = result.getCommunityID();
for (ZIMCommunityChannelFullInfoUpdateInfo updateInfo : result.getUpdateInfoList()) {
// updateInfo.channelInfo: updated complete Channel information
}
}
});
Example code
- (void)zim:(ZIM *)zim communityChannelInfoUpdatedWithResult:(ZIMCommunityChannelInfoUpdatedEventResult *)result {
NSString *communityID = result.communityID;
for (ZIMCommunityChannelFullInfoUpdateInfo *updateInfo in result.updateInfoList) {
// updateInfo.channelInfo: updated complete Channel information
}
}
- (void)zim:(ZIM *)zim communityChannelInfoUpdatedWithResult:(ZIMCommunityChannelInfoUpdatedEventResult *)result {
NSString *communityID = result.communityID;
for (ZIMCommunityChannelFullInfoUpdateInfo *updateInfo in result.updateInfoList) {
// updateInfo.channelInfo: updated complete Channel information
}
}
Example code
void onCommunityChannelInfoUpdated(zim::ZIM *zim,
const zim::ZIMCommunityChannelInfoUpdatedEventResult &result) override {
std::string communityID = result.communityID;
for (const auto &updateInfo : result.updateInfoList) {
// updateInfo contains updated Channel information
}
}
void onCommunityChannelInfoUpdated(zim::ZIM *zim,
const zim::ZIMCommunityChannelInfoUpdatedEventResult &result) override {
std::string communityID = result.communityID;
for (const auto &updateInfo : result.updateInfoList) {
// updateInfo contains updated Channel information
}
}
Example code
zim.on('communityChannelInfoUpdated', (zim, result) => {
const communityID = result.communityID;
for (const updateInfo of result.updateInfoList) {
// updateInfo.channelInfo: updated complete Channel information
}
});
zim.on('communityChannelInfoUpdated', (zim, result) => {
const communityID = result.communityID;
for (const updateInfo of result.updateInfoList) {
// updateInfo.channelInfo: updated complete Channel information
}
});
Example code
ZIMEventHandler.onCommunityChannelInfoUpdated =
(ZIM zim, ZIMCommunityChannelInfoUpdatedEventResult result) {
for (final updateInfo in result.updateInfoList) {
// updateInfo contains updated Channel information
}
};
ZIMEventHandler.onCommunityChannelInfoUpdated =
(ZIM zim, ZIMCommunityChannelInfoUpdatedEventResult result) {
for (final updateInfo in result.updateInfoList) {
// updateInfo contains updated Channel information
}
};
