---
id: pinned_messages
sidebar_position: 22
title: Pinned Messages
---

Pinning A Message In A Channel

Pinned messages allow users to highlight important messages, make announcements, or temporarily promote content.
Pinning a message is, by default, restricted to certain user roles, but this is flexible.
Each channel can have multiple pinned messages and these can be created or updated with or without an expiration.

### Pin and unpin a message

An existing message can be updated to be pinned or unpinned by using the `channel.pinMessage` and `channel.unpinMessage` methods.
Or a new message can be pinned when it is sent by setting the `pinned` and `pin_expires` fields when using `channel.sendMessage`.

```dart
// create pinned message
final message = await channel
    .sendMessage(Message(
      text: 'my message',
      pinned: true,
      pinExpires: DateTime.now().add(Duration(days: 3)),
    ))
    .then((resp) => resp.message);

// unpin message
await channel.unpinMessage(message);

// pin message for 120 seconds
await channel.pinMessage(message, 120);

// change message expiration to 2077
await channel.pinMessage(message, DateTime(2077));

// remove expiration date from pinned message
await channel.pinMessage(message, null);
```

To pin the message user has to have PinMessage permission.
You can find the list of permissions and defaults in Permission Resources and Default Permissions sections

### Retrieve pinned messages

You can easily retrieve the last 10 pinned messages from the `channel.pinned_messages` field:

```dart
// get channel state
final channelState = await channel.query();

// get pinned messages from it
final pinnedMessages = channelState.pinnedMessages;
```

To learn more about channels you can visit Querying Channels page
Search for all pinned messages

Stream Chat also provides search filter in case if you need to display more than 10 pinned messages in specific channel.

```dart
// list all pinned messages of the channel
final response = await channel.search(
    messageFilters: Filter.equal('pinned', true),
);
```