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

```java label="Java"
// Create a pinned message
chat.sendMessage(channelType, channelId, SendMessageRequest.builder()
    .message(MessageRequest.builder()
        .text("Important announcement")
        .pinned(true)
        .pinExpires(new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'").parse("2077-01-01T00:00:00Z"))
        .userID(userId)
        .build())
    .build()).execute();

// Pin an existing message
chat.updateMessage(messageId, UpdateMessageRequest.builder()
    .message(MessageRequest.builder()
        .pinned(true)
        .userID(userId)
        .build())
    .build()).execute();

// Unpin message
chat.updateMessage(messageId, UpdateMessageRequest.builder()
    .message(MessageRequest.builder()
        .pinned(false)
        .userID(userId)
        .build())
    .build()).execute();
```

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

</Admonition>

## Retrieving Pinned Messages

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

```java label="Java"
var resp = chat.getOrCreateChannel("type", "id",
    GetOrCreateChannelRequest.builder().state(true).build()).execute();
var messages = resp.getData().getPinnedMessages();
```

## Paginating Pinned Messages

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

```java label="Java"
chat.search(SearchRequest.builder()
    .Payload(SearchPayload.builder()
        .filterConditions(Map.of("cid", "messaging:general"))
        .messageFilterConditions(Map.of("pinned", true))
        .build())
    .build()).execute();
```


---

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

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