Tags | Slack | Integrations |

ADMIN PRIVILEGES REQUIRED

This documentation is for Stack Overflow 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

Once the integration is configured, users can set up notifications from SOE to Slack. Instructions for doing so can be found in the "General instructions" section of this 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.