Community Management

2026-06-24

Feature Overview

The Community product typically features a three-tier social organizational structure of "Community-Channel-Thread" (corresponding to Discord's Server-Channel-Thread). For a more detailed introduction, please refer to Overview.

ZIM SDK provides comprehensive Community management capabilities, supporting the following features:

Create/dismiss a Community
Join/leave a Community
Query the list of joined Communities and Community information
Update Community name, avatar, and notice
Set/delete Community custom attributes
Set Community message notification status
Listen for Community list changes and information updates

Integration Roadmap

The recommended order for integrating Community features is as follows:

Create/Join a Community — Community Management
Manage Community Members — Community Member Management
Create/Manage Channels — Channel Management
Send and Receive Channel Messages — Channel Message Management
Manage Channel Conversations — Channel Conversation Management

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.

Note

Community management operations are currently only supported through the client SDK and are not available via server-side APIs. Community event notifications are currently only received through client SDK callbacks and are not available via server-side callbacks.

Create a Community

After logging in to the ZIM SDK, call the createCommunity API, passing in the Community basic information ZIMCommunityInfo and creation configuration ZIMCommunityCreateConfig to create a Community. The creator automatically becomes the Community owner.

The creation result is returned through ZIMCommunityCreatedResult. Upon success, you can obtain the complete Community information.

Warning

communityID 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 Community with a communityID starting with #B.
After successful creation, you are automatically joined to the Community without needing to call the join API. A single user can join up to 100 Communities (default), expandable to 500. There is no limit on the number of Communities under the same AppID. The maximum number of Channels under the same Community is 100 (default), expandable to 1,000.

Example code

const communityInfo: ZIMCommunityInfo = {
    communityID: 'community_001', // Customizable; leave blank for server auto-generation with #B prefix 
    communityName: 'My Community', // Max length 300 characters, configurable
    communityAvatarUrl: 'https://example.com/avatar.png', // Max length 100 characters, configurable
};
const config: ZIMCommunityCreateConfig = {
    communityNotice: 'Welcome!', // Max length 500 characters, configurable 
    communityAttributes: { key1: 'value1' }, // Default max 10 attribute pairs; key max 16 characters, value max 1024 characters
};

zim.createCommunity(communityInfo, config)
    .then((result: ZIMCommunityCreatedResult) => {
        // Created successfully; result.communityInfo contains complete Community information
    })
    .catch((err: ZIMError) => {
        // Creation failed
    });

const communityInfo: ZIMCommunityInfo = {
    communityID: 'community_001', // Customizable; leave blank for server auto-generation with #B prefix 
    communityName: 'My Community', // Max length 300 characters, configurable
    communityAvatarUrl: 'https://example.com/avatar.png', // Max length 100 characters, configurable
};
const config: ZIMCommunityCreateConfig = {
    communityNotice: 'Welcome!', // Max length 500 characters, configurable 
    communityAttributes: { key1: 'value1' }, // Default max 10 attribute pairs; key max 16 characters, value max 1024 characters
};

zim.createCommunity(communityInfo, config)
    .then((result: ZIMCommunityCreatedResult) => {
        // Created successfully; result.communityInfo contains complete Community information
    })
    .catch((err: ZIMError) => {
        // Creation failed
    });

Common Error Codes

Error Code	Description	Recommended Action
6001003	Community already exists	Check if a Community with the same communityID has already been created
6001007	Community permission error	Confirm whether the current user has creation permission
6001008	Community attribute count exceeded	The default maximum is 10 attribute pairs

ZIMCommunityInfo Field Description

Field	Type	Description
communityID	String	Community ID, customizable or auto-generated by the server
communityName	String	Community name, max length 300 characters, configurable
communityAvatarUrl	String	Community avatar URL, max length 100 characters, configurable

ZIMCommunityCreateConfig Parameter Description

Parameter	Type	Description
communityNotice	String	Community notice, max length 500 characters, configurable
communityAttributes	Map<String, String>	Community custom attributes, default max 10 pairs; key max 16 characters, value max 1024 characters

ZIMCommunityFullInfo Core Fields

Field	Type	Description
baseInfo	ZIMCommunityInfo	Community basic information (ID, name, avatar, etc.)
communityNotice	String	Community notice
communityAttributes	HashMap<String, String>	Community custom attributes
createTime	long	Community creation time
creatorUserID	String	Creator User ID
currentMemberCount	int	Current Community member count
notificationStatus	ZIMCommunityMessageNotificationStatus	Message notification status

Dismiss a Community

The Community owner can call the dismissCommunity API to dismiss a Community. After dismissal, all members will no longer be able to access the Community.

Warning

Only the Community owner can call this API. Admins and regular members do not have permission to dismiss the Community.
When a Community is dismissed, all its Channels will also be automatically dismissed.

Example code

zim.dismissCommunity(communityID)
    .then((result: ZIMCommunityDismissedResult) => {
        // Dismissed successfully
    })
    .catch((err: ZIMError) => {
        // Dismissal failed
    });

zim.dismissCommunity(communityID)
    .then((result: ZIMCommunityDismissedResult) => {
        // Dismissed successfully
    })
    .catch((err: ZIMError) => {
        // Dismissal failed
    });

Join a Community

After logging in to the ZIM SDK, call the joinCommunity API and pass in the target Community ID to join the Community. Upon successful join, you can obtain the complete information of that Community. After joining a Community, you will automatically join its default Channel and all public Channels. A single user can join up to 100 Communities (default), expandable to 500.

Example code

zim.joinCommunity(communityID)
    .then((result: ZIMCommunityJoinedResult) => {
        // Joined successfully; result.communityInfo contains complete Community information
    })
    .catch((err: ZIMError) => {
        // Join failed
    });

zim.joinCommunity(communityID)
    .then((result: ZIMCommunityJoinedResult) => {
        // Joined successfully; result.communityInfo contains complete Community information
    })
    .catch((err: ZIMError) => {
        // Join failed
    });

Leave a Community

Members who have joined a Community can call the leaveCommunity API to actively leave the Community.

Warning

The Community owner cannot call this API to leave the Community. The owner must first transfer ownership to another member or dismiss the Community directly.
Leaving a Community will also leave all its Channels.

Example code

zim.leaveCommunity(communityID)
    .then((result: ZIMCommunityLeftResult) => {
        // Left successfully
    })
    .catch((err: ZIMError) => {
        // Leaving failed
    });

zim.leaveCommunity(communityID)
    .then((result: ZIMCommunityLeftResult) => {
        // Left successfully
    })
    .catch((err: ZIMError) => {
        // Leaving failed
    });

Query Community List

Call the queryCommunityList API to retrieve the list of Communities the current user has joined in pages.

Pagination rules:

For the first query, set config.nextFlag to 0.
After receiving the callback, if the returned nextFlag is not 0, use it as the config.nextFlag for the next request to continue fetching.
When the returned nextFlag is 0, it indicates no more data is available.
The maximum count per page query is 100.

Example code

const config: ZIMCommunityListQueryConfig = { nextFlag: 0 };

zim.queryCommunityList(100, config)
    .then((result: ZIMCommunityListQueriedResult) => {
        const { communityList, nextFlag } = result;
        // When nextFlag != 0, continue paginated fetching
    })
    .catch((err: ZIMError) => {
        // Query failed
    });

const config: ZIMCommunityListQueryConfig = { nextFlag: 0 };

zim.queryCommunityList(100, config)
    .then((result: ZIMCommunityListQueriedResult) => {
        const { communityList, nextFlag } = result;
        // When nextFlag != 0, continue paginated fetching
    })
    .catch((err: ZIMError) => {
        // Query failed
    });

Query Community Information

Call the queryCommunityInfo API to query the complete information of a specified Community, including name, avatar, notice, owner, etc.

Example code

zim.queryCommunityInfo(communityID)
    .then((result: ZIMCommunityInfoQueriedResult) => {
        // result.communityInfo contains complete Community information
    })
    .catch((err: ZIMError) => {
        // Query failed
    });

zim.queryCommunityInfo(communityID)
    .then((result: ZIMCommunityInfoQueriedResult) => {
        // result.communityInfo contains complete Community information
    })
    .catch((err: ZIMError) => {
        // Query failed
    });

Update Community Profile

Community owners and admins can update the Community's basic profile, including name, avatar, and notice.

Update Community Name

Call the updateCommunityName API to update the Community name. The maximum Community name length is 300 characters, configurable.

Example code

zim.updateCommunityName('New Community Name', communityID)
    .then((result: ZIMCommunityNameUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

zim.updateCommunityName('New Community Name', communityID)
    .then((result: ZIMCommunityNameUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

Update Community Avatar

Call the updateCommunityAvatarUrl API to update the Community avatar. The maximum Community avatar length is 100 characters, configurable.

Example code

zim.updateCommunityAvatarUrl('https://example.com/new_avatar.png', communityID)
    .then((result: ZIMCommunityAvatarUrlUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

zim.updateCommunityAvatarUrl('https://example.com/new_avatar.png', communityID)
    .then((result: ZIMCommunityAvatarUrlUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

Update Community Notice

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

Example code

zim.updateCommunityNotice('New Community Notice', communityID)
    .then((result: ZIMCommunityNoticeUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

zim.updateCommunityNotice('New Community Notice', communityID)
    .then((result: ZIMCommunityNoticeUpdatedResult) => {
        // Updated successfully
    })
    .catch((err: ZIMError) => {
        // Update failed
    });

Set Community Attributes

Community attributes are stored as key-value pairs and can be used to extend custom information about the Community, such as category tags and business fields. Community attributes have a default maximum of 10 pairs, with key max length of 16 characters and value max length of 1024 characters.

Set Attributes

Call the setCommunityAttributes API to batch-set Community custom attributes. Failed key names will be returned through the errorKeys list.

Example code

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

zim.setCommunityAttributes(attributes, communityID)
    .then((result: ZIMCommunityAttributesOperatedResult) => {
        // result.errorKeys lists the keys that failed the operation
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

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

zim.setCommunityAttributes(attributes, communityID)
    .then((result: ZIMCommunityAttributesOperatedResult) => {
        // result.errorKeys lists the keys that failed the operation
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

Delete Attributes

Call the deleteCommunityAttributes API to batch-delete Community attributes by key names.

Example code

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

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

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

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

Set Community Notification Status

Call the setCommunityNotificationStatus API to set the current user's message notification status for a specified Community. When set to Do Not Disturb, new messages from that Community will not trigger system push notifications, and the unread count will not be added to the total unread count. When a user enters a Community, the Community is in notification status by default. However, all Channels are in Do Not Disturb status by default. The Community total unread count is only calculated when the Community is in notification status, and its value is the sum of unread counts from all Channels in notification status.

Example code

// status: 1 = receive notifications, 2 = do not disturb
zim.setCommunityNotificationStatus(2, communityID)
    .then((result: ZIMCommunityNotificationStatusSetResult) => {
        // Set successfully
    })
    .catch((err: ZIMError) => {
        // Setting failed
    });

// status: 1 = receive notifications, 2 = do not disturb
zim.setCommunityNotificationStatus(2, communityID)
    .then((result: ZIMCommunityNotificationStatusSetResult) => {
        // Set successfully
    })
    .catch((err: ZIMError) => {
        // Setting failed
    });

Listen for Community Changes

Community List Changes

When the user's Community list UI may change due to events such as joining or leaving a Community, or updates to Community name, avatar, or unread count, the SDK will trigger the communityListChanged callback. The changeInfoList in the callback contains the change type (add, delete, update) and the corresponding Community information.

Example code

zim.on('communityListChanged', (zim, result) => {
    for (const changeInfo of result.changeInfoList) {
        // changeInfo.action: change type (add/delete/update)
        // changeInfo.community: changed Community information
    }
});

zim.on('communityListChanged', (zim, result) => {
    for (const changeInfo of result.changeInfoList) {
        // changeInfo.action: change type (add/delete/update)
        // changeInfo.community: changed Community information
    }
});

Community Information Updates

When Community profile (name, avatar, notice, attributes, etc.) changes, the SDK will trigger the communityInfoUpdated callback. The updateInfoList contains the updated complete Community information.

Example code

zim.on('communityInfoUpdated', (zim, result) => {
    for (const updateInfo of result.updateInfoList) {
        // updateInfo.communityInfo: updated complete Community information
    }
});

zim.on('communityInfoUpdated', (zim, result) => {
    for (const updateInfo of result.updateInfoList) {
        // updateInfo.communityInfo: updated complete Community information
    }
});

FAQ

Q: What SDK version is required for Community features? A: Community features require ZIM SDK 3.0.0 or later.

Q: Does Community management support server-side APIs? A: Community management operations are currently only supported through the client SDK and are not available via server-side APIs.

Q: Can the Community owner leave the Community? A: The Community owner cannot directly leave the Community. The owner must first transfer ownership to another member or dismiss the Community.

ZIM Error Codes

2026-06-24

Community Management

Feature Overview

Integration Roadmap

Prerequisites

Create a Community

ZIMCommunityInfo Field Description

ZIMCommunityCreateConfig Parameter Description

ZIMCommunityFullInfo Core Fields

Dismiss a Community

Join a Community

Leave a Community

Query Community List

Query Community Information

Update Community Profile

Update Community Name

Update Community Avatar

Update Community Notice

Set Community Attributes

Set Attributes

Delete Attributes

Set Community Notification Status

Listen for Community Changes

Community List Changes

Community Information Updates

FAQ

Related References