Reference channels

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.

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 and links.

Requires App Context

Enable App Context for your keyset in the Admin Portal.

Interactive demo

Sample React app demonstrating channel references and user mentions.

Want to implement something similar?

Implementation guide | Source code

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

send() calls Pub/Sub API and the JavaScript SDK publish() method.

Under the hood

Method signature

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

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 a message draft
2messageDraft = channel.createMessageDraft({ userSuggestionSource: "global" })
3

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

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

Remove channel references

Remove a channel reference from a draft message 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() method for details.

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.

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

Get channel suggestions

The message elements listener returns matching channels from your keyset for the 3-letter string typed after #.

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

Single listener

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

Sample code

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

1// Create a message draft
2messageDraft = channel.createMessageDraft({ userSuggestionSource: "global" })
3// Add the listener
4const listener = async function(state) {
5    elements.push(state.messageElements);
6    if (elements.length === 3) {
7        resolve();
8        return;
9    }
10    let mentions = await state.suggestedMentions;
11    messageDraft.insertSuggestedMention(mentions[0], mentions[0].replaceWith);
12};
13messageDraft.addChangeListener(listener)

Get referenced channels

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

Method signature

This method has the following signature:

1message.getMessageElements()

Sample code

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

1// reference the "incident-management" channel
2const channel = await chat.getChannel("incident-management")
3// get the timetoken of the last message on the channel
4const messageTimetoken = (await channel.getHistory({count: 1})).messages[0].timetoken
5// return the message object
6const message = await channel.getMessage("16200000000000001")
7// Retrieve the message elements
8let 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:

1message.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.

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

Track channel references

Version 2

In message draft v2, use the Message draft state listener to track channel references.

Version 1

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.

onChange() detects # followed by at least three letters. Configure your app to return suggested channels matching the text and add them to the message.

onChange() calls PubNub App Context API and the JavaScript SDK getAllChannelMetadata() method.

Under the hood

Method signature

Head over to the Mentions documentation for details on the method signature, input, and output parameters.

Sample code

Track channel references for messages on the current channel.

1const newMessageDraft = channel.createMessageDraft()
2

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

6    const suggestedChannels = response.channels.suggestedChannels
7    const lastAffectedChannelOccurrenceIndex = response.channels.channelOccurrenceIndex
8  }

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:

1chat.getChannelSuggestions(
2  text: string,
3  {
4    limit: number
5  }
6): Promise<Channel[]>

Input

* required

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.

1chat.getChannelSuggestions(
2  "Sup",
3  { limit: 5  }
4)

Add referenced channel

Version 1 functionality

Available in message draft version 1 only. See 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:

1messageDraft.addReferencedChannel(
2  channel: Channel,
3  channelNameOccurrenceIndex: number
4): void

Input

* required

Parameter	Description
channel * Type: Channel Default: n/a	Channel object 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.

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

Remove referenced channel

Version 1 functionality

Available in message draft version 1 only. See 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:

1messageDraft.removeReferencedChannel(
2    channelNameOccurrenceIndex: number
3): void

Input

* required

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.

1messageDraft.removeReferencedChannel(3)

Send message with channel references

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

send() calls Pub/Sub API and the JavaScript SDK publish() method.

Under the hood

Method signature

Head over to the Drafts 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.

1// Create a message draft
2messageDraft = channel.createMessageDraft({ userSuggestionSource: "global" })
3

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

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

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

13messageDraft.send()

Get referenced channels

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

Method signature

This method has the following signature:

1message.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.

1// reference the "support" channel
2const channel = await chat.getChannel("support")
3// get the last message on the channel
4const message = (await channel.getHistory({count: 1})).messages[0]
5// check if it contains any channel references
6message.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 and show mentions as links.

Method signature

Head over to the Links documentation for details on the method signature, input, and output parameters.

Sample code

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

1message.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

1const renderMessagePart = (messagePart: MixedTextTypedElement) => {
2  if (messagePart.type === "channelReference") {
3    // assuming messagePart.content.id is the channel ID
4    const channelUrl = `https://pubnub.com/channels/${messagePart.content.id}`;
5    return (
6      <span>
7        <a href={channelUrl}>{messagePart.content.name}</a>
8        {" "}
9        {/* add a space after channel reference */}
10      </span>
11    );
12  }
13  return "";
14}

React Native

1import React from 'react';
2import { Text, Linking, View } from 'react-native';
3

