Pinned messages

Pin messages to channels for easy access. Only one message can be pinned per channel at a time.

Use cases:

• Essential announcements and updates
• Action items and reminders
• Polls and persistent questions

Requires App Context and Message Persistence

Enable App Context and Message Persistence in the Admin Portal.

Pin

pin() and pinMessage() attach a message to a channel. Call pin() on a message object or pinMessage() on a channel object.

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()

  1message.pin(): PNFuture<Channel>

• pinMessage()

  1channel.pinMessage(message: Message): PNFuture<Channel>

Input

Parameter	Required in pin()	Required in pinMessage()	Description
message Type: Message Default: n/a	No	Yes	Message object that you want to pin to the selected channel.

Output

Type	Description
PNFuture<Channel>	PNFuture containing the updated channel metadata.

Sample code

Pin the last message on the incident-management channel.

• pin()

1fun pinLastMessageInIncidentManagementChannel(chat: Chat) {
2    // obtain the incident-management channel details
3    chat.getChannel("incident-management").async { channelResult ->
4        channelResult.onSuccess { channel ->
5            // handle success
6            // retrieve the history of messages
7            channel.getHistory(count = 1).async { historyResult ->
8                historyResult.onSuccess { historyResponse ->
9                    // handle success
10                    val messages = historyResponse.messages
11                    if (messages.isNotEmpty()) {
12                        val lastMessage = messages.last()
13                        
14                        // pin the last message
15                        lastMessage.pin().async { pinResult ->
16                            pinResult.onSuccess {
17                                // handle success
18                                println("Message pinned successfully in incident-management channel.")
19                            }.onFailure {
20                                // handle failure
21                                println("Failed to pin the message: ${it.message}")
22                            }
23                        }
24                    } else {
25                        println("The channel history is empty. No message to pin.")
26                    }
27                }.onFailure {
28                    // handle failure
29                    println("Failed to retrieve channel history: ${it.message}")
30                }
31            }
32        }.onFailure {
33            // handle failure
34            println("Failed to get channel details: ${it.message}")
35        }
36    }
37}

show all 37 lines

• pinMessage()

1fun pinLastMessageInIncidentManagementChannel(chat: Chat) {
2    // obtain the incident-management channel details
3    chat.getChannel("incident-management").async { channelResult ->
4        channelResult.onSuccess { channel ->
5            // handle success
6            // retrieve the history of messages
7            channel.getHistory(count = 1).async { historyResult ->
8                historyResult.onSuccess { historyResponse ->
9                    // handle success
10                    val messages = historyResponse.messages
11                    if (messages.isNotEmpty()) {
12                        // get the last message
13                        val lastMessage = messages.last()
14                        
15                        // pin the last message
16                        channel.pinMessage(lastMessage).async { pinResult ->
17                            pinResult.onSuccess {
18                                // handle success
19                                println("Message pinned successfully in incident-management channel.")
20                            }.onFailure {
21                                // handle failure
22                                println("Failed to pin the message: ${it.message}")
23                            }
24                        }
25                    } else {
26                        println("The channel history is empty. No message to pin.")
27                    }
28                }.onFailure {
29                    // handle failure
30                    println("Failed to retrieve channel history: ${it.message}")
31                }
32            }
33        }.onFailure {
34            // handle failure
35            println("Failed to get channel details: ${it.message}")
36        }
37    }
38}

show all 38 lines

Get

getPinnedMessage() retrieves the currently pinned message.

Method signature

This method has the following signature:

1channel.getPinnedMessage(): PNFuture<Message?>

Input

This method doesn't take any parameters.

Output

Type	Description
PNFuture<Message?>	Returned Message object.

Sample code

Get the message pinned to the incident-management channel.

1chat.getChannel("incident-management").async { result ->
2    result.onSuccess { channel ->
3        val pinnedMessageFuture = channel.getPinnedMessage()
4

5        pinnedMessageFuture.async { pinnedMessageResult ->
6            pinnedMessageResult.onSuccess { message ->
7                if (message != null) {
8                    // handle success
9                    println("Pinned message content: ${message.content}")
10                } else {
11                    println("No pinned message found in the channel.")
12                }
13            }.onFailure { exception ->
14                // handle failure
15                exception.printStackTrace()
16                println("Failed to get the pinned message: ${exception.message}")
17            }
18        }
19    }.onFailure { exception ->
20        // handle failure
21        exception.printStackTrace()
22        println("Failed to get channel details: ${exception.message}")
23    }
24}

show all 24 lines

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:

1channel.unpinMessage(): PNFuture<Channel>

Input

This method doesn't take any parameters.

Output

Type	Description
PNFuture<Channel>	PNFuture containing the updated channel metadata.

Sample code

Unpin the message from the incident-management channel.

1chat.getChannel("incident-management").async { result ->
2    result.onSuccess { channel ->
3        // attempt to unpin the message
4        val unpinMessageFuture = channel.unpinMessage()
5

6        unpinMessageFuture.async { unpinMessageResult ->
7            unpinMessageResult.onSuccess { updatedChannel ->
8                // handle success
9                println("Message successfully unpinned from the channel.")
10            }.onFailure { exception ->
11                // handle failure
12                exception.printStackTrace()
13                println("Failed to unpin the message: ${exception.message}")
14            }
15        }
16    }.onFailure { exception ->
17        // handle failure
18        exception.printStackTrace()
19        println("Failed to get channel details: ${exception.message}")
20    }
21}

show all 21 lines