In-app Chat
SDK Error Codes
On this page

Channel message management

2026-06-24

Overview

Community is a Discord-like real-time interactive community feature provided by ZIM, using a two-layer "Community - Channel" structure. A Channel is the basic unit for chat interactions within a Community, similar to traditional groups, supporting sending various types of messages such as text, images, voice, and video.

This document describes how to send and receive messages in Community channels. Sending and receiving channel messages are based on ZIM's standard messaging APIs, using ZIMConversationType.COMMUNITY_CHANNEL as the conversation type.

Prerequisites

  • Please refer to Send and receive messages to complete ZIM SDK integration, initialization, and user login.
  • Please refer to Token-based authentication to implement user authentication login.
  • The Community feature requires ZIM SDK 3.0.0 or later.
  • The Community feature is part of the Premium plan. Please contact ZEGOCLOUD Technical Support to enable it before use.
  • The Token generation for the Community feature is consistent with other ZIM features, and no additional permission declarations are required.
  • Before sending channel messages, the user must join (or create) a Community and obtain the conversationID of the target channel.
Note

Step 1: Create or join a Community

Create a Community

Call the createCommunityWithCommunityInfo API to create a Community. Upon successful creation, the system automatically creates a default channel of type GENERAL for the Community.

ZIMCommunityInfo *communityInfo = [[ZIMCommunityInfo alloc] init];
communityInfo.communityID = @"community_001";
communityInfo.communityName = @"My Community";
communityInfo.communityAvatarUrl = @"https://example.com/avatar.png";

ZIMCommunityCreateConfig *config = [[ZIMCommunityCreateConfig alloc] init];
config.communityNotice = @"Welcome!";

[zim createCommunity:communityInfo config:config callback:^(ZIMCommunityFullInfo * _Nonnull communityFullInfo, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Creation succeeded, communityFullInfo contains full Community information
    }
}];

Join an existing Community

When the communityID is known, call the joinCommunityWithCommunityID API to join the Community.

NSString *communityID = @"community_001";

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

Step 2: Get the channel list

After joining a Community, call the queryCommunityChannelListByCommunityID API to query the channel list and obtain the channel object ZIMCommunityChannel.

The conversationID field of the channel object is the conversation ID required for subsequent message sending and receiving.

NSString *communityID = @"community_001";
NSUInteger count = 100;

ZIMCommunityChannelListQueryConfig *config = [[ZIMCommunityChannelListQueryConfig alloc] init];
// config.nextFlag is used for pagination. No need to set it for the first query.

[zim queryCommunityChannelList:communityID count:count config:config callback:^(NSString * _Nonnull communityID, NSArray<ZIMCommunityChannel *> * _Nonnull channelList, long long nextFlag, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        for (ZIMCommunityChannel *channel in channelList) {
            // channel.baseInfo.channelID   — Channel ID
            // channel.baseInfo.channelName — Channel name
            // channel.conversationID        — Conversation ID used for sending/receiving messages
        }
    }
}];
Note
  • ZIMCommunityChannel.conversationID is different from ZIMCommunityChannelInfo.channelID. Please use conversationID when sending messages.
  • If the Community has many channels, you can paginate using the returned nextFlag until it returns 0 or the list is empty.

Send messages

Note

The conversationID used for sending and receiving channel messages is different from the channel's channelID. conversationID is used for message sending/receiving and conversation management, and can be obtained from the channel object; channelID is used for channel management operations (such as creating, updating, and deleting channels). Do not confuse the two.

After obtaining the target channel's conversationID, call the sendMessage API to send a message. The difference from other conversation types is that you need to set conversationType to ZIMConversationType.COMMUNITY_CHANNEL.

Warning
  • The message sending API is shared across one-on-one chats, groups, rooms, and Community channels via the same sendMessage, with the target conversation type distinguished by conversationType.
  • The interval between two message sends must be greater than 100ms.

Ordinary messages

// After obtaining the target channel, use its conversationID to send a message
NSString *conversationID = channel.conversationID;

ZIMTextMessage *textMessage = [[ZIMTextMessage alloc] init];
textMessage.message = @"Hello, Channel!";

ZIMMessageSendConfig *config = [[ZIMMessageSendConfig alloc] init];
config.priority = ZIMMessagePriorityLow;

[zim sendMessage:textMessage toConversationID:conversationID conversationType:ZIMConversationTypeCommunityChannel config:config callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Message sent successfully
    }
}];

Rich media messages

When sending rich media messages such as images, files, audio, and video, also set conversationType to ZIMConversationType.COMMUNITY_CHANNEL. The rest of the usage is consistent with group messages.

// Example: sending an image message
ZIMImageMessage *imageMessage = [[ZIMImageMessage alloc] initWithFileLocalPath:@"/path/to/photo.jpg"];

ZIMMessageSendConfig *config = [[ZIMMessageSendConfig alloc] init];
config.priority = ZIMMessagePriorityMedium;

[zim sendMessage:imageMessage toConversationID:conversationID conversationType:ZIMConversationTypeCommunityChannel config:config callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
    if (errorInfo.code == ZIMErrorCodenoneSuccess) {
        // Image sent successfully
    }
}];
Note

For the construction and sending parameters of each message type (custom messages, combined messages, etc.), please refer to Send and receive messages. Simply replace the conversationType in the corresponding example code with ZIMConversationType.COMMUNITY_CHANNEL, and replace toConversationID with the channel's conversationID.

Receive messages

Starting from ZIM SDK 3.0.0, all online messages from one-on-one chats, groups, rooms, and Community channels are received through the unified messageReceivedWithResult callback. The callback returns ZIMMessageReceivedEventResult, where the receivedInfo.conversationType field is used to determine the conversation type to which the message belongs.

zim.eventHandler = self;

- (void)zim:(ZIM *)zim messageReceivedWithResult:(ZIMMessageReceivedEventResult *)result {
    ZIMMessageReceivedInfo *info = result.receivedInfo;

    // Filter Community channel messages
    if (info.conversationType == ZIMConversationTypeCommunityChannel) {
        NSString *conversationID = info.conversationID;

        for (ZIMMessage *message in result.messageList) {
            // Handle by message type
            if ([message isKindOfClass:[ZIMTextMessage class]]) {
                ZIMTextMessage *textMsg = (ZIMTextMessage *)message;
                // Handle text message
            } else if ([message isKindOfClass:[ZIMImageMessage class]]) {
                ZIMImageMessage *imageMsg = (ZIMImageMessage *)message;
                // Handle image message
            }
        }
    }
}
Note
  • After a user logs back in, they can receive channel messages that accumulated during offline time through this callback (requires the server to enable channel offline message storage).
  • To proactively pull history messages, please refer to Get message history, passing in the channel's conversationID and ZIMConversationType.COMMUNITY_CHANNEL.

Advanced operations

In addition to basic message sending and receiving, Community channels also support the following advanced messaging operations. For each feature, pass the channel's conversationID as the conversationID and ZIMConversationType.COMMUNITY_CHANNEL as the conversationType. For detailed usage, refer to the corresponding documentation.

FeatureDescription
Get message historyPaginate and pull history messages within a channel, supporting queries by time range, message sequence number, and other conditions.
Insert local messagesInsert a notification message visible only to the local device into the channel's local database, which will not be sent to other members.
Recall messagesRecall your own sent messages in a channel; admins or group owners can recall others' messages.
Set message extension fieldAttach extension fields visible to the other party or only to the local device for channel messages.
Search for local messagesSearch local history messages within a channel by keyword, user ID, and other conditions.
Respond to messages with emoticonsAdd or remove emoji reactions on channel messages, supporting scenarios such as group voting.
Receive tip messagesReceive automatically generated operation tip messages within a channel (such as member join/leave).
Edit messagesModify already-sent messages within a channel, with changes synced in real time to all channel members.
2026-06-24

Previous

Channel management

Next

Channel conversation management

On this page

Back to top