Merge pull request #549 from n0h0/add-group-id-formatting

Add group ID formatting support for message mentions

Author: dblock

CHANGELOG.md

@@ -1,5 +1,6 @@
 ### 2.5.3 (Next)
 
+* [#549](https://github.com/slack-ruby/slack-ruby-client/pull/549): Add group ID formatting support for message mentions - [@n0h0](https://github.com/n0h0).
 * Your contribution here.
 
 ### 2.5.2 (2025/02/19)

README.md

@@ -57,6 +57,7 @@ A Ruby client for the Slack [Web](https://api.slack.com/web), [RealTime Messagin
       - [Date and Time Formatting](#date-and-time-formatting)
       - [Channel ID Formatting](#channel-id-formatting)
       - [User ID Formatting](#user-id-formatting)
+      - [Group ID Formatting](#group-id-formatting)
       - [URL Formatting](#url-formatting)
       - [Markdown Formatting](#markdown-formatting)
     - [Parsing Messages](#parsing-messages)
@@ -665,6 +666,16 @@ Slack::Messages::Formatting.user_link(user_id)
   # => "<@U0000000001>"
 ```
 
+##### Group ID Formatting
+
+If you already know the group name you can just embed it in the message as `@some_group`, but if you only have the ID you can embed it using special syntax which Slack will display as the group name.
+
+```ruby
+group_id = 'S0000000001'
+Slack::Messages::Formatting.group_link(group_id)
+  # => "<!subteam^S0000000001>"
+```
+
 ##### URL Formatting
 
 Slack will automatically parse fully qualified URLs in messages, but you need special formatting to embed a link with different text.

lib/slack/messages/formatting.rb

@@ -61,6 +61,14 @@ def user_link(user_id)
           "<@#{user_id}>"
         end
 
+        #
+        # Embed a link to a group in a message by group ID
+        # @see https://api.slack.com/reference/surfaces/formatting#mentioning-groups
+        #
+        def group_link(group_id)
+          "<!subteam^#{group_id}>"
+        end
+
         #
         # Embed a URL with custom link text in a message
         # @see https://api.slack.com/reference/surfaces/formatting#linking-urls

spec/slack/messages/formatting_spec.rb

@@ -113,6 +113,14 @@
     end
   end
 
+  context '#group_link' do
+    let(:group_id) { 'S0000000001' }
+
+    it 'links to a group by its ID' do
+      expect(formatting.group_link(group_id)).to eq "<!subteam^#{group_id}>"
+    end
+  end
+
   context '#url_link' do
     let(:text) { 'super cool website' }
     let(:url) { 'https://theuselessweb.site/' }