---
source_url: https://www.pubnub.com/docs/chat/swift-chat-sdk/build/features/channels/references
title: Reference channels
updated_at: 2026-06-12T11:23:12.959Z
---

> 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` types.
:::

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/swift-chat-sdk/build/features/users/mentions) and [links](https://www.pubnub.com/docs/chat/swift-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

Add channel references with `#` followed by at least three letters of the channel name (e.g., `#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/swift-chat-sdk/build/features/messages/drafts#add-message-element) method for details.

### Sample code

:::tip 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.

```swift
// Assumes a "ChatImpl" reference 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

Remove a channel reference from a [draft message](https://www.pubnub.com/docs/chat/swift-chat-sdk/build/features/messages/drafts) with `removeMention()`.

### 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/swift-chat-sdk/build/features/messages/drafts#remove-message-element) method for details.

:::warning Offset value
Provide the exact position of the first character; otherwise the element is not 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.

```swift
// Assumes a "MessageDraftImpl" reference named "messageDraft"
  
// 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 matching channels from your keyset for the 3-letter string typed after `#`.

##### Single listener

The listener returns suggestions for channel references, user mentions, and links using:

* `messageElements` - current draft state (text, mentions, references, URLs) in order
* `suggestedMentions` - `Future` providing potential mentions asynchronously

Typing `#Sup` returns channels like `Support` or `Support-Agents`. Default: 10 suggestions (max: 100).

### Method signature

You must add a message elements listener to receive channel suggestions.

Refer to the [addChangeListener()](https://www.pubnub.com/docs/chat/swift-chat-sdk/build/features/messages/drafts#add-message-draft-change-listener) method for details.

### Sample code

Create a message draft and add a change listener to listen for channel references.

```swift
// Assumes a "ChannelImpl" reference named "channel"
  
// Create a message draft
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
        updateMentionList(with: mentions)
      case .failure(let error):
        print("Error retrieving suggestions: \(error)")
      }
    }
  }
}
  
// Instantiate the listener
let listener = DraftChangeListener()
// Add the listener to the message draft
messageDraft.addChangeListener(listener)
  
func updateUI(with: [MessageElement]) {}
func updateMentionList(with: [SuggestedMention]) {}
```

## Get referenced channels

Return all channel names referenced in a message with `getMessageElements()`.

### Method signature

This method has the following signature:

```swift
message.getMessageElements()
```

### Sample code

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

```swift
// Assumes a "MessageImpl" reference 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
    }
  default:
    return false
  }
}
  
if containsChannelReference {
  print("The message contains channel references.")
} else {
  print("The message does not contain any channel references.")
}
```

## Get referenced channels (deprecated)

Return all channel names referenced in a message with the `referencedChannels` getter.

### Method signature

This method has the following signature:

```swift
message.referencedChannels
```

### Sample code

:::tip 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.

```swift
// Assumes a "ChannelImpl" reference 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")
  }
}
```