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
val pinExpirationDate = Calendar.getInstance().apply { set(2077, 1, 1) }.time
val message = Message(
  text = "Important announcement",
  pinned = true,
  pinExpires = pinExpirationDate
)

channel.sendMessage(message).enqueue { /* ... */ }

// Pin message for 120 seconds
channel.pinMessage(message, timeout = 120).enqueue { /* ... */ }

// Pin with a specific expiration date
channel.pinMessage(message, expirationDate = pinExpirationDate).enqueue { /* ... */ }

// Pin indefinitely (remove expiration)
channel.pinMessage(message, expirationDate = null).enqueue { /* ... */ }

// Unpin message
channel.unpinMessage(message).enqueue { /* ... */ }

Pin Parameters

NameTypeDescriptionDefaultOptional
pinnedbooleanWhether the message is pinnedfalse✓
pinned_atstringTimestamp when the message was pinned-✓
pin_expiresstringTimestamp when the pin expires. Null means the message does not expirenull✓
pinned_byobjectThe user who pinned the message-✓

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.

channelClient.query(QueryChannelRequest()).enqueue { result ->
  if (result is Result.Success) {
    val pinnedMessages: List<Message> = result.value.pinnedMessages
  } else {
    // Handle Result.Failure
  }
}

Paginating Pinned Messages

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

// First page, newest first
channelClient.getPinnedMessages(
  limit = 10,
  sort = QuerySortByField.descByName("pinnedAt"),
  pagination = PinnedMessagesPagination.BeforeDate(
    date = Date(),
    inclusive = false,
  ),
).enqueue { result ->
  if (result is Result.Success) {
    val pinnedMessages: List<Message> = result.value
  } else {
    // Handle Result.Failure
  }
}

// Next page using pinnedAt from previous response
val nextDate = Date()
channelClient.getPinnedMessages(
  limit = 10,
  sort = QuerySortByField.descByName("pinnedAt"),
  pagination = PinnedMessagesPagination.BeforeDate(
    date = nextDate,
    inclusive = false,
  ),
).enqueue { /* ... */ }
Previous
Reactions
Next
Message Search