React

Client SDKs

Backend SDKs

Pinned messages

LAST EDIT Feb 22 2021

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 messageCopied!

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// create pinned message 
const {message} = await channel.sendMessage({ 
  text: "my message", 
  pinned: true, 
  pin_expires: "2077-01-01T00:00:00Z", 
}); 
 
// unpin message 
await client.unpinMessage(message); 
 
// pin message for 120 seconds 
await client.pinMessage(message, 120); 
 
// change message expiration to 2077 
await client.pinMessage(message, "2077-01-01T00:00:00Z"); 
 
// remove expiration date from pinned message 
await client.pinMessage(message, null);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Create pinned message 
val pinExpirationDate = Calendar.getInstance().apply { set(2077, 1, 1) }.time 
val message = Message( 
    text = "Hey punk", 
    pinned = true, 
    pinExpires = pinExpirationDate 
) 
 
channelClient.sendMessage(message).enqueue { /* ... */ } 
 
// Unpin message 
channelClient.unpinMessage(message).enqueue { /* ... */ } 
 
// Pin message for 120 seconds 
channelClient.pinMessage(message, timeout = 120).enqueue { /* ... */ } 
 
// Change message expiration to 2077 
channelClient.pinMessage(message, expirationDate = pinExpirationDate).enqueue { /* ... */ } 
 
// Remove expiration date from pinned message 
channelClient.pinMessage(message, expirationDate = null).enqueue { /* ... */ }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Create pinned message 
Calendar calendar = Calendar.getInstance(); 
calendar.set(2077, 1, 1); 
Date pinExpirationDate = calendar.getTime(); 
 
Message message = new Message(); 
message.setText("Hey punk"); 
message.setPinned(true); 
message.setPinExpires(pinExpirationDate); 
 
channelClient.sendMessage(message).enqueue(result -> { /* ... */ }); 
 
// Unpin message 
channelClient.unpinMessage(message).enqueue(result -> { /* ... */ }); 
 
// Pin message for 120 seconds 
channelClient.pinMessage(message, 120).enqueue(result -> { /* ... */ }); 
 
// Change message expiration to 2077 
channelClient.pinMessage(message, pinExpirationDate).enqueue(result -> { /* ... */ }); 
 
// Remove expiration date from pinned message 
channelClient.pinMessage(message, null).enqueue(result -> { /* ... */ });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 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);
nametypedescriptiondefaultoptional
pinnedbooleanIndicates whether the message is pinned or notfalse✓
pinned_atstringDate when the message got pinned-✓
pin_expiresstringDate when the message pin expires. An empty value means that message does not expirenull✓
pinned_byUserThe user that pinned the message-✓
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 messagesCopied!

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

1
2
3
4
// get channel state 
const state = client.channel('messaging', channelId).query(); 
// get pinned messages from it 
const pinnedMessages = channelState.pinnedMessages
1
2
3
4
5
6
7
channelClient.query(QueryChannelRequest()).enqueue { result -> 
    if (result.isSuccess) { 
        val pinnedMessages: List<Message> = result.data().pinnedMessages 
    } else { 
        // Handle result.error() 
    } 
}
1
2
3
4
5
6
7
channelClient.query(new QueryChannelRequest()).enqueue(result -> { 
    if (result.isSuccess()) { 
        List<Message> pinnedMessages = result.data().getPinnedMessages(); 
    } else { 
        // Handle result.error() 
    } 
});
1
2
3
4
5
// 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 messagesCopied!

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

1
2
// list all pinned messages of the channel 
const response = await channel.search({pinned: true});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
val request = SearchMessagesRequest( 
    offset = 0, 
    limit = 30, 
    channelFilter = Filters.`in`("cid", "channelType:channelId"), 
    messageFilter = Filters.eq("pinned", true) 
) 
 
client.searchMessages(request).enqueue { result -> 
    if (result.isSuccess) { 
        val pinnedMessages = result.data() 
    } else { 
        // Handle result.error() 
    } 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
int offset = 0; 
int limit = 10; 
FilterObject channelFilter = Filters.in("cid", "channelType:channelId"); 
FilterObject messageFilter = Filters.eq("pinned", true); 
SearchMessagesRequest request = new SearchMessagesRequest(offset, limit, channelFilter, messageFilter); 
 
client.searchMessages(request).enqueue(result -> { 
    if (result.isSuccess()) { 
        List<Message> pinnedMessages = result.data(); 
    } else { 
        // Handle result.error() 
    } 
});
1
2
3
4
// list all pinned messages of the channel 
final response = await channel.search( 
  messageFilters: {'pinned': true}, 
);
To learn more about message search you can visit Search page

Pinned messages Feedback

Did you find the content on this page helpful?