FEATURE: Pin chat messages (discourse#37985)

Allow staff to pin important messages in chat channels. Pinned messages
appear in a dedicated panel accessible from the channel navbar. Members
of allowed groups (admins/moderators by default) can pin and unpin
messages via the message actions menu.

Pinned messages show "pinned by" attribution, track unread state per
user, and auto-unpin when the original message is trashed. Real-time
updates via MessageBus keep the pinned list in sync.

Gated behind the chat_pinned_messages upcoming change (experimental).

Author: jjaffeux

plugins/chat/app/controllers/chat/api/channel_pins_controller.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+class Chat::Api::ChannelPinsController < Chat::ApiController
+  def index
+    raise Discourse::NotFound unless SiteSetting.chat_pinned_messages
+
+    Chat::ListChannelPins.call(service_params) do
+      on_success do |pins:, membership:|
+        render_serialized({ pins:, membership: }, Chat::ChannelPinsSerializer, root: false)
+      end
+      on_model_not_found(:channel) { raise Discourse::NotFound }
+      on_model_not_found(:membership) do |pins:|
+        render_serialized({ pins:, membership: nil }, Chat::ChannelPinsSerializer, root: false)
+      end
+      on_failed_policy(:can_view_channel) { raise Discourse::InvalidAccess }
+      on_failed_contract do |contract|
+        render(json: failed_json.merge(errors: contract.errors.full_messages), status: :bad_request)
+      end
+      on_failure { render(json: failed_json, status: :unprocessable_entity) }
+    end
+  end
+
+  def mark_read
+    raise Discourse::NotFound unless SiteSetting.chat_pinned_messages
+
+    Chat::MarkPinsAsRead.call(params: { channel_id: params[:channel_id] }, guardian: guardian) do
+      on_success { render json: success_json }
+      on_model_not_found(:channel) { raise Discourse::NotFound }
+      on_model_not_found(:membership) { raise Discourse::NotFound }
+      on_failed_policy(:can_access_channel) { raise Discourse::InvalidAccess }
+      on_failed_contract do |contract|
+        render(json: failed_json.merge(errors: contract.errors.full_messages), status: :bad_request)
+      end
+      on_failure { render(json: failed_json, status: :unprocessable_entity) }
+    end
+  end
+
+  def create
+    raise Discourse::NotFound unless SiteSetting.chat_pinned_messages
+
+    Chat::PinMessage.call(service_params) do
+      on_success { render(json: success_json) }
+      on_failure { render(json: failed_json, status: :unprocessable_entity) }
+      on_model_not_found(:message) { raise Discourse::NotFound }
+      on_failed_policy(:can_pin) { raise Discourse::InvalidAccess }
+      on_failed_policy(:within_pin_limit) do
+        render(
+          json:
+            failed_json.merge(
+              error:
+                I18n.t(
+                  "chat.errors.pin_limit_reached",
+                  limit: Chat::PinnedMessage::MAX_PINS_PER_CHANNEL,
+                ),
+            ),
+          status: :unprocessable_entity,
+        )
+      end
+      on_failed_policy(:not_already_pinned) do
+        render(
+          json: failed_json.merge(error: I18n.t("chat.errors.message_already_pinned")),
+          status: :unprocessable_entity,
+        )
+      end
+      on_failed_contract do |contract|
+        render(json: failed_json.merge(errors: contract.errors.full_messages), status: :bad_request)
+      end
+    end
+  end
+
+  def destroy
+    raise Discourse::NotFound unless SiteSetting.chat_pinned_messages
+
+    Chat::UnpinMessage.call(service_params) do
+      on_success { render(json: success_json) }
+      on_failure { render(json: failed_json, status: :unprocessable_entity) }
+      on_model_not_found(:message) { raise Discourse::NotFound }
+      on_model_not_found(:pin) do
+        render(
+          json: failed_json.merge(error: I18n.t("chat.errors.message_not_pinned")),
+          status: :unprocessable_entity,
+        )
+      end
+      on_failed_policy(:can_unpin) { raise Discourse::InvalidAccess }
+      on_failed_contract do |contract|
+        render(json: failed_json.merge(errors: contract.errors.full_messages), status: :bad_request)
+      end
+    end
+  end
+end

plugins/chat/app/jobs/scheduled/chat/delete_old_messages.rb

@@ -18,19 +18,23 @@ def delete_public_channel_messages
         return unless valid_day_value?(:chat_channel_retention_days)
 
         ::Chat::MessageDestroyer.new.destroy_in_batches(
-          ::Chat::Message.in_public_channel.with_deleted.created_before(
-            ::SiteSetting.chat_channel_retention_days.days.ago,
-          ),
+          ::Chat::Message
+            .in_public_channel
+            .with_deleted
+            .created_before(::SiteSetting.chat_channel_retention_days.days.ago)
+            .where.not(id: ::Chat::PinnedMessage.select(:chat_message_id)),
         )
       end
 
       def delete_dm_channel_messages
         return unless valid_day_value?(:chat_dm_retention_days)
 
         ::Chat::MessageDestroyer.new.destroy_in_batches(
-          ::Chat::Message.in_dm_channel.with_deleted.created_before(
-            ::SiteSetting.chat_dm_retention_days.days.ago,
-          ),
+          ::Chat::Message
+            .in_dm_channel
+            .with_deleted
+            .created_before(::SiteSetting.chat_dm_retention_days.days.ago)
+            .where.not(id: ::Chat::PinnedMessage.select(:chat_message_id)),
         )
       end
 

plugins/chat/app/models/chat/channel.rb

@@ -25,6 +25,7 @@ class Channel < ActiveRecord::Base
                class_name: "Chat::Message",
                foreign_key: :last_message_id,
                optional: true
+    has_many :pinned_messages, class_name: "Chat::PinnedMessage", foreign_key: :chat_channel_id
 
     def last_message
       super || NullMessage.new
@@ -145,6 +146,10 @@ def leave(user)
       self.remove(user)
     end
 
+    def pinned_messages_count
+      pinned_messages.size
+    end
+
     def url
       "#{Discourse.base_url}/chat/c/#{self.slug || "-"}/#{self.id}"
     end

plugins/chat/app/models/chat/message.rb

@@ -57,6 +57,10 @@ class Message < ActiveRecord::Base
              dependent: :destroy,
              class_name: "Chat::Mention",
              foreign_key: :chat_message_id
+    has_one :pinned_message,
+            class_name: "Chat::PinnedMessage",
+            foreign_key: :chat_message_id,
+            dependent: :destroy
     has_many :user_mentions,
              dependent: :destroy,
              class_name: "Chat::UserMention",

plugins/chat/app/models/chat/pinned_message.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Chat
+  class PinnedMessage < ActiveRecord::Base
+    self.table_name = "chat_pinned_messages"
+
+    MAX_PINS_PER_CHANNEL = 20
+
+    belongs_to :chat_message, class_name: "Chat::Message"
+    belongs_to :chat_channel, class_name: "Chat::Channel"
+    belongs_to :user, foreign_key: :pinned_by_id
+
+    validates :chat_message_id, uniqueness: true
+
+    scope :for_channel, ->(channel) { where(chat_channel: channel).order(created_at: :desc) }
+  end
+end
+
+# == Schema Information
+#
+# Table name: chat_pinned_messages
+#
+#  id              :bigint           not null, primary key
+#  created_at      :datetime         not null
+#  updated_at      :datetime         not null
+#  chat_channel_id :bigint           not null
+#  chat_message_id :bigint           not null
+#  pinned_by_id    :bigint           not null
+#
+# Indexes
+#
+#  idx_chat_pinned_messages_channel_created       (chat_channel_id,created_at DESC)
+#  index_chat_pinned_messages_on_chat_message_id  (chat_message_id) UNIQUE
+#

plugins/chat/app/models/chat/user_chat_channel_membership.rb

@@ -17,6 +17,24 @@ class UserChatChannelMembership < ActiveRecord::Base
     def mark_read!(new_last_read_id = nil)
       update!(last_read_message_id: new_last_read_id || chat_channel.last_message_id)
     end
+
+    def has_unseen_pins?
+      pins = chat_channel.pinned_messages
+
+      if pins.loaded?
+        others = pins.reject { |pin| pin.pinned_by_id == user_id }
+        return false if others.empty?
+        return true if last_viewed_pins_at.nil?
+        others.any? { |pin| pin.created_at > last_viewed_pins_at }
+      else
+        others = pins.where.not(pinned_by_id: user_id)
+        if last_viewed_pins_at.nil?
+          others.exists?
+        else
+          others.where("created_at > ?", last_viewed_pins_at).exists?
+        end
+      end
+    end
   end
 end
 
@@ -28,6 +46,7 @@ def mark_read!(new_last_read_id = nil)
 #  following                           :boolean          default(FALSE), not null
 #  join_mode                           :integer          default("manual"), not null
 #  last_viewed_at                      :datetime         not null
+#  last_viewed_pins_at                 :datetime
 #  muted                               :boolean          default(FALSE), not null
 #  notification_level                  :integer          default("mention"), not null
 #  starred                             :boolean          default(FALSE), not null

plugins/chat/app/queries/chat/messages_query.rb

@@ -107,6 +107,7 @@ def self.base_query(channel:)
           .includes(uploads: { optimized_videos: :optimized_upload })
           .includes(chat_channel: :chatable)
           .includes(thread: %i[original_message last_message])
+          .includes(:pinned_message)
           .where(chat_channel_id: channel.id)
 
       user_includes = SiteSetting.enable_user_status ? %i[user_status user_option] : %i[user_option]

plugins/chat/app/serializers/chat/base_channel_membership_serializer.rb

@@ -8,7 +8,9 @@ class BaseChannelMembershipSerializer < ApplicationSerializer
                :chat_channel_id,
                :last_read_message_id,
                :last_viewed_at,
-               :starred
+               :last_viewed_pins_at,
+               :starred,
+               :has_unseen_pins
 
     def starred
       object.starred
@@ -17,5 +19,17 @@ def starred
     def include_starred?
       scope&.authenticated?
     end
+
+    def has_unseen_pins
+      object.has_unseen_pins?
+    end
+
+    def include_has_unseen_pins?
+      SiteSetting.chat_pinned_messages && scope&.authenticated?
+    end
+
+    def include_last_viewed_pins_at?
+      SiteSetting.chat_pinned_messages && scope&.authenticated?
+    end
   end
 end

plugins/chat/app/serializers/chat/channel_pins_serializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Chat
+  class ChannelPinsSerializer < ApplicationSerializer
+    attributes :pinned_messages, :membership
+
+    def pinned_messages
+      ActiveModel::ArraySerializer.new(
+        object[:pins],
+        each_serializer: Chat::PinnedMessageSerializer,
+        scope: scope,
+      )
+    end
+
+    def membership
+      return if !object[:membership]
+
+      Chat::UserChannelMembershipSerializer.new(object[:membership], scope: scope, root: false)
+    end
+  end
+end

plugins/chat/app/serializers/chat/channel_serializer.rb

@@ -23,7 +23,8 @@ class ChannelSerializer < ApplicationSerializer
                :memberships_count,
                :current_user_membership,
                :meta,
-               :threading_enabled
+               :threading_enabled,
+               :pinned_messages_count
 
     has_one :last_message, serializer: Chat::LastMessageSerializer, embed: :objects
 
@@ -46,6 +47,14 @@ def memberships_count
       object.user_count
     end
 
+    def pinned_messages_count
+      object.pinned_messages.size
+    end
+
+    def include_pinned_messages_count?
+      SiteSetting.chat_pinned_messages
+    end
+
     def chatable_url
       object.chatable_url
     end
@@ -140,6 +149,7 @@ def meta
       data[:can_delete_self] = scope.can_delete_own_chats?(object.chatable)
       data[:can_delete_others] = scope.can_delete_other_chats?(object.chatable)
       data[:can_remove_members] = scope.can_remove_members?(object)
+      data[:can_manage_pins] = scope.can_manage_chat_channel_pins?(object)
 
       data
     end