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.
let messageController = client.messageController(
cid: .init(type: .messaging, id: "general"),
messageId: "message-id"
)
// Pin message for 120 seconds
messageController.pin(.expirationTime(120))
// Pin to a specific date
let pinExpirationDate = Calendar.current.date(byAdding: DateComponents(day: 7), to: Date())!
messageController.pin(.expirationDate(pinExpirationDate))
// Unpin message
messageController.unpin()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 | - | ✓ |
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.
let channelController = client.channelController(for: .init(type: .messaging, id: "general"))
channelController.synchronize() { error in
if error == nil {
let pinnedMessages = channelController.channel?.pinnedMessages
}
}Paginating Pinned Messages
Use the dedicated pinned messages endpoint to retrieve all pinned messages with pagination.
channelController.loadPinnedMessages(
pageSize: 10,
sorting: [.init(key: .pinnedAt, isAscending: false)],
pagination: .earlier(Date(), inclusive: true)) { result in
switch result {
case .success(let pinnedMessages):
print(pinnedMessages)
// Next page using the ID of the last message on this page
guard let lastPinnedMessageId = pinnedMessages.last?.id else { return }
channelController.loadPinnedMessages(
pageSize: 10,
sorting: [.init(key: .pinnedAt, isAscending: false)],
pagination: .before(lastPinnedMessageId, inclusive: false)) { result in
// Handle result
}
case .failure(let error):
// Handle error
print(error)
}
}