In-app Chat
SDK Error Codes
On this page

Channel Management

2026-06-24

Feature Overview

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

Prerequisites

  • Please refer to Implement basic message sending and receiving to complete ZIM SDK acquisition, initialization, and user login.
  • Please refer to Authenticate with Token to implement user authentication and login.
  • 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

TypeDescriptionJoin MethodVisibility
GENERALDefault Channel, automatically created when a Community is created. Community-level Tips and notifications are sent in this ChannelAuto-joinVisible to all members
PUBLICPublic Channel, needs to be created after the Community is createdAuto-joinVisible 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.

Create a Channel

After joining a Community, call the createCommunityChannel API, passing in the Channel basic information ZIMCommunityChannelInfo and creation configuration ZIMCommunityChannelCreateConfig to create a Channel in the specified Community.

Note
  • 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.
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
        }
    }
});

Dismiss a Channel

Call the dismissCommunityChannel 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.
zim.dismissCommunityChannel(channelID, communityID, new ZIMCommunityChannelDismissedCallback() {
    @Override
    public void onCommunityChannelDismissed(String communityID, String channelID, ZIMError errorInfo) {
        if (errorInfo.code == ZIMErrorCode.SUCCESS) {
            // Dismissed successfully
        }
    }
});

Update Channel Profile

Community owners and admins can update the Channel's name, avatar, and notice.

Update Channel Name

Call the updateCommunityChannelName API to update the Channel name. The maximum Channel name length is 300 characters, configurable.

zim.updateCommunityChannelName("New Channel Name", channelID, communityID,
    new ZIMCommunityChannelNameUpdatedCallback() {
        @Override
        public void onCommunityChannelNameUpdated(String communityID, String channelID, String channelName, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // Updated successfully
            }
        }
    });

Update Channel Avatar

Call the updateCommunityChannelAvatarUrl API to update the Channel avatar. The maximum Channel avatar length is 100 characters, configurable.

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) {
                // Updated successfully
            }
        }
    });

Update Channel Notice

Call the updateCommunityChannelNotice API to update the Channel notice content. The maximum Channel notice length is 500 characters, configurable.

zim.updateCommunityChannelNotice("New Channel Notice", channelID, communityID,
    new ZIMCommunityChannelNoticeUpdatedCallback() {
        @Override
        public void onCommunityChannelNoticeUpdated(String communityID, String channelID, String channelNotice, ZIMError errorInfo) {
            if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                // Updated successfully
            }
        }
    });

Set Channel Attributes

Channel attributes are stored as key-value pairs and can be used to extend custom information about the Channel.

Set Attributes

Call the setCommunityChannelAttributes API to batch-set Channel custom attributes. Failed key names will be returned through 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) {
                // Set successfully
            }
        }
    });

Delete Attributes

Call the deleteCommunityChannelAttributes API to batch-delete Channel attributes by key names.

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) {
                // Deleted successfully
            }
        }
    });

Query Channel Information

Call the queryCommunityChannelsInfo 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.

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
            }
        }
    });

Query Channel List

Call the queryCommunityChannelList 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.

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
                }
            }
        }
    });

Mute Channels

Call the muteCommunityChannels API to batch set the mute status of specified Channels. Mute configuration is passed through ZIMCommunityChannelMuteConfig.

channelIDs and communityID are direct parameters of the API method, not config configuration fields.

Configuration FieldDescription
modeMute scope. Enum values: NONE(0) = no mute, NORMAL(1) = mute regular members, ALL(2) = mute all members, CUSTOM(3) = custom role scope
durationMute duration (seconds), range 1-2592001 (approximately 30 days), or -1 for permanent mute
rolesWhen mode is CUSTOM, specifies the list of roles to be muted

Failed Channel IDs will be returned through errorChannelIDs. For detailed operations, please refer to Community Mute.

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

ZIMCommunityChannelMuteConfig config = new ZIMCommunityChannelMuteConfig();
config.setDuration(3600);  // Mute for 1 hour; -1 for permanent mute
config.setMode(ZIMCommunityChannelMuteMode.ALL);  // Mute all members

// isMute = true to mute, false to unmute
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) {
                // Mute set successfully
            }
        }
    });

Listen for Channel Changes

Channel List Changes

When a Channel is created or dismissed in a Community, causing the Channel list to change, the SDK will trigger the onCommunityChannelListChanged callback. changeInfoList contains the change type and Channel information for each changed Channel.

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
        }
    }
});

Channel Information Updates

When Channel profile (name, avatar, notice, attributes, mute status, etc.) changes, the SDK will trigger the onCommunityChannelInfoUpdated callback. updateInfoList contains the 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
        }
    }
});

Previous

Community member management

Next

Channel message management