---
source_url: https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/pinned
title: Pinned messages
updated_at: 2026-05-29T11:07:54.246Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# 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

:::note Requires App Context and Message Persistence
Enable [App Context](https://youtu.be/9UEoSlngpYI) and [Message Persistence](https://youtu.be/qLMtbINWGig) in the [Admin Portal](https://admin.pubnub.com/).
:::

## Pin

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

##### Under the hood

`pin()` and `pinMessage()` call PubNub App Context API and the JavaScript SDK [setChannelMetadata()](https://www.pubnub.com/docs/sdks/javascript/api-reference/objects#set-channel-metadata) method.

Alternatively, you can also use other Chat SDK methods to pin a message in a thread (thread message) to the [thread channel](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/threads#pin-thread-message-to-thread-channel) or the [parent channel](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/threads#pin-thread-message-to-parent-channel).

### Method signature

These methods take the following parameters:

* pin() 1message.pin(): Promise<any>
* pinMessage() 1channel.pinMessage(2 message: Message3): Promise<Channel>

#### Input

| Parameter | Required in pin() | Required in pinMessage() | Description |
| --- | --- | --- | --- |
| message | Message | Optional |  | No | Yes | [Message object](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/message) that you want to pin to the selected channel. |

#### Output

| Type | In `pin()` | In `pinMessage()` | Description |
| --- | --- | --- | --- |
| `Promise<any>` | Yes | No | Returned object with a value of any type. |
| `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" channel2const channel = await chat.getChannel("incident-management")3// get the last message on the channel4const lastMessage = (await channel.getHistory({count: 1})).messages[0]5// pin the message to the channel6const pinnedMessage = await lastMessage.pin()
* pinMessage() 1// reference the "incident-management" channel2const channel = await chat.getChannel("incident-management")3// get the last message on the channel4const lastMessage = (await channel.getHistory({count: 1})).messages[0]5// pin the message to the channel6const pinnedMessage = await channel.pinMessage(lastMessage)

## Get

`getPinnedMessage()` retrieves the currently pinned message.

##### Under the hood

`getPinnedMessage()` calls PubNub App Context API and the JavaScript SDK [getChannelMetadata()](https://www.pubnub.com/docs/sdks/javascript/api-reference/objects#get-channel-metadata) method.

### Method signature

This method has the following signature:

```ts
channel.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](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/message) or null value if no message is currently pinned to the channel. |

### Sample code

Get the message pinned to the `incident-management` channel.

```ts
// reference the "incident-management" channel
const channel = await chat.getChannel("incident-management")
// get the pinned message
const pinnedMessage = await channel.getPinnedMessage()
```

## Unpin

`unpinMessage()` unpins a message from the channel.

##### Under the hood

`unpinMessage()` calls PubNub App Context API and the JavaScript SDK [setChannelMetadata()](https://www.pubnub.com/docs/sdks/javascript/api-reference/objects#set-channel-metadata) method.

Alternatively, you can also use other Chat SDK methods to unpin a message in a thread (thread message) from the [thread channel](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/threads#unpin-thread-message-from-thread-channel) or the [parent channel](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/threads#unpin-thread-message-from-parent-channel).

### Method signature

This method has the following signature:

```ts
channel.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.

```ts
// reference the "incident-management" channel
const channel = await chat.getChannel("incident-management")
// unpin the message from the channel
const unpinnedMessage = await channel.unpinMessage()
```