4const renderMessagePart = (messagePart) => {
5  if (messagePart.type === "channelReference") {
6    const channelUrl = `https://pubnub.com/channels/${messagePart.content.id}`;
7    return (
8      <View>
9        <Text>
10          <Text onPress={() => Linking.openURL(channelUrl)}>
11            {messagePart.content.name}
12          </Text>
13          {" "}
14        </Text>
15      </View>
16    );
17  }
18  return null;
19}
20

show all 20 lines

Vue

1<template>
2  <div>
3    <span v-for="messagePart in messageParts" :key="messagePart.content.id">
4      <template v-if="messagePart.type === 'channelReference'">
5        <a :href="getChannelUrl(messagePart.content.id)">{{ messagePart.content.name }}</a>
6        &nbsp; <!-- add a space after channel reference -->
7      </template>
8    </span>
9  </div>
10</template>
11

12<script>
13export default {
14  data() {
15    return {
16      messageParts: [
17        // array of message parts
18      ]
19    };
20  },
21  methods: {
22    getChannelUrl(channelId) {
23      return `https://pubnub.com/channels/${channelId}`;
24    },
25  },
26};
27</script>

show all 27 lines

Angular

1import { Component } from '@angular/core';
2

3@Component({
4  selector: 'app-message',
5  template: `
6    <span>
7      <ng-container *ngFor="let messagePart of messageParts">
8        <ng-container *ngIf="messagePart.type==='channelReference'">
9          <a [href]="getChannelUrl(messagePart.content.id)">
10            {{ messagePart.content.name }}
11          </a>
12          &nbsp;
13        </ng-container>
14        <ng-container *ngIf="messagePart.type!=='channelReference'">
15        <!-- render other message elements, like text:
16        <ng-container *ngIf="messagePart.type === 'text'>
17          <span style="color:green;">{{messagePart.content.text}}</span>
18        </ng-container>"-->
19        </ng-container>
20      </ng-container>
21    </span>
22  `
23})
24export class MessageComponent {
25  messageParts: MixedTextTypedElement[] = [
26    // assuming you have an array of message parts
27  ];
28

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

show all 33 lines

Modify display color

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

React

1const renderMessagePart = (messagePart: MixedTextTypedElement) => {
2  if (messagePart.type === "channelReference") {
3    const linkStyle = {
4      color: "green", // set the color to green
5      // add any other desired styles here, e.g., textDecoration: "underline"
6    };
7

8    return (
9      <a href={`https://pubnub.com/${messagePart.content.id}`} style={linkStyle}>
10        {messagePart.content.name}
11      </a>
12    );
13  }
14

15  return "";
16}

show all 16 lines

React Native

1import React from 'react';
2import { Text } from 'react-native';
3

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

11    return (
12      <Text style={linkStyle}>
13        {messagePart.content.name}
14      </Text>
15    );
16  }
17

18  return null;
19}

show all 19 lines

Vue

1<template>
2  <div>
3    <span v-for="messagePart in messageParts" :key="messagePart.id">
4      <a v-if="messagePart.type === 'channelReference'"" :href="`https://pubnub.com/${messagePart.content.id}`" :style="linkStyle">
5        {{ messagePart.content.name }}
6      </a>
7      <!-- render other message elements, like text:
8      <span v-else>
9        <span :style="color: green;" v-if="messagePart.type === 'text'">{{ messagePart.content.text }}</span>
10      </span> -->
11    </span>
12  </div>
13</template>
14

15<script>
16export default {
17  data() {
18    return {
19      messageParts: [
20        { type: "text", content: "Hello" },
21        { type: "channelReference", content: { id: 1, name: "Support" } },
22        { type: "text", content: "!" },
23      ],
24      linkStyle: {
25        color: "green", // set the color to green
26        // add any other desired styles here, e.g., textDecoration: "underline"
27      },
28    };
29  },
30};
31</script>

show all 31 lines

Angular

1import { Component } from '@angular/core';
2

3@Component({
4  selector: 'app-message',
5  template: `
6    <ng-container *ngFor="let messagePart of messageParts">
7      <a *ngIf="messagePart.type === 'channelReference'"
8         [href]="'https://pubnub.com/' + messagePart.content.id"
9         style="color: green;">
10        {{ messagePart.content.name }}
11      </a>
12    </ng-container>
13  `,
14})
15export class MessageComponent {
16  messageParts: MixedTextTypedElement[];
17

18  constructor() {
19    // initialize messageParts here
20  }
21}

show all 21 lines

Show referenced channel preview

Get a list of message draft elements (text, referenced channels, user mentions, URLs) with getMessagePreview(). Format each element type separately, such as rendering channel references as links.

Method signature

Head over to the Links documentation for details on the method signature, input, and output parameters.

Sample code

Show a preview of the linked referenced channel.

1messageDraft.getMessagePreview()