Tags | Slack | Integrations |
ADMIN PRIVILEGES REQUIRED
This documentation is for Stack Overflow for Teams Enterprise. Free, Basic, and Business users can access their documentation here. Find your plan.
Overview
Slack’s "Granular Bot Permissions" (GBP) integration path provides more fine-grained control of what the integration for Slack has access to. This allows applications like Stack Overflow for Teams Enterprise (SOE) to request only the access it needs to deliver value to users. GBP also includes support for org-level app installation, so organizations with multiple Slack workspaces can centrally manage what’s installed in each of their workspaces.
The Slack GBP integration are powered by a bot that joins your workspace once the integration is configured.
SOE requires different scopes based on optional features that can be set up.
All these scopes are bot scopes, which means they're related to our bot and not to the user that's installing it.
Scopes used by the Slack GBP integration
Here is a breakdown of the scopes used by the Slack GBP integration and what they are used for:
Scope | When it's required | What it's used for |
chat:write | always | To send notifications based on the users' configured notifications. Can be sent to public channels or DMs |
team:read | always | To show details about all the workspaces the integration is installed on |
channels:read | always | Grants very basic info on public Slack Channels, to select the target of the notifications. SOE shows a list of the public Channels where notifications can be sent to. Example response can been seen here. |
commands | interactive version | To add a /stack command that lets users search, connect and disconnect their Slack accounts with their SOE accounts (required so that the notifications know who to send a DM to when they set up a notification to their DM) |
links:read | interactive version | To subscribe to the link_shared event, the first step of unfurling a url |
links:write | interactive version | To provide the unfurled details, the last step of unfurling a url |
im:history | interactive version | To subscribe to the im_message event. So that the bot can reply to messages that are sent as a DM to the bot. NOTE: as this is a bot scope, it ONLY gives us access to messages that users send to the bot. |
channels:join | auto join public channels enabled | To join public channels automatically |
users:read | always | To map users from Slack to SOE |
users:read.email | automatic user mapping enabled | To map users from Slack to SOE (the mapping is done by email addresses) |
groups:read | private channel notifications | This optional scope is needed by the “Allow the bot to access basic info for private Slack channels it is a member of” option. This scope is used with the Slack API (see Slack docs here) to access a listing of private channels and their basic info. |
Notifications
After a site admin configures the Slack integration, users can set up notifications from SOE to Slack by following instructions in the Integration for Slack article. The destination for a notification can be a public channel or a DM.
If the user selects a public channel as a destination
The Slack GBP bot can only write to channels where it has been added. So while setting up the notification, SOE shows a list of all the public channels the bot is already a member of. In order to list all those channels, the integration uses channels:read. To simplify setting up new notifications, you can optionally have the Slack GBP bot join all public channels automatically.
If the user selects direct messages as a destination
For the Slack GBP bot to send notifications as direct messages, the integration needs to map a user's Slack workspace account with their SOE account. To simplify setting up new notifications, you can optionally have the integration automatically generate a mapping between Slack workspace and SOE user accounts based on matching email addresses. This automatic mapping requires the users:read and users:read.email scopes.
Without automatic mapping, each user who wants notifications as direct messages will need to manually map their Slack workspace and SOE accounts by sending the /stack connect command to the Slack GBP bot within Slack.
Additionally, to receive notifications as direct messages and to send commands directly to the Slack GBP bot, the integration requires the im:history scope. This scope only grants access to direct messages between a user and the Slack GBP bot.