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 #
.
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(
"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
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
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.
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 linesGet 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
- React Native
- Vue
- Angular
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 "";
}
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<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>
<!-- add a space after channel reference -->
</template>
</span>
</div>
</template>
<script>
export default {
data() {
return {
show all 27 linesimport { 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>
</ng-container>
<ng-container *ngIf="messagePart.type!=='channelReference'">
<!-- render other message elements, like text:
show all 33 linesModify display color
Change the display color of the referenced channels from the default blue to green.
- React
- React Native
- Vue
- Angular
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 linesimport 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<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 linesimport { 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 linesShow 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.
Show referenced channel as link (deprecated)
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 channel links
Add a link to a PubNub channel under each channel reference.
- React
- React Native
- Vue
- Angular
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 "";
}
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<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>
<!-- add a space after channel reference -->
</template>
</span>
</div>
</template>
<script>
export default {
data() {
return {
show all 27 linesimport { 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>
</ng-container>
<ng-container *ngIf="messagePart.type!=='channelReference'">
<!-- render other message elements, like text:
show all 33 linesModify display color
Change the display color of the referenced channels from the default blue to green.
- React
- React Native
- Vue
- Angular
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 linesimport 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<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 linesimport { 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