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.

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.

For # to be treated as a channel reference in the message, you must first map a given # character to a specific channel. Without it, # will be treated as a regular string and will be shown as plain text.

You can implement channel referencing in your app similarly to user @mentions.

Requires App Context

To reference channels from a keyset, you must enable App Context for your app's keyset in the Admin Portal.

A sample implementation of channel referencing could include the following:

  • Configure how a message with referenced channels (called "draft message") should behave - what should be the maximum number of channel references allowed in a single message.
  • Add the onChange listener for the message input to track if there are any channel references in a message to handle.
  • Decide how many suggested channels you want to show after typing the required string (# and at least three characters).
  • Add channels to the list of referenced channels or remove channels when at least one character of the referenced channel is deleted.
  • Handle draft messages publishing (text with referenced channel metadata).
  • Optionally, show referenced channels in the published message as links.

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.

Create message with channel references​

createMessageDraft() creates a message draft with referenced channels.

Whenever you reference a channel, this channel is added to the list of all referenced channels inside the MessageDraft object. This draft contains the text content with all additional information, such as referenced channel names (#) or user mentions (@). Once you send this message (send()), that information gets stored in the message metadata.

For channel referencing implementation, you can use the createMessageDraft() method and the channelLimit option to configure the maximum number of channels you allow to reference in a single message - the default option is set to 10 and you can change it to a maximum of 100 channels.

Method signature​

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

Basic usage​

Set the maximum number of allowed channel references in a single message draft to 20.

// reference the "channel" object
const channel = await chat.getChannel("support")
channel.createMessageDraft({
    channelLimit: 20
})

Track channel references​

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

icon

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​

ParameterTypeRequiredDefaultDescription
textstringYesn/aAt least a 3-letter string typed in after # with the channel name you want to reference.
limitnumberYes10Maximum 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​

TypeDescription
Promise<Channel[]>Returned array of Channel objects.

Basic usage​

Return five channels that have names starting with Sup.

chat.getChannelSuggestions(
  "You can ask this question on #Sup",
  { limit: 5  }
)

Add referenced channel​

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​

ParameterTypeRequiredDefaultDescription
channelChannelYesn/aChannel object that you want to map to a given occurrence of # in the message.
channelNameOccurrenceIndexnumberYesn/aSpecific occurrence of # in the message (like 3) that you want to map to a given channel.

Output​

TypeDescription
voidMethod 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​

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​

ParameterTypeRequiredDefaultDescription
channelNameOccurrenceIndexnumberYesn/aSpecific occurrence of # in the message (like 3) that you want to unmap from a given channel.

Output​

TypeDescription
voidMethod 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.

icon

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.

const newMessageDraft = channel.createMessageDraft({ channelLimit: 5 })
const suggestedChannels = []
const lastAffectedChannelOccurrenceIndex = -1

async handleInput(text: string) {
  const response = await newMessageDraft.onChange(text)
  suggestedChannels = response.channels.suggestedChannels
  lastAffectedChannelOccurrenceIndex = response.channels.nameOccurrenceIndex
}

handleInput("Please contact #Support")
newMessageDraft.addReferencedChannel(suggestedChannels[0], lastAffectedChannelOccurrenceIndex)
handleInput("Please contact #Support or #Support-Agents")
newMessageDraft.addReferencedChannel(suggestedChannels[0], lastAffectedChannelOccurrenceIndex)

show all 16 lines

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​

PropertyTypeDescription
referencedChannelsChannel[]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

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 a link to a PubNub channel under each channel reference.

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

Modify display color​

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

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

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

For examples of how you can customize linked referenced channel previews, refer to the getMessageElements() method that's similar in structure but is meant for final, published messages.

Alternative method

This method is deprecated. Use getMessageElements() instead.

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

Other examples​

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

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

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

Modify display color​

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

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
Last updated on
Related Resources
On this page