Skip to main content

Tagging channels

  • Before tagging channels, make sure you have created tag data. See Managing Channel Tag Data.
  • This feature is not available for open channels or community channels.

Each user can create up to 20 tags, and each tag can hold up to 1,000 channels. If a tag already contains 1,000 channels, adding more channels will succeed but the earliest-tagged channel will be removed from the tag.

Use cases​

Channel tags are commonly used to let users organize channels into groups. After creating a tag, users can assign one or more tags to a channel.

Once tags are assigned, you can use them to filter and display channels by group, delete tagged channels, get unread counts for a specific tag, or pin channels within a tag group.

  • Scenario 1: Tag each channel in the channel list — similar to "External Groups," "Department Groups," and "Personal Groups" tags in enterprise messaging apps.
  • Scenario 2: Organize contacts by tag — similar to "Family," "Friends," and "Colleagues" groups in contact lists.
  • Scenario 3: Combine both scenarios to group the channel list by tag — similar to Telegram's channel list folders.

Tag a channel​

After creating a tag, users can assign it to channels. The SDK treats tagging a channel as adding the channel to a tag.

Supported operations:

  • Add one or more channels to a tag
  • Remove one or more channels from a tag
  • Remove one or more tags from a channel

Add channels to a tag​

Call tag.addChannels() to add one or more channels to a tag.

kotlin
Tag.getTags { tagList, error ->
    if (error == null && tagList != null) {
        val tag = tagList.firstOrNull { it.tagId == "peixunban" }
        
        if (tag != null) {
            tag.addChannels(
                listOf(
                    ChannelIdentifier(ChannelType.DIRECT, "userId1"),
                    ChannelIdentifier(ChannelType.GROUP, "groupId1")
                )
            ) { error ->
                if (error == null) {
                    // Added successfully
                } else {
                    // Failed: ${error.message}
                }
            }
        }
    }
}

Remove channels from a tag​

Remove one or more channels from a tag. For example, remove the direct channel with "Tom" from all channels tagged "Training." After removal, the channel still exists but no longer carries the tag.

kotlin
Tag.getTags { tagList, error ->
    if (error == null && tagList != null) {
        val tag = tagList.firstOrNull { it.tagId == "peixunban" }
        
        if (tag != null) {
            tag.deleteChannels(
                listOf(
                    ChannelIdentifier(ChannelType.DIRECT, "userId1")
                )
            ) { error ->
                if (error == null) {
                    // Removed successfully
                } else {
                    // Failed: ${error.message}
                }
            }
        }
    }
}

Remove tags from a channel​

A channel may have multiple tags. Call channel.deleteTags() to remove one or more tags from a channel.

kotlin
val channel = DirectChannel("userId")

channel.deleteTags(listOf("tag001", "tag002")) { error ->
    if (error == null) {
        // Removed successfully
    } else {
        // Failed: ${error.message}
    }
}

Get all tags for a channel​

Call channel.getTags() to retrieve all tags associated with a channel.

kotlin
val channel = DirectChannel("userId")

channel.getTags { tagInfoList, error ->
    if (error == null && tagInfoList != null) {
        tagInfoList.forEach { info ->
            println("Tag: ${info.tag.tagName}")
            println("Tag ID: ${info.tag.tagId}")
            println("Pinned within tag: ${info.isTop}")
        }
    } else {
        // Failed: ${error?.message}
    }
}

Multi-device tag sync​

Nexconn supports multi-device login for the same user account. When a user adds, removes, or updates channel tags on another device, the ChannelHandler listener receives a notification. After receiving the notification, call channel.getTags() to fetch the latest tag data.

tip

Modifying channel tags on the current device does not trigger the callback. The server only notifies the SDK on other devices logged in with the same account.

Operations by tag​

The Nexconn SDK supports performing operations on channels that share a specific tag. After assigning tags to channels, you can:

  • Pin a channel within a tag group (using the [pinning] feature)
  • Retrieve the channel list filtered by tag
  • Get the unread message count for a tag
  • Clear unread counts for all channels under a tag
  • Delete all channels under a tag

Pin within a tag​

Organize and display channels by tag, then pin a channel within that tag group using the channel pinning feature.

For details, see Pin Within a Tag in Pinning Channels.

Get channels by tag (paginated)​

Call Tag.createTaggedChannelsQuery() to create a paginated query for channels under a specific tag. This queries the local database only.

kotlin
Tag.getTags { tagList, error ->
    if (error == null && tagList != null) {
        val tag = tagList.firstOrNull { it.tagId == "peixunban" }
        
        if (tag != null) {
            val params = TaggedChannelsQueryParams(tag.tagId).apply { pageSize = 20 }
            val query = Tag.createTaggedChannelsQuery(params)
            
            query.loadNextPage { result, error ->
                if (error == null && result != null) {
                    result.data?.forEach { channel ->
                        println("Channel ID: ${channel.channelId}")
                        println("Channel type: ${channel.channelType}")
                    }
                }
            }
        }
    }
}

Get untagged channels (paginated)​

Call Tag.createUntaggedChannelsQuery() to create a paginated query for channels that have no tags.

kotlin
val params = UntaggedChannelsQueryParams().apply {
    pageSize = 20
    topPriority = true
}
val query = Tag.createUntaggedChannelsQuery(params)

query.loadNextPage { result, error ->
    if (error == null && result != null) {
        result.data?.forEach { channel ->
            println("Channel ID: ${channel.channelId}")
            println("Channel type: ${channel.channelType}")
        }
    }
}

Get unread count by tag​

Call tag.getUnreadCount() to get the total unread message count across all channels under a specific tag.

kotlin
Tag.getTags { tagList, error ->
    if (error == null && tagList != null) {
        val tag = tagList.firstOrNull { it.tagId == "peixunban" }
        
        if (tag != null) {
            tag.getUnreadCount(containNoDisturb = false) { count, error ->
                if (error == null && count != null) {
                    println("Unread count: $count")
                }
            }
        }
    }
}

Clear unread count by tag​

Call tag.clearUnreadCount() to clear the unread message count for all channels under a specific tag.

kotlin
Tag.getTags { tagList, error ->
    if (error == null && tagList != null) {
        val tag = tagList.firstOrNull { it.tagId == "peixunban" }
        
        if (tag != null) {
            tag.clearUnreadCount { success, error ->
                if (error == null && success == true) {
                    println("Cleared successfully")
                }
            }
        }
    }
}

Delete all channels under a tag​

Call tag.clearChannels() to delete all channels under a tag and unbind them from that tag. After deletion, the channels no longer carry the specified tag. When these channels receive new messages, new channel entries are created.

kotlin
Tag.getTags { tagList, error ->
    if (error == null && tagList != null) {
        val tag = tagList.firstOrNull { it.tagId == "peixunban" }
        
        if (tag != null) {
            tag.clearChannels(
                isDeleteMessage = true
            ) { success, error ->
                if (error == null && success == true) {
                    println("Deleted successfully")
                }
            }
        }
    }
}

Use the isDeleteMessage parameter to control whether local messages are also deleted:

  • false: Messages are kept. When new messages arrive, users can view message history.
  • true: Local messages are deleted. Users cannot see history when new messages arrive. If cloud message storage is enabled, the server still retains messages, and you can retrieve them via getMessages. To delete server-side messages, use the server-side message deletion API.
Last updated on