Reference channels

Version 2 functionality

All operations relative to message drafts in this document are based on the version 2 of the message draft functionality, unless otherwise specified.

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 mentionType values.

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.

Interactive demo

Check how a sample implementation could look like in a React app showcasing channel references and user mentions.

Want to implement something similar?

Read how to do that or go straight to the demo's source code.

Test it out

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

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.

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.

Basic usage

Create the Hello Alex! I have sent you this link on the #offtopic channel. message where #offtopic is a channel reference.

// Create a message draft
messageDraft = channel.createMessageDraftV2({ 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

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(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
messageDraft = channel.createMessageDraftV2({ 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

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.

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

Use the referencedChannels getter method to return all channel names referenced in a message.

Method signature

This method has the following signature:

message.referencedChannels: Channel[]

Properties

Property	Type	Description
referencedChannels	Channel[]	Returned array of Channel objects.

Basic usage

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

// 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 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() attached to the input message lets you control if there are any # in the text followed by at least three letters.

If there are hashtags (#), you can configure your app to return suggested channels whose names match the typed text and later add these suggested channels to the correct #.

Under the hood

Method signature

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

Basic usage

Track channel references for messages on the current channel.

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

getChannelSuggestions() returns all suggested channels that match the provided 3-letter string from your app's keyset.

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

This method takes the following signature:

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

Input

Parameter	Type	Required	Default	Description
text	string	Yes	n/a	At least a 3-letter string typed in after # with the channel name you want to reference.
limit	number	Yes	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.

Basic usage

Return five channels that have names starting with Sup.

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

Add referenced channel

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.

For # to be treated as a channel reference in the message, you must first map a given # character to a specific channel. Use the addReferencedChannel() method to create this mapping. Without it, # will be treated as a regular string and will be shown as plain text.

Method signature

This method has the following signature:

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

Input

Parameter	Type	Required	Default	Description
channel	Channel	Yes	n/a	Channel object that you want to map to a given occurrence of # in the message.
channelNameOccurrenceIndex	number	Yes	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.

Basic usage

Map #Support to the third # in the message.

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

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.

Use the removeReferencedChannel() method to remove the mapping between a specific occurrence of #Some-channel in the message and a given channel. Once you remove at least one character from a referenced channel, this reference is automatically deleted, and #Some-channel becomes a regular string.

Method signature

This method has the following signature:

messageDraft.removeReferencedChannel(
    channelNameOccurrenceIndex: number
): void

Input

Parameter	Type	Required	Default	Description
channelNameOccurrenceIndex	number	Yes	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.

Basic usage

Remove #Support from the third # in the message.

messageDraft.removeReferencedChannel(3)

Send message with channel references

send() publishes the text message with all referenced channels.

Under the hood

Method signature

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

Basic usage

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

// Create a message draft
messageDraft = channel.createMessageDraftV2({ 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

Use the referencedChannels getter method to return all channel names referenced in a message.

Method signature

This method has the following signature:

message.referencedChannels: Channel[]

Properties

Property	Type	Description
referencedChannels	Channel[]	Returned array of Channel objects.

Basic usage

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

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

getMessageElements() renders a referenced channel (like #Support) as a clickable link in the final, published message. You can create custom functions if you want to customize how these referenced channels render.

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.

Basic usage

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

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

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

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>

show all 20 lines

Vue

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

show all 27 lines

Angular

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:

show all 33 lines

Modify display color

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

React

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 "";

show all 16 lines

React Native

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

show all 19 lines

Vue

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

show all 31 lines

Angular

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 {

show all 21 lines

Show referenced channel preview

getMessagePreview() returns a list of message draft elements, such as: text, referenced channels, user mentions, plain URLs, or text URLs. You can decide how you want to render these elements in your app and format them separately. For example, you could use this method to map referenced channels in your message to render as links to these channels.

Method signature

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

Basic usage

Show a preview of the linked referenced channel.

messageDraft.getMessagePreview()