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.

// 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	-	✓

Info:

Pinning a message requires the PinMessage permission. See Permission Resources and Default Permissions for details.

Retrieving Pinned Messages

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

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.

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