Pinned messages

Pin messages to channels for easy access. Only one message can be pinned per channel at a time.

Use cases:

• Essential announcements and updates
• Action items and reminders
• Polls and persistent questions

Requires App Context and Message Persistence

Enable App Context and Message Persistence in the Admin Portal.

Pin

pin() and pinMessage() attach a message to a channel. Call pin() on a message object or pinMessage() on a channel object.

pin() and pinMessage() call PubNub App Context API and the JavaScript SDK setChannelMetadata() method.

Under the hood

Alternatively, you can also use other Chat SDK methods to pin a message in a thread (thread message) to the thread channel or the parent channel.

Method signature

These methods take the following parameters:

• pin()

  1message.pin(): Promise<void>

• pinMessage()

  1channel.pinMessage(
  2    message: Message
  3): Promise<Channel>

Input

Parameter	Required in pin()	Required in pinMessage()	Description
message Type: Message Default: n/a	No	Yes	Message object that you want to pin to the selected channel.

Output

Type	In pin()	In pinMessage()	Description
Promise<void>	Yes	No	Method returns no output data.
Promise<Channel>	No	Yes	Object returning the channel metadata updated with these custom fields: pinnedMessageTimetoken to mark the timetoken when the message was pinned pinnedMessageChannelID to mark the channel on which the message was pinned to the given channel (pinning was performed either directly on the parent channel or on a thread channel).

Sample code

Pin the last message on the incident-management channel.

• pin()

  1// reference the "incident-management" channel
  2const channel = await chat.getChannel("incident-management")
  3// get the last message on the channel
  4const lastMessage = (await channel.getHistory({count: 1})).messages[0]
  5// pin the message to the channel
  6const pinnedMessage = await lastMessage.pin()

• pinMessage()

  1// reference the "incident-management" channel
  2const channel = await chat.getChannel("incident-management")
  3// get the last message on the channel
  4const lastMessage = (await channel.getHistory({count: 1})).messages[0]
  5// pin the message to the channel
  6const pinnedMessage = await channel.pinMessage(lastMessage)

Get

getPinnedMessage() retrieves the currently pinned message.

getPinnedMessage() calls PubNub App Context API and the JavaScript SDK getChannelMetadata() method.

Under the hood

Method signature

This method has the following signature:

1channel.getPinnedMessage(): Promise<Message | null>

Input

This method doesn't take any parameters.

Output

Type	Description
Promise<Message> or Promise<null>	Object returning either the pinned Message object or null value if no message is currently pinned to the channel.

Sample code

Get the message pinned to the incident-management channel.

1// reference the "incident-management" channel
2const channel = await chat.getChannel("incident-management")
3// get the pinned message
4const pinnedMessage = await channel.getPinnedMessage()

Unpin

unpinMessage() unpins a message from the channel.

unpinMessage() calls PubNub App Context API and the JavaScript SDK setChannelMetadata() method.

Under the hood

Alternatively, you can also use other Chat SDK methods to unpin a message in a thread (thread message) from the thread channel or the parent channel.

Method signature

This method has the following signature:

1channel.unpinMessage(): Promise<Channel>

Input

This method doesn't take any parameters.

Output

Type	Description
Promise<Channel>	Object returning the channel metadata updated with these custom fields: pinnedMessageTimetoken to mark the timetoken when the message was unpinned pinnedMessageChannelID to mark the channel on which the message was unpinned from the given channel (unpinning was performed either directly on the parent channel or on a thread channel).

Sample code

Unpin the message from the incident-management channel.

1// reference the "incident-management" channel
2const channel = await chat.getChannel("incident-management")
3// unpin the message from the channel
4const unpinnedMessage = await channel.unpinMessage()