diff --git a/docs/sources/notify/slack/index.md b/docs/sources/notify/slack/index.md index b25321c0..8407620c 100644 --- a/docs/sources/notify/slack/index.md +++ b/docs/sources/notify/slack/index.md @@ -41,54 +41,69 @@ For Open Source Grafana OnCall Slack installation guidance, refer to 1. Click **Allow** to give Grafana OnCall permission to access your Slack workspace. ## Why does OnCall Slack App require so many permissions? -OnCall has an advanced Slack App with dozens of features making it even possible for users to be on-call and work with + +OnCall has an advanced Slack App with dozens of features making it even possible for users to be on-call and work with alerts completely inside Slack. The drawback is that our Slack bot requires a lot of permissions and some of those permissions may sound suspicious, so we commented on them to give you more context. -#### Content and info about you -The bot is using those permissions to receive Slack handles and avatars. -Those permissions are supporting account matching between Grafana and Slack. + +### Content and info about you + +The bot is using those permissions to receive Slack handles and avatars. +Those permissions are supporting account matching between Grafana and Slack. + - **View information about your identity** - **View profile details about people in your workspace** -#### Content and info about channels & conversations -- **View basic information about public channels in your workspace** -— this permission is supporting channel selectors in the integration settings so the user could choose where to -send Alert Groups. -- **View messages and other content in public channels, private channels, direct messages, and group direct messages -that Grafana OnCall has been added to** — this permission is supporting a feature of adding messages to the resolution -notes in the Alert Group's Slack thread. -- **View basic information about private channels that Grafana OnCall has been added to** — this permission allows to -add a slack bot to the private channel and make it selectable in the list of channels. -So users will be able to route Alert Groups to the private channels. + +### Content and info about channels & conversations + +- **View basic information about public channels in your workspace** + — this permission is supporting channel selectors in the integration settings so the user could choose where to + send Alert Groups. +- **View messages and other content in public channels, private channels, direct messages, and group direct messages + that Grafana OnCall has been added to** — this permission is supporting a feature of adding messages to the resolution + notes in the Alert Group's Slack thread. +- **View basic information about private channels that Grafana OnCall has been added to** — this permission allows to + add a slack bot to the private channel and make it selectable in the list of channels. + So users will be able to route Alert Groups to the private channels. - **View basic information about direct messages that Grafana OnCall has been added to** -#### Content and info about your workspace + +### Content and info about your workspace + This set of permissions is supporting the ability of Grafana OnCall to match users with Grafana users. + - **View people in your workspace** - **View email addresses of people in your workspace** - **View the name, email domain, and icon for workspaces Grafana OnCall is connected to** - **View user groups in your workspace** - **View profile details about people in your workspace** -#### Perform actions as you -- **Send messages on your behalf** — this permission may sound suspicious, but it's actually a general ability -to send messages as the bot: https://api.slack.com/scopes/chat:write Grafana OnCall will not impersonate or post -using your handle to slack. It will always post as the bot. -#### Perform actions in channels & conversations + +### Perform actions as you + +- **Send messages on your behalf** — this permission may sound suspicious, but it's actually a general ability + to send messages as the bot: Grafana OnCall will not impersonate or post + using your handle to slack. It will always post as the bot. + +### Perform actions in channels & conversations + - **View messages that directly mention @grafana_oncall in conversations that the app is in** - **Join public channels in your workspace** - **Send messages as @grafana_oncall** - **Send messages as @grafana_oncall with a customized username and avatar** -- **Send messages to channels @grafana_oncall isn't a member of** — users configure channels to publish -Alert Groups in the OnCall's UI, but the bot is usually not a member of those channels. -- **Upload, edit, and delete files as Grafana OnCall** — the bot is using this permission: -https://api.slack.com/scopes/files:write to be able to send files to the channel. -The bot will not delete or read files sent by other users. +- **Send messages to channels @grafana_oncall isn't a member of** — users configure channels to publish + Alert Groups in the OnCall's UI, but the bot is usually not a member of those channels. +- **Upload, edit, and delete files as Grafana OnCall** — the bot is using this permission: + to be able to send files to the channel. + The bot will not delete or read files sent by other users. - **Start direct messages with people** - **Add and edit emoji reactions** -#### Perform actions in your workspace -- **Add shortcuts and/or slash commands that people can use** — the permission is used to add /escalate and /oncall -(deprecated) slack commands. + +### Perform actions in your workspace + +- **Add shortcuts and/or slash commands that people can use** — the permission is used to add /escalate and /oncall + (deprecated) slack commands. - **Create and manage user groups** — the permission is used to automatically update user groups linked to on-call -schedules. It will add users once their on-call shift starts and remove them once the on-call shift ends. -- **Set presence for Grafana OnCall** + schedules. It will add users once their on-call shift starts and remove them once the on-call shift ends. +- **Set presence for Grafana OnCall** ## Post-install configuration for Slack integration