--- source_url: https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/channels/references title: Reference channels updated_at: 2026-06-15T12:11:31.494Z --- > Documentation Index > For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt > For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt # Reference channels Channel referencing lets users mention channels in messages by typing `#` followed by at least three letters. Matching channel names appear as suggestions. :::tip Generic referencing Channel references, user mentions, and links are `MessageElement` instances with different `MentionTarget` values. ::: Suggestions include all channels in the app keyset (up to 100), regardless of user membership. Configure up to 100 channel references per message (default: 10) and display them as links. Implementation is similar to [user mentions](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/users/mentions) and [links](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/messages/links). :::note Requires App Context To reference channels from a keyset, you must [enable App Context](https://youtu.be/9UEoSlngpYI) for your app's keyset in the [Admin Portal](https://admin.pubnub.com/). ::: ## Add channel references You can let users reference channels in a message by adding `#` and typing at least three first letters of the channel name they want to reference, like `#Sup`. ### Method signature You can add a channel reference by calling the `addMention()` method with the `target` of `MentionTarget.Channel`. Refer to the [addMention()](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/messages/drafts#add-message-element) method for details. ### Sample code Create the `Hello Alex! I have sent you this link on the #offtopic channel.` message where `#offtopic` is a channel reference. ```kotlin // create an empty message draft val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC) // change the text messageDraft.update(text = "Hello Alex! I have sent you this link on the #offtopic channel.") // add a channel mention to the string '#offtopic' messageDraft.addMention(offset = 45, length = 9, target = MentionTarget.Channel(channelId = "group.offtopic")) ``` ## Remove channel references `removeMention()` lets you remove a previously added channel reference from a [draft message](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/messages/drafts). ### Method signature You can remove channel references from a draft message by calling the `removeMention()` method at the exact offset where the channel reference starts. Refer to the [removeMention()](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/messages/drafts#remove-message-element) method for details. :::warning Offset value If you don't provide the position of the first character of the message element to remove, it isn't removed. ::: ### Sample code Remove the channel reference from the `Hello Alex! I have sent you this link on the #offtopic channel.` message where `#offtopic` is a channel reference. ```kotlin // assume the message reads // Hello Alex! I have sent you this link on the #offtopic channel.` // remove the channel reference messageDraft.removeMention(offset = 45) ``` ## Get channel suggestions The message elements listener returns all channels referenced in the [draft message](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/learn/chat-entities/message-draft) that match the provided 3-letter string from your app's keyset. :::note Single listener The message elements listener returns suggestions for channel references, user mentions, and links. ::: For example, if you type `#Sup`, you will get the list of channels starting with `Sup` like `Support` or `Support-Agents`. The default number of returned suggested channel names is `10`, configurable to a maximum value of `100`. ### Method signature You must add a message elements listener to receive channel suggestions. Refer to the [addChangeListener()](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/messages/drafts#add-message-draft-change-listener) method for details. ### Sample code ```kotlin // create a message draft val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC) // add the listener val listener = { elements: List, suggestedMentions: PNFuture> -> updateUI(elements) // updateUI is your own function for updating UI suggestedMentions.async { result -> result.onSuccess { updateSuggestions(it) } // updateSuggestions is your own function for displaying suggestions } } messageDraft.addChangeListener(listener) ``` ## Get referenced channels To return all channel names referenced in a message, use the `getMessageElements()` method. ### Method signature This method has the following signature: ```kotlin message.getMessageElements(): List ``` #### Input This method doesn't take any parameters. #### Output | Type | Description | | --- | --- | | `List` | A list of message elements representing parsed components of the input text, including processed user mentions, links, and referenced channels based on the available data. | ##### MessageElement details Each `MessageElement` on the returned list can be of one of these types: * `data class PlainText(override val text: String) : MessageElement` * `data class Link(override val text: String, val target: MentionTarget) : MessageElement` If a `MessageElement` is of type `Link`, its `target` depends on the returned item: ```kotlin // Mentioned user identified by [userId]. data class User(val userId: String) : MentionTarget // Referenced channel identified by [channelId]. data class Channel(val channelId: String) : MentionTarget // Link to [url]. data class Url(val url: String) : MentionTarget ``` ### Sample code Check if the message with the `16200000000000000` timetoken contains any channel references. ```kotlin chat.getChannel("incident-management").async { channelResult -> channelResult.onSuccess { channel -> // successfully retrieved the channel channel?.getMessage(16200000000000000L)?.async { messageResult -> messageResult.onSuccess { message -> // handle success val elements = message?.getMessageElements() val hasChannelReferences = elements?.any { element -> // Assuming there's a way to check if an element is a channel reference element is Link && element.target is Channel } ?: false if (hasChannelReferences) { println("The message contains channel references.") } else { println("The message does not contain any channel references.") } }.onFailure { error -> // handle failure println("Failed to retrieve the message: ${error.message}") } } }.onFailure { error -> // failed to retrieve the channel println("Failed to retrieve the channel: ${error.message}") } } ``` ## Get referenced channels (deprecated) You can access the `referencedChannels` property of the [Message object](https://www.pubnub.com/docs/chat/kotlin-chat-sdk/learn/chat-entities/message) to return all channel names referenced in a message. ### Method signature This is how you can access the property: ```kotlin message.referencedChannels ``` ### Sample code Check if the message with the `16200000000000000` timetoken contains any channel references. ```kotlin val channel = chat.getChannel("your-channel") channel.getMessage(16200000000000000).async { result -> result.onSuccess { message: Message? -> if (message != null) { // access the referencedChannels property val referencedChannels = message.referencedChannels if (referencedChannels != null && referencedChannels.isNotEmpty()) { println("The message contains the following referenced channels:") referencedChannels.forEach { (position, refChannel) -> println("Position: $position, Channel: ${refChannel.name}, ID: ${refChannel.id}") } } else { println("The message does not contain any channel references.") } } else { println("Message does not exist") } }.onFailure { exception: PubNubException -> println("Exception occurred: ${exception.message}") } } ```