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

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.

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.

Example code

const 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,
};
const config: ZIMCommunityChannelCreateConfig = {
    channelNotice: 'This is the Channel notice', // Max length 500 characters, configurable
    channelAttributes: { type: 'announcement' },
};

zim.createCommunityChannel(channelInfo, config)
    .then((result: ZIMCommunityChannelCreatedResult) => {
        // result.channelFullInfo contains complete Channel information
    })
    .catch((err: ZIMError) => {
        // Creation failed
    });

const 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,
};
const config: ZIMCommunityChannelCreateConfig = {
    channelNotice: 'This is the Channel notice', // Max length 500 characters, configurable
    channelAttributes: { type: 'announcement' },
};

zim.createCommunityChannel(channelInfo, config)
    .then((result: ZIMCommunityChannelCreatedResult) => {
        // result.channelFullInfo contains complete Channel information
    })
    .catch((err: ZIMError) => {
        // Creation failed
    });

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.

Example code

zim.dismissCommunityChannel(channelID, communityID)
    .then((result: ZIMCommunityChannelDismissedResult) => {
        // Dismissed successfully
    })
    .catch((err: ZIMError) => {
        // Dismissal failed
    });

zim.dismissCommunityChannel(channelID, communityID)
    .then((result: ZIMCommunityChannelDismissedResult) => {
        // Dismissed successfully
    })
    .catch((err: ZIMError) => {
        // Dismissal failed
    });

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.

Example code

zim.updateCommunityChannelName('New Channel Name', channelID, communityID)
    .then((result: ZIMCommunityChannelNameUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

zim.updateCommunityChannelName('New Channel Name', channelID, communityID)
    .then((result: ZIMCommunityChannelNameUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

Update Channel Avatar

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

Example code

zim.updateCommunityChannelAvatarUrl('https://example.com/new_channel_avatar.png', channelID, communityID)
    .then((result: ZIMCommunityChannelAvatarUrlUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

zim.updateCommunityChannelAvatarUrl('https://example.com/new_channel_avatar.png', channelID, communityID)
    .then((result: ZIMCommunityChannelAvatarUrlUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

Update Channel Notice

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

Example code

zim.updateCommunityChannelNotice('New Channel Notice', channelID, communityID)
    .then((result: ZIMCommunityChannelNoticeUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

zim.updateCommunityChannelNotice('New Channel Notice', channelID, communityID)
    .then((result: ZIMCommunityChannelNoticeUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

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.

Example code

const channelAttributes: Record<string, string> = { key1: 'value1', key2: 'value2' };

zim.setCommunityChannelAttributes(channelAttributes, channelID, communityID)
    .then((result: ZIMCommunityChannelAttributesOperatedResult) => {
        // result.errorKeys lists the keys that failed the operation
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

const channelAttributes: Record<string, string> = { key1: 'value1', key2: 'value2' };

zim.setCommunityChannelAttributes(channelAttributes, channelID, communityID)
    .then((result: ZIMCommunityChannelAttributesOperatedResult) => {
        // result.errorKeys lists the keys that failed the operation
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

Delete Attributes

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

Example code

const keys = ['key1', 'key2'];

zim.deleteCommunityChannelAttributes(keys, channelID, communityID)
    .then((result: ZIMCommunityChannelAttributesOperatedResult) => {
        // Deleted successfully
    })
    .catch((err: ZIMError) => {
        // Deletion failed
    });

const keys = ['key1', 'key2'];

zim.deleteCommunityChannelAttributes(keys, channelID, communityID)
    .then((result: ZIMCommunityChannelAttributesOperatedResult) => {
        // Deleted successfully
    })
    .catch((err: ZIMError) => {
        // Deletion failed
    });

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.

Example code

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

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.

Example code

const config: ZIMCommunityChannelListQueryConfig = { nextFlag: 0 };

zim.queryCommunityChannelList(communityID, 100, config)
    .then((result: ZIMCommunityChannelListQueriedResult) => {
        const { channelList, nextFlag } = result;
        // channel.conversationID is used for sending and receiving messages
    })
    .catch((err: ZIMError) => {
        // Query failed
    });

const config: ZIMCommunityChannelListQueryConfig = { nextFlag: 0 };

zim.queryCommunityChannelList(communityID, 100, config)
    .then((result: ZIMCommunityChannelListQueriedResult) => {
        const { channelList, nextFlag } = result;
        // channel.conversationID is used for sending and receiving messages
    })
    .catch((err: ZIMError) => {
        // Query failed
    });

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 Field	Description
`mode`	Mute scope. Enum values: `NONE`(0) = no mute, `NORMAL`(1) = mute regular members, `ALL`(2) = mute all members, `CUSTOM`(3) = custom role scope
`duration`	Mute duration (seconds), range 1-2592001 (approximately 30 days), or `-1` for permanent mute
`roles`	When `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.

Example code

const channelIDs = ['channel_001', 'channel_002'];
const config: ZIMCommunityChannelMuteConfig = {
    duration: 3600,
    mode: 2, // 2 = ALL, mute all members
};

zim.muteCommunityChannels(true, channelIDs, communityID, config)
    .then((result: ZIMCommunityChannelsMutedResult) => {
        // result.errorChannelIDs lists the failed Channels
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

const channelIDs = ['channel_001', 'channel_002'];
const config: ZIMCommunityChannelMuteConfig = {
    duration: 3600,
    mode: 2, // 2 = ALL, mute all members
};

zim.muteCommunityChannels(true, channelIDs, communityID, config)
    .then((result: ZIMCommunityChannelsMutedResult) => {
        // result.errorChannelIDs lists the failed Channels
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

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 communityChannelListChanged callback. changeInfoList contains the change type and Channel information for each changed Channel.

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

Channel Information Updates

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

ZIM Error Codes

2026-06-24

Channel Management

Feature Overview

Prerequisites

Channel Type Description

Create a Channel

Dismiss a Channel

Update Channel Profile

Update Channel Name

Update Channel Avatar

Update Channel Notice

Set Channel Attributes

Set Attributes

Delete Attributes

Query Channel Information

Query Channel List

Mute Channels

Listen for Channel Changes

Channel List Changes

Channel Information Updates

Related References