64 lines
2.0 KiB
Plaintext
64 lines
2.0 KiB
Plaintext
---
|
|
id: pinned_messages
|
|
sidebar_position: 22
|
|
title: Pinned Messages
|
|
---
|
|
|
|
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),
|
|
);
|
|
``` |