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.
Basic usage
Sample code
The code samples in Swift Chat SDK focus on asynchronous code execution.
You can also write synchronous code as the parameters are shared between the async and sync methods but we don't provide usage examples of such.
Create the Hello Alex! I have sent you this link on the #offtopic channel. message where #offtopic is a channel reference.
// Assuming you have a reference of type "ChatImpl" named "chat"
Task {
if let channel = try await chat.getChannel(channelId: "messages") {
let messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered: true)
messageDraft.update(text: "Hello Alex! I have sent you this link on the #offtopic channel.")
messageDraft.addMention(offset: 45, length: 9, target: MentionTarget.channel(channelId: "group.offtopic"))
try await messageDraft.send()
} else {
debugPrint("Channel not found")
}
}
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.
Basic usage
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.
// 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 that match the provided 3-letter string from your app's keyset.
Single listener
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.
Basic usage
Create a message draft and add a change listener to listen for channel references.
// Create a message draft
// Assuming you have a reference of type "ChannelImpl" named "channel"
let messageDraft = channel.createMessageDraft(isTypingIndicatorTriggered: channel.type != .public)
// Define the listener conforming to MessageDraftChangeListener protocol.
// You can also use our ClosureMessageDraftChangeListener class to reduce the need for your custom types to implement the MessageDraftChangeListener protocol
class DraftChangeListener: MessageDraftChangeListener {
func onChange(messageElements: [MessageElement], suggestedMentions: any FutureObject<[SuggestedMention]>) {
// Update UI with message elements. This is your own function for updating UI
updateUI(with: messageElements)
// Asynchronously process suggested mentions
suggestedMentions.async { result in
switch result {
case .success(let mentions):
// This is your own function for updating suggestions
Get referenced channels
To return all channel names referenced in a message, use the getMessageElements() method.
Method signature
This method has the following signature:
message.getMessageElements()
Basic usage
Check if the message with the 16200000000000000 timetoken contains any channel references.
// Assuming you have a reference of type "MessageImpl" named "message".
// Retrieve the message elements
let messageElements = message.getMessageElements()
// Check if any of the message elements reference a channel
let containsChannelReference = messageElements.contains {
switch $0 {
case let .link(text, target):
if case let .channel(channelId) = target {
// Replace this with your condition for checking if the element is a channel reference
// This is a placeholder condition
return true
} else {
return false
}
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:
message.referencedChannels
Basic usage
Sample code
The code samples in Swift Chat SDK focus on asynchronous code execution.
You can also write synchronous code as the parameters are shared between the async and sync methods but we don't provide usage examples of such.
Check if the message with the 16200000000000000 timetoken contains any channel references.
// Assuming you have a reference of type "ChannelImpl" named "channel"
// Get the specific message using its timetoken
Task {
if let message = try await channel.getMessage(timetoken: 16200000000000000) {
if let referencedChannels = message.referencedChannels, !referencedChannels.isEmpty {
for referencedChannel in referencedChannels {
debugPrint("Referenced channel name: \(referencedChannel.value.name)")
}
} else {
debugPrint("Message does not contain any channel references.")
}
} else {
debugPrint("Message not found")
}
}