---
source_url: https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/references
title: Reference channels
updated_at: 2026-06-17T11:36:32.371Z
---

> 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

:::warning Version 2 functionality
Operations in this document use message draft version 2 unless otherwise specified.
:::

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

:::note Requires App Context
Enable [App Context](https://youtu.be/9UEoSlngpYI) for your keyset in the [Admin Portal](https://admin.pubnub.com/).
:::

## Interactive demo

Sample React app demonstrating channel references and [user mentions](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions).

:::tip Want to implement something similar?
[Implementation guide](https://www.pubnub.com/how-to/chat-sdk-mention-users/) | [Source code](https://github.com/PubNubDevelopers/Chat-SDK-How-Tos/tree/main/mentions)
:::

### Test it out

Type in `#EME` in the input field and select one of the suggested channels to reference.

## Add channel references

Add channel references with `#` followed by at least three letters of the channel name (e.g., `#Sup`).

##### Under the hood

`send()` calls Pub/Sub API and the JavaScript SDK [publish()](https://www.pubnub.com/docs/sdks/javascript/api-reference/publish-and-subscribe#publish) method.

### Method signature

You can add a channel reference by calling the `addMention()` method with the `mentionType` of `channelReference`.

Refer to the [addMention()](https://www.pubnub.com/docs/chat/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.

```ts
// Create a message draft
messageDraft = channel.createMessageDraft({ userSuggestionSource: "global" })

// Add initial text
messageDraft.update("Hello Alex! I have sent you this link on the #offtopic channel.")

// Add a user mention to the string "Alex"
messageDraft.addMention(45, 9, "channelReference", "group.offtopic")
```

## Remove channel references

Remove a channel reference from a [draft message](https://www.pubnub.com/docs/chat/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/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.

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

// remove the channel reference
messageDraft?.removeMention(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()` - `Promise` 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/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.

```ts
// Create a message draft
messageDraft = channel.createMessageDraft({ userSuggestionSource: "global" })
// Add the listener
const listener = async function(state) {
    elements.push(state.messageElements);
    if (elements.length === 3) {
        resolve();
        return;
    }
    let mentions = await state.suggestedMentions;
    messageDraft.insertSuggestedMention(mentions[0], mentions[0].replaceWith);
};
messageDraft.addChangeListener(listener)
```

## Get referenced channels

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

### Method signature

This method has the following signature:

```js
message.getMessageElements()
```

### Sample code

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

```ts
// reference the "incident-management" channel
const channel = await chat.getChannel("incident-management")
// get the timetoken of the last message on the channel
const messageTimetoken = (await channel.getHistory({count: 1})).messages[0].timetoken
// return the message object
const message = await channel.getMessage("16200000000000001")
// Retrieve the message elements
let messageElements = message.getMessageElements()
```

## Get referenced channels (deprecated)

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

#### Method signature

This method has the following signature:

```ts
message.referencedChannels: Channel[]
```

##### Properties

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| referencedChannels | Channel[] | Optional |  | Returned array of `Channel` objects. |

#### Sample code

Check if the last message on the `support` channel contains any channel references.

```ts
// reference the "support" channel
const channel = await chat.getChannel("support")
// get the last message on the channel
const message = (await channel.getHistory({count: 1})).messages[0]
// check if it contains any channel references
message.referencedChannels
```

## Track channel references

### Version 2

In message draft v2, use the [Message draft state](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/drafts#add-message-draft-change-listener) listener to track channel references.

### Version 1

:::warning Version 1 functionality
This method is available in message draft version 1 only. For more information on methods available in versions 1 and 2, refer to [Message Draft](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/message-draft).
:::

`onChange()` detects `#` followed by at least three letters. Configure your app to [return suggested channels](#get-channel-suggestions) matching the text and [add them](#add-referenced-channel) to the message.

##### Under the hood

`onChange()` calls PubNub App Context API and the JavaScript SDK [getAllChannelMetadata()](https://www.pubnub.com/docs/sdks/javascript/api-reference/objects#get-metadata-for-all-channels) method.

### Method signature

Head over to the [Mentions](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#track-mentions) documentation for details on the method signature, input, and output parameters.

### Sample code

Track channel references for messages on the current channel.

```ts
const newMessageDraft = channel.createMessageDraft()

  async handleInput(text: string) {
    const response = await newMessageDraft.onChange(text)

    const suggestedChannels = response.channels.suggestedChannels
    const lastAffectedChannelOccurrenceIndex = response.channels.channelOccurrenceIndex
  }
```

## Get channel suggestions

Get matching channel suggestions with `getChannelSuggestions()`.

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

### Method signature

This method takes the following signature:

```ts
chat.getChannelSuggestions(
  text: string,
  {
    limit: number
  }
): Promise<Channel[]>
```

#### Input

| Parameter | Description |
| --- | --- |
| `text` *Type: `string`Default: n/a | At least a 3-letter string typed in after `#` with the channel name you want to reference. |
| `limit` *Type: `number`Default: `10` | Maximum number of returned channel names that match the typed 3-letter suggestion. The default value is set to `10`, and the maximum is `100`. |

#### Output

| Type | Description |
| --- | --- |
| `Promise<Channel[]>` | Returned array of `Channel` objects. |

### Sample code

Return five channels that have names starting with `Sup`.

```ts
chat.getChannelSuggestions(
  "Sup",
  { limit: 5  }
)
```

## Add referenced channel

:::warning Version 1 functionality
Available in message draft version 1 only. See [Message Draft](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/message-draft) for version differences.
:::

Map a `#` character to a specific channel with `addReferencedChannel()`. Without this mapping, `#` displays as plain text.

### Method signature

This method has the following signature:

```ts
messageDraft.addReferencedChannel(
  channel: Channel,
  channelNameOccurrenceIndex: number
): void
```

#### Input

| Parameter | Description |
| --- | --- |
| `channel` *Type: `Channel`Default: n/a | [Channel object](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/channel) that you want to map to a given occurrence of `#` in the message. |
| `channelNameOccurrenceIndex` *Type: `number`Default: n/a | Specific occurrence of `#` in the message (like `3`) that you want to map to a given channel. |

#### Output

| Type | Description |
| --- | --- |
| `void` | Method returns no output data. |

### Sample code

Map `#Support` to the third `#` in the message.

```ts
const response = await messageDraft.onChange("Contact #Sup")
// let's say it returns { suggestedChannels: [channel Support, someOtherChannel...], channelNameOccurrenceIndex: 0 }
messageDraft.addReferencedChannel(response.suggestedChannels[0], response.channelNameOccurrenceIndex)
```

## Remove referenced channel

:::warning Version 1 functionality
Available in message draft version 1 only. See [Message Draft](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/message-draft) for version differences.
:::

Remove the mapping between `#Some-channel` and a channel with `removeReferencedChannel()`. Editing the reference text also removes the mapping automatically.

### Method signature

This method has the following signature:

```ts
messageDraft.removeReferencedChannel(
    channelNameOccurrenceIndex: number
): void
```

#### Input

| Parameter | Description |
| --- | --- |
| `channelNameOccurrenceIndex` *Type: `number`Default: n/a | Specific occurrence of `#` in the message (like `3`) that you want to unmap from a given channel. |

#### Output

| Type | Description |
| --- | --- |
| `void` | Method returns no output data. |

### Sample code

Remove `#Support` from the third `#` in the message.

```ts
messageDraft.removeReferencedChannel(3)
```

## Send message with channel references

Publish the message with all channel references using `send()`.

##### Under the hood

`send()` calls Pub/Sub API and the JavaScript SDK [publish()](https://www.pubnub.com/docs/sdks/javascript/api-reference/publish-and-subscribe#publish) method.

### Method signature

Head over to the [Drafts](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/drafts#send-a-draft-message) documentation for details on the method signature, input, and output parameters.

### Sample code

Send the previously drafted message in which you reference two channels `#Support` and `#Support-Agents`.

```ts
// Create a message draft
messageDraft = channel.createMessageDraft({ userSuggestionSource: "global" })

// Add the text
messageDraft.update("Hello Alex! I have sent you this link on the #Support and #Support-Agents channels.")

// Add a first URL mention 
messageDraft.addMention(44, 8, "channelReference", "group.support")

// Add a second URL mention 
messageDraft.addMention(56, 15, "channelReference", "group.support-agents")

messageDraft.send()
```

## Get referenced channels

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

### Method signature

This method has the following signature:

```ts
message.referencedChannels: Channel[]
```

#### Properties

| Property | Description |
| --- | --- |
| `referencedChannels`Type: `Channel[]` | Returned array of `Channel` objects. |

### Sample code

Check if the last message on the `support` channel contains any channel references.

```ts
// reference the "support" channel
const channel = await chat.getChannel("support")
// get the last message on the channel
const message = (await channel.getHistory({count: 1})).messages[0]
// check if it contains any channel references
message.referencedChannels
```

## Show referenced channel as link

Render referenced channels (like `#Support`) as clickable links with `getMessageElements()`. Create custom functions to customize rendering.

This is the same method that lets you [render plain or text links](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/links#render-urls) and [show mentions as links](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#show-mention-as-link).

### Method signature

Head over to the [Links](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/links#render-urls) documentation for details on the method signature, input, and output parameters.

### Sample code

Show all linked referenced channels in a message as clickable links.

```ts
message.getMessageElements()
```

### Other examples

Check how you can customize the default behavior of the Chat SDK methods and render the referenced channels differently.

#### Add channel links

Add a link to a PubNub channel under each channel reference.

##### React

```ts
const renderMessagePart = (messagePart: MixedTextTypedElement) => {
  if (messagePart.type === "channelReference") {
    // assuming messagePart.content.id is the channel ID
    const channelUrl = `https://pubnub.com/channels/${messagePart.content.id}`;
    return (
      <span>
        <a href={channelUrl}>{messagePart.content.name}</a>
        {" "}
        {/* add a space after channel reference */}
      </span>
    );
  }
  return "";
}
```

##### React Native

```jsx
import React from 'react';
import { Text, Linking, View } from 'react-native';

const renderMessagePart = (messagePart) => {
  if (messagePart.type === "channelReference") {
    const channelUrl = `https://pubnub.com/channels/${messagePart.content.id}`;
    return (
      <View>
        <Text>
          <Text onPress={() => Linking.openURL(channelUrl)}>
            {messagePart.content.name}
          </Text>
          {" "}
        </Text>
      </View>
    );
  }
  return null;
}
```

##### Vue

```ts
<template>
  <div>
    <span v-for="messagePart in messageParts" :key="messagePart.content.id">
      <template v-if="messagePart.type === 'channelReference'">
        <a :href="getChannelUrl(messagePart.content.id)">{{ messagePart.content.name }}</a>
        &nbsp; <!-- add a space after channel reference -->
      </template>
    </span>
  </div>
</template>

<script>
export default {
  data() {
    return {
      messageParts: [
        // array of message parts
      ]
    };
  },
  methods: {
    getChannelUrl(channelId) {
      return `https://pubnub.com/channels/${channelId}`;
    },
  },
};
</script>
```

##### Angular

```ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-message',
  template: `
    <span>
      <ng-container *ngFor="let messagePart of messageParts">
        <ng-container *ngIf="messagePart.type==='channelReference'">
          <a [href]="getChannelUrl(messagePart.content.id)">
            {{ messagePart.content.name }}
          </a>
          &nbsp;
        </ng-container>
        <ng-container *ngIf="messagePart.type!=='channelReference'">
        <!-- render other message elements, like text:
        <ng-container *ngIf="messagePart.type === 'text'>
          <span style="color:green;">{{messagePart.content.text}}</span>
        </ng-container>"-->
        </ng-container>
      </ng-container>
    </span>
  `
})
export class MessageComponent {
  messageParts: MixedTextTypedElement[] = [
    // assuming you have an array of message parts
  ];

  getChannelUrl(id: string): string {
    // assuming you have a function to generate the PubNub channel URL
    return `https://pubnub.com/channels/${id}`;
  }
}
```

#### Modify display color

Change the display color of the referenced channels from the default blue to green.

##### React

```ts
const renderMessagePart = (messagePart: MixedTextTypedElement) => {
  if (messagePart.type === "channelReference") {
    const linkStyle = {
      color: "green", // set the color to green
      // add any other desired styles here, e.g., textDecoration: "underline"
    };

    return (
      <a href={`https://pubnub.com/${messagePart.content.id}`} style={linkStyle}>
        {messagePart.content.name}
      </a>
    );
  }

  return "";
}
```

##### React Native

```tsx
import React from 'react';
import { Text } from 'react-native';

const renderMessagePart = (messagePart) => {
  if (messagePart.type === "channelReference") {
    const linkStyle = {
      color: "green", // set the color to green
      // add any other desired styles here, e.g., textDecorationLine: "underline"
    };

    return (
      <Text style={linkStyle}>
        {messagePart.content.name}
      </Text>
    );
  }

  return null;
}
```

##### Vue

```html
<template>
  <div>
    <span v-for="messagePart in messageParts" :key="messagePart.id">
      <a v-if="messagePart.type === 'channelReference'"" :href="`https://pubnub.com/${messagePart.content.id}`" :style="linkStyle">
        {{ messagePart.content.name }}
      </a>
      <!-- render other message elements, like text:
      <span v-else>
        <span :style="color: green;" v-if="messagePart.type === 'text'">{{ messagePart.content.text }}</span>
      </span> -->
    </span>
  </div>
</template>

<script>
export default {
  data() {
    return {
      messageParts: [
        { type: "text", content: "Hello" },
        { type: "channelReference", content: { id: 1, name: "Support" } },
        { type: "text", content: "!" },
      ],
      linkStyle: {
        color: "green", // set the color to green
        // add any other desired styles here, e.g., textDecoration: "underline"
      },
    };
  },
};
</script>
```

##### Angular

```ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-message',
  template: `
    <ng-container *ngFor="let messagePart of messageParts">
      <a *ngIf="messagePart.type === 'channelReference'"
         [href]="'https://pubnub.com/' + messagePart.content.id"
         style="color: green;">
        {{ messagePart.content.name }}
      </a>
    </ng-container>
  `,
})
export class MessageComponent {
  messageParts: MixedTextTypedElement[];

  constructor() {
    // initialize messageParts here
  }
}
```

## Show referenced channel preview

Get a list of message draft elements (text, referenced channels, [user mentions](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#show-linked-mention-preview), [URLs](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/links)) with `getMessagePreview()`. Format each element type separately, such as rendering channel references as links.

### Method signature

Head over to the [Links](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/links#show-text-link-preview) documentation for details on the method signature, input, and output parameters.

### Sample code

Show a preview of the linked referenced channel.

```ts
messageDraft.getMessagePreview()
```