Pinned messages

LAST EDIT Mar 18 2024

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

Copied!

An existing message can be updated to be pinned or unpinned by using the .pinMessage and .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.

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 messages

Copied!

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

To learn more about channels you can visit Querying Channels page

Paginate over all pinned messages

Copied!

Stream Chat also provides dedicated endpoint for pinned messages of the channel which can be used to retrieve all pinned messages page by page: