Channel conversation management

2026-06-24

Overview

Each Community channel corresponds to a conversation of type COMMUNITY_CHANNEL. Using the channel's conversationID, you can operate on channel conversations through ZIM's standard conversation management APIs, including:

Getting the channel list (including the conversation ID)
Clearing the unread message count of a channel
Setting/clearing the draft of a channel conversation
Configuring Do Not Disturb for a channel conversation
Listening for channel conversation changes

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.

Note

The conversationID of a channel conversation is different from the channel's channelID. When sending messages and managing conversations, please use the conversationID field obtained from the ZIMCommunityChannel object.

Warning

Do not mistakenly use channelID as conversationID. When sending messages and performing conversation management operations, you must use the conversationID obtained from the channel object (ZIMCommunityChannel), not channelID.

Get the channel list

Before managing channel conversations, you need to call the queryCommunityChannelList API to get the channel list and obtain the conversationID from the returned ZIMCommunityChannel object for subsequent conversation operations.

Pagination rule: Set config.nextFlag to 0 for the first request, pass the returned nextFlag to the next request, and continue until 0 is returned.

Example code

const config: ZIMCommunityChannelListQueryConfig = { nextFlag: 0 };

zim.queryCommunityChannelList(communityID, 100, config)
    .then((result: ZIMCommunityChannelListQueriedResult) => {
        for (const channel of result.channelList) {
            const conversationID = channel.conversationID; // Used for subsequent conversation management
        }
    })
    .catch((err: ZIMError) => {
        // Query failed
    });

const config: ZIMCommunityChannelListQueryConfig = { nextFlag: 0 };

zim.queryCommunityChannelList(communityID, 100, config)
    .then((result: ZIMCommunityChannelListQueriedResult) => {
        for (const channel of result.channelList) {
            const conversationID = channel.conversationID; // Used for subsequent conversation management
        }
    })
    .catch((err: ZIMError) => {
        // Query failed
    });

Clear unread message count

Call the clearConversationUnreadMessageCount API to reset the unread message count of a specified channel conversation to zero. After successful clearing, the conversationChanged callback will be triggered to reflect the latest conversation state.

Example code

const conversationID = channel.conversationID;
const conversationType = ZIMConversationType.CommunityChannel;

zim.clearConversationUnreadMessageCount(conversationID, conversationType)
    .then((result: ZIMConversationUnreadMessageCountClearedResult) => {
        // Unread count cleared
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

const conversationID = channel.conversationID;
const conversationType = ZIMConversationType.CommunityChannel;

zim.clearConversationUnreadMessageCount(conversationID, conversationType)
    .then((result: ZIMConversationUnreadMessageCountClearedResult) => {
        // Unread count cleared
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

Set conversation draft

Call the setConversationDraft API to save draft content for a specified channel conversation, allowing the user to continue editing after leaving the channel. Draft content is stored locally only and will not be sent to other users.

Note

To clear the draft, simply pass an empty string for draft.

Example code

const draft = 'This is draft content';
const conversationID = channel.conversationID;
const conversationType = ZIMConversationType.CommunityChannel;

zim.setConversationDraft(draft, conversationID, conversationType)
    .then((result: ZIMConversationDraftSetResult) => {
        // Draft saved successfully
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

const draft = 'This is draft content';
const conversationID = channel.conversationID;
const conversationType = ZIMConversationType.CommunityChannel;

zim.setConversationDraft(draft, conversationID, conversationType)
    .then((result: ZIMConversationDraftSetResult) => {
        // Draft saved successfully
    })
    .catch((err: ZIMError) => {
        // Operation failed
    });

Set conversation notification status

Call the setConversationNotificationStatus API to set the Do Not Disturb status for a specified channel conversation. When set to Do Not Disturb, the unread message count of that channel will no longer be added to the total unread count of the Community, and system push notifications will not be triggered.

Example code

const conversationID = channel.conversationID;
const conversationType = ZIMConversationType.CommunityChannel;
const status = 2;             // 2 = Do Not Disturb, 1 = Normal notification

zim.setConversationNotificationStatus(status, conversationID, conversationType)
    .then((result: ZIMConversationNotificationStatusSetResult) => {
        // Set successfully
    })
    .catch((err: ZIMError) => {
        // Setting failed
    });

const conversationID = channel.conversationID;
const conversationType = ZIMConversationType.CommunityChannel;
const status = 2;             // 2 = Do Not Disturb, 1 = Normal notification

zim.setConversationNotificationStatus(status, conversationID, conversationType)
    .then((result: ZIMConversationNotificationStatusSetResult) => {
        // Set successfully
    })
    .catch((err: ZIMError) => {
        // Setting failed
    });

Listen for channel list changes

When channels in a Community are created, disbanded, or their visible information changes, the channel list updates accordingly. The SDK notifies the developer through the onCommunityChannelListChanged callback. You can re-fetch the channel list in this callback to update the local conversationID mapping. For details, see Community channel management - Listen for channel list changes.

Note

Changes to channel conversations (such as unread count changes, draft updates, etc.) will also trigger the conversationChanged callback. For the complete usage of conversation change listening, refer to Get the conversation list.

ZIM error codes

2026-06-24

Channel conversation management

Overview

Prerequisites

Get the channel list

Clear unread message count

Set conversation draft

Set conversation notification status

Listen for channel list changes

Related references