In-app Chat
SDK Error Codes
On this page

Community Management

2026-07-06

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:

  1. Create/Join a CommunityCommunity Management
  2. Manage Community MembersCommunity Member Management
  3. Create/Manage ChannelsChannel Management
  4. Send and Receive Channel MessagesChannel Message Management
  5. Manage Channel ConversationsChannel 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 createCommunityWithCommunityInfo 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 ZIMCommunityCreatedCallback. 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.
ZIMCommunityInfo *communityInfo = [[ZIMCommunityInfo alloc] init];
communityInfo.communityID = @"community_001"; // Customizable; leave blank for server auto-generation with #B prefix 
communityInfo.communityName = @"My Community"; // Max length 300 characters, configurable
communityInfo.communityAvatarUrl = @"https://example.com/avatar.png"; // Max length 100 characters, configurable

ZIMCommunityCreateConfig *config = [[ZIMCommunityCreateConfig alloc] init];
config.communityNotice = @"Welcome!"; // Max length 500 characters, configurable 
config.communityAttributes = @{@"key1": @"value1"}; // Default max 10 attribute pairs; key max 16 characters, value max 1024 characters

[zim createCommunity:communityInfo config:config callback:^(ZIMCommunityFullInfo * _Nonnull communityFullInfo, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Created successfully; communityFullInfo contains complete Community information
    }
}];
Error CodeDescriptionRecommended Action
6001003Community already existsCheck if a Community with the same communityID has already been created
6001007Community permission errorConfirm whether the current user has creation permission
6001008Community attribute count exceededThe default maximum is 10 attribute pairs

ZIMCommunityInfo Field Description

FieldTypeDescription
communityIDStringCommunity ID, customizable or auto-generated by the server
communityNameStringCommunity name, max length 300 characters, configurable
communityAvatarUrlStringCommunity avatar URL, max length 100 characters, configurable

ZIMCommunityCreateConfig Parameter Description

ParameterTypeDescription
communityNoticeStringCommunity notice, max length 500 characters, configurable
communityAttributesMap<String, String>Community custom attributes, default max 10 pairs; key max 16 characters, value max 1024 characters

ZIMCommunityFullInfo Core Fields

FieldTypeDescription
baseInfoZIMCommunityInfoCommunity basic information (ID, name, avatar, etc.)
communityNoticeStringCommunity notice
communityAttributesHashMap<String, String>Community custom attributes
createTimelongCommunity creation time
creatorUserIDStringCreator User ID
currentMemberCountintCurrent Community member count
notificationStatusZIMCommunityMessageNotificationStatusMessage notification status

Dismiss a Community

The Community owner can call the dismissCommunityByCommunityID 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.
[zim dismissCommunity:communityID callback:^(NSString * _Nonnull communityID, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Dismissed successfully
    }
}];

Join a Community

After logging in to the ZIM SDK, call the joinCommunityWithCommunityID 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.

[zim joinCommunity:communityID callback:^(ZIMCommunityFullInfo * _Nonnull communityFullInfo, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Joined successfully
    }
}];

Leave a Community

Members who have joined a Community can call the leaveCommunityByCommunityID 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.
[zim leaveCommunity:communityID callback:^(NSString * _Nonnull communityID, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Left successfully
    }
}];

Query Community List

Call the queryCommunityListWithCount 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.
ZIMCommunityListQueryConfig *config = [[ZIMCommunityListQueryConfig alloc] init];
config.nextFlag = 0;

[zim queryCommunityList:100 config:config callback:^(NSArray<ZIMCommunity *> * _Nonnull communityList, long long nextFlag, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Queried successfully
    }
}];

Query Community Information

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

[zim queryCommunityInfo:communityID callback:^(ZIMCommunityFullInfo * _Nonnull communityFullInfo, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Queried successfully
    }
}];

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.

[zim updateCommunityName:@"New Community Name" communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull communityName, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Updated successfully
    }
}];

Update Community Avatar

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

[zim updateCommunityAvatarUrl:@"https://example.com/new_avatar.png" communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull communityAvatarUrl, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Updated successfully
    }
}];

Update Community Notice

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

[zim updateCommunityNotice:@"New Community Notice" communityID:communityID callback:^(NSString * _Nonnull communityID, NSString * _Nonnull communityNotice, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Updated successfully
    }
}];

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.

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

[zim setCommunityAttributes:attributes communityID:communityID callback:^(NSString * _Nonnull communityID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Set successfully
    }
}];

Delete Attributes

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

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

[zim deleteCommunityAttributes:keys communityID:communityID callback:^(NSString * _Nonnull communityID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Deleted successfully
    }
}];

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.

[zim setCommunityNotificationStatus:ZIMCommunityMessageNotificationStatusDoNotDisturb communityID:communityID callback:^(NSString * _Nonnull communityID, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Set successfully
    }
}];

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 communityListChangedWithResult callback. The changeInfoList in the callback contains the change type (add, delete, update) and the corresponding Community information.

- (void)zim:(ZIM *)zim communityListChangedWithResult:(ZIMCommunityListChangedEventResult *)result {
    for (ZIMCommunityChangeInfo *changeInfo in 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 communityInfoUpdatedWithResult callback. The updateInfoList contains the updated complete Community information.

- (void)zim:(ZIM *)zim communityInfoUpdatedWithResult:(ZIMCommunityInfoUpdatedEventResult *)result {
    for (ZIMCommunityFullInfoUpdateInfo *updateInfo in 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.

2026-06-24

Previous

Overview

Next

Community member management