# 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.

```go label="Go"
// Create a pinned message
messageResp, err := channel.SendMessage(ctx, &getstream.SendMessageRequest{
  Message: getstream.MessageRequest{
    Text:   getstream.PtrTo("Important announcement"),
    Pinned: getstream.PtrTo(true),
    UserID: getstream.PtrTo(userID),
  },
})

// Pin an existing message using partial update
client.Chat().UpdateMessagePartial(ctx, msgID, &getstream.UpdateMessagePartialRequest{
  Set:    map[string]any{"pinned": true, "pin_expires": "2077-01-01T00:00:00Z"},
  UserID: getstream.PtrTo(userID),
})

// Unpin message
client.Chat().UpdateMessagePartial(ctx, msgID, &getstream.UpdateMessagePartialRequest{
  Set:    map[string]any{"pinned": false},
  UserID: getstream.PtrTo(userID),
})
```

### 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/go-golang/permissions-reference/) and [Default Permissions](https://getstream.io/chat/docs/go-golang/chat-permission-policies/) for details.

</Admonition>

## Retrieving Pinned Messages

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

```go label="Go"
resp, err := channel.GetOrCreate(ctx, &getstream.GetOrCreateChannelRequest{
  State: getstream.PtrTo(true),
})
pinnedMessages := resp.Data.PinnedMessages
```

## 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:01.359Z.

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