# Pinned Messages

Pinned messages highlight important content in a channel. Use them for announcements, key information, or temporarily promoted content. Each channel can have multiple pinned messages, with optional expiration times.

## Pinning and Unpinning Messages

Pin an existing message using `pinMessage`, or create a pinned message by setting `pinned: true` when sending.

```ruby label="Ruby"
require 'getstream_ruby'
Models = GetStream::Generated::Models

# Create a pinned message
response = client.chat.send_message('messaging', channel_id, Models::SendMessageRequest.new(
  message: Models::MessageRequest.new(
    text: 'Important announcement',
    pinned: true,
    user_id: user_id
  )
))

# Pin an existing message using partial update
client.chat.update_message_partial(response.message.to_h['id'], Models::UpdateMessagePartialRequest.new(
  set: { 'pinned' => true, 'pin_expires' => '2077-01-01T00:00:00Z' },
  user_id: user_id
))

# Unpin message
client.chat.update_message_partial(response.message.to_h['id'], Models::UpdateMessagePartialRequest.new(
  set: { 'pinned' => false },
  user_id: user_id
))
```

### Pin Parameters

| Name        | Type    | Description                                                            | Default | Optional |
| ----------- | ------- | ---------------------------------------------------------------------- | ------- | -------- |
| pinned      | boolean | Whether the message is pinned                                          | false   | ✓        |
| pinned_at   | string  | Timestamp when the message was pinned                                  | -       | ✓        |
| pin_expires | string  | Timestamp when the pin expires. Null means the message does not expire | null    | ✓        |
| pinned_by   | object  | The user who pinned the message                                        | -       | ✓        |

<Admonition type="info">

Pinning a message requires the `PinMessage` permission. See [Permission Resources](https://getstream.io/chat/docs/ruby/permissions-reference/) and [Default Permissions](https://getstream.io/chat/docs/ruby/chat-permission-policies/) for details.

</Admonition>

## Retrieving Pinned Messages

Query a channel to retrieve the 10 most recent pinned messages from `pinned_messages`.

```ruby label="Ruby"
require 'getstream_ruby'
Models = GetStream::Generated::Models

response = client.chat.get_or_create_channel('messaging', channel_id, Models::ChannelGetOrCreateRequest.new(
  state: true
))
pinned_messages = response.pinned_messages
```

## Paginating Pinned Messages

Use the dedicated pinned messages endpoint to retrieve all pinned messages with pagination.

```js label="JavaScript"
// First page, newest first
const page1 = await channel.getPinnedMessages({ limit: 10 }, { pinned_at: -1 });

// Next page
const lastMsg = page1.messages[page1.messages.length - 1];
const page2 = await channel.getPinnedMessages(
  { limit: 10, id_lt: lastMsg.id },
  { pinned_at: -1 },
);

// Oldest first
const ascPage = await channel.getPinnedMessages({ limit: 10 });
const ascLastMsg = ascPage.messages[ascPage.messages.length - 1];
const ascPage2 = await channel.getPinnedMessages({
  limit: 10,
  id_gt: ascLastMsg.id,
});
```


---

This page was last updated at 2026-08-07T20:38:02.957Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/ruby/pinned-messages/](https://getstream.io/chat/docs/ruby/pinned-messages/).