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 createCommunity API to create a Community. Upon successful creation, the system automatically creates a default channel of type GENERAL for the Community.

import im.zego.zim.ZIM;
import im.zego.zim.entity.ZIMCommunityCreateConfig;
import im.zego.zim.entity.ZIMCommunityFullInfo;
import im.zego.zim.entity.ZIMCommunityInfo;
import im.zego.zim.entity.ZIMError;
import im.zego.zim.enums.ZIMErrorCode;

// Construct basic Community information
ZIMCommunityInfo communityInfo = new ZIMCommunityInfo();
communityInfo.setCommunityID("community_001");   // Community ID, customized by the developer
communityInfo.setCommunityName("My Community");
communityInfo.setCommunityAvatarUrl("https://example.com/avatar.png");

ZIMCommunityCreateConfig config = new ZIMCommunityCreateConfig();
// Optional: set Community notice
config.setCommunityNotice("Welcome!");

zim.createCommunity(communityInfo, config, (ZIMCommunityFullInfo fullInfo, ZIMError error) -> {
    if (error.code == ZIMErrorCode.SUCCESS) {
        // Creation succeeded, fullInfo contains full Community information
    }
});

Join an existing Community

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

String communityID = "community_001";

zim.joinCommunity(communityID, (ZIMCommunityFullInfo fullInfo, ZIMError error) -> {
    if (error.code == ZIMErrorCode.SUCCESS) {
        // Joined successfully, fullInfo contains full Community information
    }
});

Step 2: Get the channel list

After joining a Community, call the queryCommunityChannelList 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.

String communityID = "community_001";
int count = 100; // Maximum number of channels to fetch per request

ZIMCommunityChannelListQueryConfig config = new ZIMCommunityChannelListQueryConfig();
// config.nextFlag is used for pagination. No need to set it for the first query; for subsequent queries, use the nextFlag returned from the previous call.

zim.queryCommunityChannelList(communityID, count, config,
    (ArrayList<ZIMCommunityChannel> channelList, long nextFlag, ZIMError error) -> {
        if (error.code == ZIMErrorCode.SUCCESS) {
            for (ZIMCommunityChannel channel : channelList) {
                // channel.getBaseInfo().getChannelID()   — Channel ID
                // channel.getBaseInfo().getChannelName() — Channel name
                // channel.getConversationID()             — 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
String conversationID = channel.getConversationID(); // From the queryCommunityChannelList result

ZIMTextMessage textMessage = new ZIMTextMessage();
textMessage.setMessage("Hello, Channel!");

ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// Set message priority: LOW(1) / MEDIUM(2) / HIGH(3)
config.setPriority(ZIMMessagePriority.LOW);

zim.sendMessage(
    textMessage,
    conversationID,
    ZIMConversationType.COMMUNITY_CHANNEL,   // Conversation type: Community channel
    config,
    new ZIMMessageSentFullCallback() {
        @Override
        public void onMessageAttached(ZIMMessage message) {
            // Message has passed local validation and is ready to send; you can update the UI here (e.g., show sending status)
        }

        @Override
        public void onMessageSent(ZIMMessage message, ZIMError error) {
            if (error.code == ZIMErrorCode.SUCCESS) {
                // Message sent successfully
            } else {
                // Message sending failed, handle based on error.code
            }
        }

        @Override
        public void onMediaUploadingProgress(ZIMMediaMessage message, long currentFileSize, long totalFileSize) {
        }

        @Override
        public void onMultipleMediaUploadingProgress(ZIMMultipleMessage message, long messageInfoIndex, long currentIndexFileSize, int messageIndex, long totalIndexFileSize, long totalFileSize) {
        }
    }
);

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 = new ZIMImageMessage(
    "/storage/emulated/0/Android/data/com.example/pictures/photo.jpg"
);

ZIMMessageSendConfig config = new ZIMMessageSendConfig();
config.setPriority(ZIMMessagePriority.MEDIUM);

zim.sendMessage(
    imageMessage,
    conversationID,
    ZIMConversationType.COMMUNITY_CHANNEL,
    config,
    new ZIMMessageSentFullCallback() {
        @Override
        public void onMessageAttached(ZIMMessage message) {
            // You can show an image placeholder UI here
        }

        @Override
        public void onMessageSent(ZIMMessage message, ZIMError error) {
            if (error.code == ZIMErrorCode.SUCCESS) {
                // Image sent successfully; message contains the server-generated fileDownloadUrl
            }
        }

        @Override
        public void onMediaUploadingProgress(
            ZIMMediaMessage message, long currentFileSize, long totalFileSize) {
            // You can update the upload progress bar here
        }
    }
);
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 onMessageReceived callback. The callback returns ZIMMessageReceivedEventResult, where the receivedInfo.conversationType field is used to determine the conversation type to which the message belongs.

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onMessageReceived(ZIM zim, ZIMMessageReceivedEventResult result) {
        ZIMMessageReceivedInfo info = result.getReceivedInfo();

        // Filter Community channel messages
        if (info.getConversationType() == ZIMConversationType.COMMUNITY_CHANNEL) {
            String conversationID = info.getConversationID(); // conversationID of the channel the message belongs to

            for (ZIMMessage message : result.getMessageList()) {
                // Handle by message type
                switch (message.getType()) {
                    case TEXT:
                        ZIMTextMessage textMsg = (ZIMTextMessage) message;
                        // Handle text message
                        break;
                    case IMAGE:
                        ZIMImageMessage imageMsg = (ZIMImageMessage) message;
                        // Handle image message; call downloadMediaFile to download the original image
                        break;
                    default:
                        break;
                }
            }
        }
    }
});
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.

Previous

Channel management

Next

Channel conversation management

On this page

Back to top