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

Supported message types are the same as those for groups, including text, rich media, custom, and combined messages. For details, see Send and receive messages - Message types.

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.

Example code

// Construct basic Community information
const communityInfo = {
    communityID: "community_001",
    communityName: "My Community",
    communityAvatarUrl: "https://example.com/avatar.png"
};

const config = {
    // Optional: set Community notice
    communityNotice: "Welcome!"
};

try {
    const result = await zim.createCommunity(communityInfo, config);
    // Creation succeeded, result contains full Community information
} catch (error) {
    // Creation failed, handle based on error.code
}

// Construct basic Community information
const communityInfo = {
    communityID: "community_001",
    communityName: "My Community",
    communityAvatarUrl: "https://example.com/avatar.png"
};

const config = {
    // Optional: set Community notice
    communityNotice: "Welcome!"
};

try {
    const result = await zim.createCommunity(communityInfo, config);
    // Creation succeeded, result contains full Community information
} catch (error) {
    // Creation failed, handle based on error.code
}

Join an existing Community

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

Example code

const communityID = "community_001";

try {
    const result = await zim.joinCommunity(communityID);
    // Joined successfully, result contains full Community information
} catch (error) {
    // Failed to join, handle based on error.code
}

const communityID = "community_001";

try {
    const result = await zim.joinCommunity(communityID);
    // Joined successfully, result contains full Community information
} catch (error) {
    // Failed to join, handle based on error.code
}

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.

Example code

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

const 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.
};

try {
    const result = await zim.queryCommunityChannelList(communityID, count, config);
    for (const channel of result.channelList) {
        // channel.baseInfo.channelID   — Channel ID
        // channel.baseInfo.channelName — Channel name
        // channel.conversationID        — Conversation ID used for sending/receiving messages
    }
    // result.nextFlag is used for pagination. A value of 0 or an empty list indicates no more data.
} catch (error) {
    // Query failed, handle based on error.code
}

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

const 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.
};

try {
    const result = await zim.queryCommunityChannelList(communityID, count, config);
    for (const channel of result.channelList) {
        // channel.baseInfo.channelID   — Channel ID
        // channel.baseInfo.channelName — Channel name
        // channel.conversationID        — Conversation ID used for sending/receiving messages
    }
    // result.nextFlag is used for pagination. A value of 0 or an empty list indicates no more data.
} catch (error) {
    // Query failed, handle based on error.code
}

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

Example code

// After obtaining the target channel, use its conversationID to send a message
const conversationID = channel.conversationID; // From the queryCommunityChannelList result

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

const config = {
    // Set message priority: LOW(1) / MEDIUM(2) / HIGH(3)
    priority: ZIMMessagePriority.LOW,
};

try {
    const result = await zim.sendMessage(
        textMessage,
        conversationID,
        ZIMConversationType.COMMUNITY_CHANNEL,   // Conversation type: Community channel
        config
    );
    // Message sent successfully
} catch (error) {
    // Message sending failed, handle based on error.code
}

// After obtaining the target channel, use its conversationID to send a message
const conversationID = channel.conversationID; // From the queryCommunityChannelList result

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

const config = {
    // Set message priority: LOW(1) / MEDIUM(2) / HIGH(3)
    priority: ZIMMessagePriority.LOW,
};

try {
    const result = await zim.sendMessage(
        textMessage,
        conversationID,
        ZIMConversationType.COMMUNITY_CHANNEL,   // Conversation type: Community channel
        config
    );
    // Message sent successfully
} catch (error) {
    // Message sending failed, handle based on error.code
}

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 code

// Example: sending an image message
const imageMessage = new ZIMImageMessage({ fileLocalPath: '/path/to/photo.jpg' });

const config = {
    priority: ZIMMessagePriority.MEDIUM,
};

try {
    const result = await zim.sendMessage(
        imageMessage,
        conversationID,
        ZIMConversationType.COMMUNITY_CHANNEL,
        config
    );
    // Image sent successfully
} catch (error) {
    // Image sending failed, handle based on error.code
}

// Example: sending an image message
const imageMessage = new ZIMImageMessage({ fileLocalPath: '/path/to/photo.jpg' });

const config = {
    priority: ZIMMessagePriority.MEDIUM,
};

try {
    const result = await zim.sendMessage(
        imageMessage,
        conversationID,
        ZIMConversationType.COMMUNITY_CHANNEL,
        config
    );
    // Image sent successfully
} catch (error) {
    // Image sending failed, handle based on error.code
}

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.

Example code

zim.on('messageReceived', (result: ZIMMessageReceivedEventResult) => {
    const info = result.receivedInfo;

    // Filter Community channel messages
    if (info.conversationType === ZIMConversationType.COMMUNITY_CHANNEL) {
        const conversationID = info.conversationID;

        for (const message of result.messageList) {
            // Handle by message type
            if (message.type === ZIMMessageType.TEXT) {
                const textMsg = message as ZIMTextMessage;
                // Handle text message
            } else if (message.type === ZIMMessageType.IMAGE) {
                const imageMsg = message as ZIMImageMessage;
                // Handle image message; call downloadMediaFile to download the original image
            }
        }
    }
});

zim.on('messageReceived', (result: ZIMMessageReceivedEventResult) => {
    const info = result.receivedInfo;

    // Filter Community channel messages
    if (info.conversationType === ZIMConversationType.COMMUNITY_CHANNEL) {
        const conversationID = info.conversationID;

        for (const message of result.messageList) {
            // Handle by message type
            if (message.type === ZIMMessageType.TEXT) {
                const textMsg = message as ZIMTextMessage;
                // Handle text message
            } else if (message.type === ZIMMessageType.IMAGE) {
                const imageMsg = message as ZIMImageMessage;
                // Handle image message; call downloadMediaFile to download the original image
            }
        }
    }
});

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.

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

ZIM error codes

2026-06-24

Channel message management

Overview

Prerequisites

Step 1: Create or join a Community

Step 2: Get the channel list

Send messages

Ordinary messages

Rich media messages

Receive messages

Advanced operations

Related references