diff --git a/docs/snippets/guides/alerts-code-configuration.mdx b/docs/snippets/guides/alerts-code-configuration.mdx
index 339e73634..56cec6ce5 100644
--- a/docs/snippets/guides/alerts-code-configuration.mdx
+++ b/docs/snippets/guides/alerts-code-configuration.mdx
@@ -56,6 +56,26 @@ Elementary prioritizes configuration in the following order:
 
 <Subscribers />
 
+#### Tagging owners and subscribers on Slack
+
+Elementary tags the owners and subscribers of each alert on Slack. A value that starts with `@` is matched,
+case-insensitively, in this order:
+
+1. A Slack user whose email address starts with the handle (`@jessica.jones` tags jessica.jones@marvel.com).
+2. A Slack user whose display name matches the handle.
+3. A Slack user group whose handle matches (`@data-team` tags the `data-team` group). This requires the Slack app to
+   have the `usergroups:read` scope.
+
+You can also use a full email address, without `@` (`jessica.jones@marvel.com`).
+
+If several users match, full members take precedence over guests. Bots and deactivated users are ignored.
+A handle that doesn't match anything is shown as plain text, and the alert is still sent.
+
+<Info>
+  With the Elementary CLI, tagging requires a [Slack token](/oss/deployment-and-configuration/slack#token-vs-webhook).
+  A Slack webhook posts the handles as plain text.
+</Info>
+
 #### Test description
 
 <Description />
diff --git a/docs/snippets/setup-slack-integration.mdx b/docs/snippets/setup-slack-integration.mdx
index bc8eca27c..0f60115b8 100644
--- a/docs/snippets/setup-slack-integration.mdx
+++ b/docs/snippets/setup-slack-integration.mdx
@@ -48,6 +48,7 @@ Go to the "OAauth & Permissions" page for your newly-created app, and add the fo
 - `users:read` - View people in a workspace
 - `users:read.email` - View email addresses of people in a workspace
 - `groups:read` - View basic information about private channels that your slack app has been added to
+- `usergroups:read` - View user groups in a workspace (optional, needed only to [tag user groups](/oss/guides/alerts/alerts-configuration#tagging-owners-and-subscribers-on-slack) in alerts)
 
 <img
   src="https://res.cloudinary.com/diuctyblm/image/upload/v1695889115/slack-app-permissions-new_bysiso.png"