Pinned messages
Using Chat SDK methods, you can implement UI features allowing users to "pin" a message to a channel by selecting a sent message and placing it on top of the channel for everyone to see and access it easily.
They can also "unpin" the message if it's no longer important or "pin" another one to replace an already pinned message (there can be only one pinned message on a channel at a time).
Additionally, they can check which message is pinned to the selected channel since the Chat SDK uses the channel metadata to store information on such messages in Message Persistence.
Pinned Messages let users highlight messages in channels for:
-
Essential information - pin critical updates or announcements, ensuring important information remains easily accessible to all participants and reducing the chance of missing key details.
-
Action items and reminders - by pinning action items or reminders, users and their teams can have a centralized location for reference, making it easier to stay organized, prioritize tasks, and ensure accountability.
-
Polling - pin a poll to a channel, allowing a pollster to persist their questions and not have them lost in a chat flow.
Requires App Context and Message Persistence
To store modified data about messages, you must enable App Context and Message Persistence for your app's keyset in the Admin Portal.
Pin
pin() and pinMessage() attach a message to the channel.
Both of these methods give the same result. The only difference between them is that you may or may not be required to provide input parameters, and you call them on different objects: message (pin()) or channel (pinMessage()).
Alternatively, you can also use other Chat SDK methods to pin a message in a thread (thread message) to the thread channel or the parent channel.
Method signature
These methods take the following parameters:
-
pin()message.pin(completion: ((Swift.Result<ChannelImpl, Error>) -> Void)? = nil) -
pinMessage()channel.pinMessage(
message: MessageImpl,
completion: ((Swift.Result<ChannelImpl, Error>) -> Void)? = nil
)
Input
| Parameter | Type | Required in pin() | Required in pinMessage() | Default | Description |
|---|---|---|---|---|---|
message | MessageImpl | No | Yes | n/a | MessageImpl object that you want to pin to the selected channel. |
Output
| Type | Description |
|---|---|
((Swift.Result<ChannelImpl, Error>) -> Void) | completion containing the updated channel metadata. |
Basic usage
Pin the last message on the incident-management channel.
pin()
func pinLastMessageInIncidentManagementChannel(chat: ChatImpl) {
// Obtain the incident-management channel details
chat.getChannel(channelId: "incident-management") { channelResult in
switch channelResult {
case let .success(channel):
if let channel = channel {
// Handle success
// Retrieve the history of messages
channel.getHistory(count: 1) { historyResult in
switch historyResult {
case let .success(historyResponse):
// Handle success
let messages = historyResponse.messages
if !messages.isEmpty {
let lastMessage = messages.last!
pinMessage()
func pinLastMessageInIncidentManagementChannel(chat: ChatImpl) {
// Obtain the incident-management channel details
chat.getChannel(channelId: "incident-management") { channelResult in
switch channelResult {
case let .success(channel):
if let channel = channel {
// Handle success
// Retrieve the history of messages
channel.getHistory(count: 1) { historyResult in
switch historyResult {
case let .success(historyResponse):
// Handle success
let messages = historyResponse.messages
if !messages.isEmpty {
// Get the last message
Get
getPinnedMessage() fetches the message that is currently pinned to the channel.
Method signature
This method has the following signature:
channel.getPinnedMessage(completion: ((Swift.Result<MessageImpl?, Error>) -> Void)? = nil)
Input
This method doesn't take any parameters.
Output
| Type | Description |
|---|---|
((Swift.Result<MessageImpl?, Error>) -> Void) | Returned MessageImpl object. |
Basic usage
Get the message pinned to the incident-management channel.
// Reference the "incident-management" channel
chat?.getChannel(channelId: "incident-management") { result in
switch result {
case let .success(channel):
if let channel = channel {
// Fetch the pinned message from the channel
channel.getPinnedMessage { pinnedMessageResult in
switch pinnedMessageResult {
case let .success(message):
if let message = message {
// Handle success
print("Pinned message content: \(message.content)")
} else {
print("No pinned message found in the channel.")
}
Unpin
unpinMessage() unpins a message from the channel.
Alternatively, you can also use other Chat SDK methods to unpin a message in a thread (thread message) from the thread channel or the parent channel.
Method signature
This method has the following signature:
channel.unpinMessage(completion: ((Swift.Result<ChannelImpl, Error>) -> Void)? = nil)
Input
This method doesn't take any parameters.
Output
| Type | Description |
|---|---|
((Swift.Result<ChannelImpl, Error>) -> Void) | completion containing the updated channel metadata. |
Basic usage
Unpin the message from the incident-management channel.
// Reference the "incident-management" channel
chat?.getChannel(channelId: "incident-management") { result in
switch result {
case let .success(channel):
if let channel = channel {
// Attempt to unpin the message
channel.unpinMessage { unpinMessageResult in
switch unpinMessageResult {
case .success:
// Handle success
print("Message successfully unpinned from the channel.")
case let .failure(error):
// Handle failure
print("Failed to unpin the message: \(error.localizedDescription)")
}