Channel conversation management

2026-09-18

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
Syncing channel conversations to the conversation list

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 onConversationChanged 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
    });

Sync channel conversations to the conversation list

After this feature is enabled, community channel conversations are included in the ZIM conversation list together with one-on-one and group conversations: you can pull the complete list including channel conversations in one go through queryConversationList, and stay aware of changes to channel conversations such as the latest messages, unread counts, and drafts through onConversationChanged, without maintaining a separate list for community channels.

For channel conversations synced to the conversation list, the conversation type is COMMUNITY_CHANNEL, and the conversationID is still the conversationID field in the channel object ZIMCommunityChannel.

Warning

This feature is disabled by default. Contact ZEGOCLOUD Technical Support for activation before use. If it is not enabled, channel conversations do not appear in the conversation list, and no conversation change notifications of the COMMUNITY_CHANNEL type are generated.
The current version only supports syncing the default channel of a Community to the conversation list. For other channels, continue to use queryCommunityChannelList to get and manage them.

Supported conversation management capabilities

After channel conversations enter the conversation list, the available conversation management APIs are the same as the capabilities described earlier in this article:

Conversation management capability	API	Supported
Clear conversation unread count	clearConversationUnreadMessageCount	Yes
Set conversation draft	setConversationDraft	Yes
Set conversation Do Not Disturb	setConversationNotificationStatus	Yes
Pin conversation	updateConversationPinnedState	Not supported yet
Mark conversation	setConversationMark	Not supported yet

Get the community ID of a channel conversation

ZIMConversation adds a relatedID property to identify the ID of the object associated with the conversation. When the conversation type is COMMUNITY_CHANNEL, this value is the communityID of the Community that the channel belongs to.

In the conversation list scenario, you can directly locate the Community that a channel conversation belongs to through relatedID, for scenarios such as querying community public information and pulling the community member list, without maintaining the mapping between conversationID and communityID yourself.

Note

In the current version, the meaning of relatedID is clearly defined only when the conversation type is COMMUNITY_CHANNEL.

Listen for community channel conversation updates

The addition, update, and deletion of channel conversations are notified through the onConversationChanged callback, just like one-on-one and group conversations. In the callback, you can filter out conversations of the COMMUNITY_CHANNEL type and update the display of community channels in the conversation list.

Example code

// Register SDK event notification callbacks
zim.on('conversationChanged', (zim: ZIM, data: ZIMConversationChangedEventResult) => {
    data.infoList.forEach((info) => {
        const conversation = info.conversation;
        if (conversation.type !== ZIMConversationType.CommunityChannel) {
            // Not a channel conversation, handle it with the original logic
            return;
        }
        // info.action: Added (conversation added), Deleted (conversation deleted), Updated (conversation updated)
        const conversationID = conversation.conversationID;  // Channel conversation ID
        const communityID = conversation.relatedID;          // ID of the Community that the channel conversation belongs to
        const unreadMessageCount = conversation.unreadMessageCount;
        const draft = conversation.draft;
    });
});

// Register SDK event notification callbacks
zim.on('conversationChanged', (zim: ZIM, data: ZIMConversationChangedEventResult) => {
    data.infoList.forEach((info) => {
        const conversation = info.conversation;
        if (conversation.type !== ZIMConversationType.CommunityChannel) {
            // Not a channel conversation, handle it with the original logic
            return;
        }
        // info.action: Added (conversation added), Deleted (conversation deleted), Updated (conversation updated)
        const conversationID = conversation.conversationID;  // Channel conversation ID
        const communityID = conversation.relatedID;          // ID of the Community that the channel conversation belongs to
        const unreadMessageCount = conversation.unreadMessageCount;
        const draft = conversation.draft;
    });
});

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 onConversationChanged 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

Sync channel conversations to the conversation list

Supported conversation management capabilities

Get the community ID of a channel conversation

Listen for community channel conversation updates

Listen for channel list changes

Related references