Reference channels

Channel referencing lets users mention specific channel names in a chat conversation. They can do it by adding # and typing at least three first letters of the channel name they want to reference. As a result, they get a list of suggested names when typing such a suggestion, like #Sup.

Generic referencing

Channel references, user mentions, and links are instances of MessageElement with different MentionTarget types.

The list of returned channels contains all channels in an app (channel data taken from the Admin Portal keyset for the app), regardless of whether the users are members of these channels. The number of returned suggested channels for reference also depends on the app configuration and can show up to 100 suggestions. The names of the suggested channels can consist of multiple words.

You can configure your app to let users refer up to 100 channels in a single message (default value is 10) and show references as links.

You can implement channel referencing in your app similarly to user mentions and links.

Requires App Context

To reference channels from a keyset, you must enable App Context for your app's keyset in the Admin Portal.

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() 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.

1// create an empty message draft
2val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)
3

4// change the text
5messageDraft.update(text = "Hello Alex! I have sent you this link on the #offtopic channel.")
6

7// add a channel mention to the string '#offtopic'
8messageDraft.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.

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() method for details.

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.

1// assume the message reads
2// Hello Alex! I have sent you this link on the #offtopic channel.`
3

4// remove the channel reference
5messageDraft.removeMention(offset = 45)

Get channel suggestions

The message elements listener returns all channels referenced in the draft message that match the provided 3-letter string from your app's keyset.

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() method for details.

Sample code

1// create a message draft
2val messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered = channel.type != ChannelType.PUBLIC)
3

4// add the listener
5val listener = { elements: List<MessageElement>, suggestedMentions: PNFuture<List<SuggestedMention>> ->
6        updateUI(elements) // updateUI is your own function for updating UI
7        suggestedMentions.async { result ->
8            result.onSuccess { updateSuggestions(it) } // updateSuggestions is your own function for displaying suggestions
9        }
10    }
11messageDraft.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:

1message.getMessageElements(): List<MessageElement>

Input

This method doesn't take any parameters.

Output

Type	Description
List<MessageElement>	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.

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:

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

MessageElement details

Sample code

Check if the message with the 16200000000000000 timetoken contains any channel references.

1chat.getChannel("incident-management").async { channelResult ->
2    channelResult.onSuccess { channel ->
3        // successfully retrieved the channel
4        channel?.getMessage(16200000000000000L)?.async { messageResult ->
5            messageResult.onSuccess { message ->
6                // handle success
7                val elements = message?.getMessageElements()
8                val hasChannelReferences = elements?.any { element ->
9                    // Assuming there's a way to check if an element is a channel reference
10                    element is Link && element.target is Channel
11                } ?: false
12

13                if (hasChannelReferences) {
14                    println("The message contains channel references.")
15                } else {
16                    println("The message does not contain any channel references.")
17                }
18            }.onFailure { error ->
19                // handle failure
20                println("Failed to retrieve the message: ${error.message}")
21            }
22        }
23    }.onFailure { error ->
24        // failed to retrieve the channel
25        println("Failed to retrieve the channel: ${error.message}")
26    }
27}

show all 27 lines

Get referenced channels (deprecated)

You can access the referencedChannels property of the Message object to return all channel names referenced in a message.

Method signature

This is how you can access the property:

1message.referencedChannels

Sample code

Check if the message with the 16200000000000000 timetoken contains any channel references.

1val channel = chat.getChannel("your-channel")
2

3channel.getMessage(16200000000000000).async { result ->
4    result.onSuccess { message: Message? ->
5        if (message != null) {
6            // access the referencedChannels property
7            val referencedChannels = message.referencedChannels
8            
9            if (referencedChannels != null && referencedChannels.isNotEmpty()) {
10                println("The message contains the following referenced channels:")
11                referencedChannels.forEach { (position, refChannel) ->
12                    println("Position: $position, Channel: ${refChannel.name}, ID: ${refChannel.id}")
13                }
14            } else {
15                println("The message does not contain any channel references.")
16            }
17        } else {
18            println("Message does not exist")
19        }
20    }.onFailure { exception: PubNubException ->
21        println("Exception occurred: ${exception.message}")
22    }
23}

show all 23 lines