> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/automate/connectors/slack.md).
# Slack
{% hint style="info" %}
This capability is only available to BYOC deployments. Check out our [pricing page](https://www.groundcover.com/pricing) for more information about subscription plans and the available deployment modes.
{% endhint %}
The Slack connector integrates groundcover with your Slack workspace. Once configured, groundcover can send monitor notifications to specific Slack channels and enable users to interact with groundcover's agent directly from Slack using [@groundcover mentions](/automate/connectors/slack/slack-agent.md).
{% hint style="info" %}
Admin permissions are required to create and manage the Slack connector.\
Any workspace member can connect their personal Slack account once the connector is set up.
{% endhint %}
## Setting Up the Slack App
Setting up the Slack connector is a one-time process that involves creating a Slack App, providing its credentials, and authorizing it in your workspace.
### Step 1: Create the Slack App from Manifest
1. In groundcover, go to **Integrations → Connectors** and open the **Org Connectors** tab.
2. Select **Slack**. The setup form opens directly for the first Slack App
1. If you already have one or more Slack Apps connected, click **Add Slack Connector** to add another one (see [Connecting Multiple Slack Workspaces](#connecting-multiple-slack-workspaces)).
3. Click **Create App** — this opens Slack's app creation page with a pre-filled manifest containing all the required permissions and configuration.
4. In Slack, **choose the workspace** to install the app in, click **Next**, review the manifest, and click **Create**.
{% hint style="info" %}
You can also reach the same setup form from **Integrations → Destinations → Slack App**, which is convenient when you're configuring Slack alongside other Destinations like PagerDuty.
{% endhint %}
{% hint style="info" %}
You can click **View Manifest** to inspect the full manifest JSON before creating the app. The manifest includes all required OAuth scopes, event subscriptions, and Socket Mode configuration.
The default manifest includes permissions used by current features and additional unused bot scopes. See [Slack App Permissions Reference](#slack-app-permissions-reference) for their current use, removal impacts, and guidance on reducing permissions.
{% endhint %}
For more details on creating apps from manifests, see [Slack's manifest guide](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/).
### Step 2: Upload the App Icon
1. Click **Download Icon** in the groundcover setup wizard to save the groundcover app icon (PNG).
2. In your Slack App settings, go to **Settings → Basic Information → Display Information → App Icon & Preview**.
3. Click **Add App Icon** and upload the downloaded image.
### Step 3: Fill in App Credentials
You need three values from your Slack App. All of them are found in your Slack App's settings page.
| Field | Where to find it in Slack |
| ------------------- | ------------------------------------------------------------------------ |
| **Client ID** | Settings → Basic Information → App Credentials → Client ID |
| **Client Secret** | Settings → Basic Information → App Credentials → Client Secret |
| **App-Level Token** | Settings → Basic Information → App-Level Tokens (see instructions below) |
#### Generating the App-Level Token
The App-Level Token is not created automatically — you need to generate it:
1. In your Slack App settings, go to **Basic Information → App-Level Tokens**.
2. Click **Generate Token and Scopes**.
3. Enter a name (e.g., `groundcover`).
4. Click **Add Scope** and select **`connections:write`**.
5. Click **Generate**.
6. Copy the token — it starts with `xapp-`.
{% hint style="warning" %}
The App-Level Token must start with `xapp-`. groundcover validates it against Slack's API during setup. If the token is invalid or missing the `connections:write` scope, the setup will fail with an error.
{% endhint %}
Back in the groundcover setup wizard, fill in:
* **Connector Name** — A unique label to identify this connector (e.g., `groundcover Prod`).
* **Client ID** — From your Slack App credentials.
* **Client Secret** — From your Slack App credentials.
* **App-Level Token** — The `xapp-` token you just generated.
Click **Connect** to save and proceed to authorization.
### Step 4: Authorize the App (OAuth)
After saving the credentials, you are redirected to Slack to authorize the app in your workspace. The standard authorization flow requests the default bot permissions (sending messages, reading channels, etc.). If you need fewer permissions, review [Reducing permissions](#reducing-permissions) before authorizing.
Once authorization completes:
* The connector status changes to **active**.
* A Destination of type `slack-app` is automatically created and bound to your Slack workspace. It appears alongside other Destinations (like Slack Webhook and PagerDuty) in the [Notification Routes](/automate/monitors/notification-routes.md) destination picker and in the monitor wizard. You do not configure this Destination separately — it is managed by the connector.
## Connecting Multiple Slack Workspaces
You can connect more than one Slack workspace by repeating the [Setting Up the Slack App](#setting-up-the-slack-app) flow for each workspace:
1. Create a separate Slack App in each workspace (each workspace will need its own Client ID, Client Secret, and App-Level Token).
2. Add each one as a separate connector in **Integrations → Connectors → Org Connectors → Slack** with a distinct **Connector Name** (e.g., `groundcover Prod`, `groundcover Staging`, `groundcover Customer-Success`).
3. After OAuth, each connector is bound to its workspace and creates its own `slack-app` Destination.
When you [select a Slack channel](#selecting-slack-channels-in-notification-routes) in a notification route or monitor, each Slack App appears separately in the picker labeled by its connector name, so you can route alerts to the correct workspace.
{% hint style="info" %}
A single Slack connector is bound to one workspace. You cannot point two connectors at the same Slack workspace.
{% endhint %}
## Connecting Your Personal Slack Account
After an admin sets up the Slack connector, individual users can link their personal Slack accounts from **Integrations → Connectors → My Connections**. This enables features like interacting with groundcover's agent via [@groundcover mentions](/automate/connectors/slack/slack-agent.md) in Slack.
See [Connecting Your Personal Slack Account](/automate/connectors/slack/slack-agent.md#connecting-your-personal-slack-account) for the full walkthrough.
## Preview groundcover links in Slack
Paste a link to an individual log or trace into a Slack message to show its details without opening groundcover. Log previews include the log line, level, workload, pod, and timestamp. Trace previews include duration, span and error counts, status code when available, and the slowest span.
The Slack App connector must be active, and the link must point to the same groundcover organization as the connector. Previews use the sharing user's groundcover permissions; if your Slack identity is not connected, Slack prompts you to connect it. Slack can preview up to three recognized groundcover links from one message.
Open a preview to see more details or follow its link back to the corresponding view in groundcover. Links to other pages remain regular Slack links.
## Selecting Slack Channels in Notification Routes
After the Slack connector is active, you can route monitor notifications to specific Slack channels.
1. Go to **Monitors → Notification Routes**.
2. Click **Create Notification Route** (or edit an existing one).
3. In **Step 3 (Rules)**, click the **destination dropdown**.
4. Select your Slack App — it is marked with an **App** tag. A second panel appears listing the available channels in your workspace.
5. Search for and select the target channel.
1. Click **Add Rule** to add more rules with different channels or status filters.
Private channels are marked with a lock icon. With `chat:write.public`, the bot can post to **public** channels without being added. If you remove that scope, add the bot to each target public channel before sending notifications; selecting a channel here does not add it. For **private** channels, the bot must first be invited to the channel — only private channels the bot has been added to appear in the picker.
{% hint style="info" %}
You can create multiple rules to route to different channels based on issue status. For example, send **Firing** alerts to `#critical-alerts` and **Resolved** notifications to `#alerts-resolved`.
{% endhint %}
For more details on notification routes, see [Notification Routes](/automate/monitors/notification-routes.md).
## Selecting Slack Channels in the Monitor Wizard
When creating or editing a monitor, you can send notifications directly to Slack channels without using notification routes:
1. Open the monitor wizard (create or edit a monitor).
2. In the **Notifications** section, select **Directly to destinations**.
3. Click **Set rule**.
4. Choose an issue status filter (Firing, Resolved, or both).
5. In the **Send to** dropdown, select your Slack App.
6. Pick a target channel from the drilldown panel. Without `chat:write.public`, add the bot to each target public channel before sending notifications. Private channels always require an invitation.
7. Click **+** to add more destinations (additional Slack channels or other Destinations).
{% hint style="info" %}
Choosing **Directly to destinations** means this monitor's issues will be skipped by notification routes. If you want notifications to flow through your configured routes instead, select **Based on matching notification routes**.
{% endhint %}
The selected channels are persisted in the monitor under `notificationSettings.connectedAppParams..channels` — see [Monitor YAML structure](/automate/monitors/monitor-yaml-structure.md#notificationsettings) for the full schema.
## Issue Graph Previews in Notifications
Slack App notifications include the issue timeline as a PNG by default. The graph is attached shortly after the notification is posted and is updated when the issue resolves.
The issue graph shows the firing, pending, and normal states directly in Slack.
Graph previews are available only for **Slack App** destinations, not Slack webhooks. They are best-effort and limited to approximately one image per second. When notifications are enabled, delivery is independent: the text notification is sent first and is unaffected if a graph is delayed or skipped.
To disable the graph while creating or editing a monitor, expand **Advanced** under **Issue Details**, then enable **Hide preview graph in Slack**. See [Create a new Monitor](/automate/monitors/create-a-new-monitor.md#section-3-issue-details).
## Updating Credentials
If you need to rotate the Client Secret or App-Level Token after the initial setup:
1. Go to **Integrations → Connectors** and open the **Org Connectors** tab.
2. Select **Slack** and open your Slack connector.
3. Enter the new Client Secret and/or App-Level Token. Leave a field blank to keep its current value.
4. Click **Save Changes**.
{% hint style="warning" %}
If the App-Level Token becomes invalid or is revoked in Slack, the connector will stop receiving events from Slack and move to an **invalid token** state. Update the token to restore functionality.
{% endhint %}
## Deleting the Connector
1. Go to **Integrations → Connectors** and open the **Org Connectors** tab.
2. Select **Slack** and click the delete action on the Slack connector.
3. Confirm deletion.
{% hint style="warning" %}
A Slack connector that is used by notification routes or monitors cannot be deleted. Remove it from all routes and monitors first.
{% endhint %}
## Troubleshooting
### The App-Level Token is rejected during setup
Verify that:
* The token starts with `xapp-`.
* The token was generated with the `connections:write` scope.
* The token has not been revoked in Slack.
You can regenerate it in your Slack App under **Basic Information → App-Level Tokens**.
### OAuth authorization fails
* Ensure you are signing into the correct Slack workspace.
* Verify the Client ID and Client Secret match your Slack App's credentials (check for extra spaces when pasting).
### User sign-in fails with "workspace does not match"
Each Slack connector is bound to a specific workspace. If a user tries to sign in with a different workspace, the connection will fail. Make sure users sign into the same workspace the admin authorized during initial setup.
### Notifications are not being sent to Slack
1. Verify the connector status is **active** in **Integrations → Connectors → Org Connectors**.
2. Check that the target channel is selected in your notification route or monitor. For private channels, or public channels when `chat:write.public` is absent, verify that the bot is a member. Selecting a channel does not add it.
3. Verify the notification route's scope query matches the monitor's labels.
4. Use the **Test** button in the monitor to send a test notification.
5. Filter traces by `workload:dispatch-center` in groundcover to inspect delivery attempts.
### A private channel does not appear in the channel picker
The bot must be invited to a private channel before that channel appears in the picker. Public-channel delivery without membership requires `chat:write.public`; without it, add the bot to public alert channels too. Open the channel in Slack and run `/invite @groundcover` (or use the channel settings → **Integrations** → **Add apps**), then reopen the picker.
### The channel picker is empty
* If channels were recently created, try closing and reopening the dropdown to refresh the list.
* Verify the Slack App connector status is **active** in **Integrations → Connectors → Org Connectors**.
## Slack App Permissions Reference
Slack uses separate permissions for the workspace bot, individual users, and the app-level token used for Socket Mode. The tables below describe current use and the impact of removing or declining each permission. Bot permissions support notifications and interactions with the Slack app. Slack MCP user permissions let the agent use Slack tools on your behalf.
### Reducing permissions
The nine bot scopes listed under **Unused bot scopes** are not used by current groundcover features. They are candidates for removal without losing those features. This applies only to bot scopes; permissions with the same names may still support user-token MCP capabilities.
{% hint style="warning" %}
The standard groundcover authorization flow still requests the full default set of bot scopes. Editing the manifest alone does not change that authorization request. If your organization requires a reduced-permission installation, contact groundcover support before creating or reauthorizing the app to confirm the installation procedure for your deployment.
Existing bot and user OAuth tokens retain removed scopes until they are revoked or the app is uninstalled. Reauthorizing alone does not remove those permissions. Revoking the bot token stops notifications and bot API calls; uninstalling the app also disrupts personal connections. Plan the change with support and follow [Restoring connections after revocation](#restoring-connections-after-revocation). See [Slack's scope-change guidance](https://docs.slack.dev/app-management/distribution/#scopes).
{% endhint %}
Keep the permissions needed by the features you use. In particular, public-channel notifications without inviting the bot use `chat:write.public`, file uploads can require `channels:join`, and custom message icons use `chat:write.customize`. These permissions are used by current features and are not part of the unused list.
For personal Slack connections with MCP enabled, users can decline optional permissions during consent. Keep `search:read.public`, which is required to establish that MCP connection. Declining optional permissions limits the agent's available Slack tools without changing the bot's permissions. Users still need a connected personal Slack account for agent mentions and authenticated link previews.
#### Choosing permissions for notifications
For text alerts and the public/private channel picker, keep bot scopes `chat:write`, `channels:read`, and `groups:read`. Invite the bot to each target channel. These permissions do not grant access to message history or files, and do not enable agent conversations.
Add permissions for the features you need:
| Feature | Additional bot permission | Without it |
| ------------------------------------------------------------- | ------------------------- | --------------------------------------------------- |
| Issue graph images | `files:write` | Text alerts continue without uploaded graphs. |
| Posting to public channels without an invitation | `chat:write.public` | Invite the bot to each target channel. |
| Automatically joining public channels for direct file sharing | `channels:join` | Invite the bot before sharing files to the channel. |
| Custom message icon | `chat:write.customize` | Messages use the app's default icon. |
For agent conversations, link previews, and other features, use the feature-impact table below. Slack MCP uses separate user permissions and is not required for notifications. The app-level `connections:write` token remains separate from bot scopes.
Bot `files:read` is optional. Graph uploads, graph display, and attachment names in message context do not need it. Slack grants file-detail and content access through this scope; groundcover's bot conversation context does not download or analyze file contents.
Follow the support-assisted installation guidance in [Reducing permissions](#reducing-permissions). Removing bot scopes can also require removing event subscriptions that depend on them; changing the manifest does not change the standard OAuth request.
#### Restoring connections after revocation
The bot OAuth token, personal MCP user tokens, and app-level Socket Mode token serve separate purposes. Updating the Client Secret or App-Level Token does not replace revoked bot or user OAuth tokens.
1. If the app-level token was revoked, generate a replacement with `connections:write` and save it in the connector using [Updating Credentials](#updating-credentials). This restores the credential used to receive Slack events.
2. If the bot token was revoked or the app was uninstalled, reconnect the existing org connector and complete Slack OAuth authorization to install the app and store a new bot token. For reduced permissions, use the procedure agreed with support; the standard flow requests the full default set. Confirm that the connector is **active**.
3. Users whose personal MCP tokens were revoked must reconnect separately through **Integrations → Connectors → My Connections**. Reconnecting the org connector does not replace their user tokens.
4. Restore any required channel invitations and send a test notification before relying on the connector for alerts.
### Bot Token Scopes
Bot scopes define what the groundcover Slack App can do as a bot in your workspace. History and file permissions are subject to Slack's access rules; they do not grant access to every private channel in the workspace.
#### Bot permissions and feature impact
These scopes grant access for bot features. The **For text notifications** column identifies permissions used to send and update text alerts and populate the channel picker. Optional scopes support the additional features described in each row. The bot must be invited to each target channel when `chat:write.public` is omitted. Coordinate changes with support as described in [Reducing permissions](#reducing-permissions), because the standard installation still requests the full default set.
| Scope | For text notifications | Permission and current groundcover use | Impact if removed |
| ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `app_mentions:read` | Optional | Receive events when users @mention the groundcover bot, powering the [@groundcover Agent](/automate/connectors/slack/slack-agent.md) | The agent no longer receives channel @mentions. |
| `assistant:write` | Optional | Show assistant thread status, such as the agent's thinking indicator | The agent cannot show its thinking indicator or thread status. |
| `channels:history` | Optional | Read messages in public channels the bot has joined for agent conversation context | The agent cannot fetch public-channel conversation context. Public-channel message events also require this scope. |
| `channels:join` | Optional | Join public channels when sharing uploaded files directly to a channel | The bot cannot join public channels automatically. Invite it before sharing files directly to a channel. Text notifications can still be sent without membership when `chat:write.public` is retained. |
| `channels:read` | Required for public-channel listing | List public channels and their metadata for the notification channel picker | The connector cannot refresh public-channel listings or fetch their metadata for the channel picker. |
| `chat:write` | Required to send and update alerts | Send and update monitor notifications, agent replies, and resolved-status messages | The bot cannot send or update notifications or agent replies. |
| `chat:write.customize` | Optional | Set the custom groundcover icon on messages sent by the integration | Messages still send, but Slack uses the app's default icon instead of the custom groundcover icon. |
| `chat:write.public` | Optional | Send notifications to public channels where the bot has not been invited | The bot cannot send messages to public channels it has not joined. With `channels:read` retained, those channels can still appear in the picker, but selecting them does not grant permission to send. Add the bot with `/invite @groundcover` before sending alerts. With `channels:history` retained, joining also grants channel-history and message-event access; see the access note below. |
| `files:read` | Optional | Slack grants access to file details and contents. groundcover's bot conversation context uses attachment names supplied in messages, without downloading or analyzing file contents. | Removes permission for file-detail API calls such as `files.info`. Attachment names remain available in conversation history and message or mention events. Issue graph uploads, inline display, and updates on resolution do not require this scope. Text notifications continue independently. |
| `files:write` | Optional | Upload files, such as issue timeline graph images attached to notifications | Notifications lose uploaded issue graph images. Text notifications continue independently. |
| `groups:history` | Optional | Read message history in private channels the bot has been invited to | The agent cannot fetch private-channel conversation context. Private-channel message events also require this scope. |
| `groups:read` | Required for private-channel listing | List private channels the bot has been invited to for the channel picker | The connector cannot refresh private-channel listings or fetch their metadata for the channel picker. |
| `im:history` | Optional | Receive incoming DM messages and read DM history for agent conversations. | The bot no longer receives incoming DM messages and cannot read DM history, preventing agent conversations in DMs. |
| `im:read` | Optional | Read information about DM conversations with the bot | The bot cannot fetch DM conversation metadata. |
| `links:read` | Optional | Detect shared groundcover URLs to trigger link previews | Shared groundcover links no longer trigger automatic previews. |
| `links:write` | Optional | Display rich previews of groundcover URLs, including log and trace details | The bot cannot display rich groundcover link previews. |
| `reactions:read` | Optional | Receive reaction-added events to measure engagement with bot messages | The integration loses reaction-added events used for engagement metrics. |
| `reactions:write` | Optional | Add emoji reactions, such as acknowledging an agent request | The bot cannot add acknowledgment emoji reactions. |
| `users:read` | Optional | Look up Slack user profiles for agent context and personal account linking when MCP is enabled | New personal Slack connections with MCP enabled fail during account linking. Profile lookups for agent context also fail. |
| `users:read.email` | Optional | Include email addresses in Slack profile responses. Account linking uses the signed-in groundcover account's email. | Slack profile responses omit email addresses. Account linking still uses the groundcover identity. |
Inviting the bot changes its access as well as where it can post. With `channels:history` granted, the bot can read messages in public channels it joins. The default manifest also subscribes to `message.channels`, allowing Slack to deliver new message events from those channels. The agent can use conversation history as [context for Slack interactions](/automate/connectors/slack/slack-agent.md#how-it-works).
Keeping `chat:write.public` allows text notifications without channel membership, but does not enforce a posting-only boundary: the file-upload path can join public channels using `channels:join`. For notifications without granting the groundcover bot channel-history access, use a separate [Slack Webhook destination](/automate/connected-apps/slack-webhook.md). Webhook destinations do not provide the Slack app's agent interactions or uploaded issue graph previews.
Slack Webhook destinations are available only for BYOC deployments. Each destination sends to the channel configured for its webhook URL; you cannot select a different channel per rule through that destination. To replace Slack App delivery, create one webhook destination per target channel and manually update notification routes or direct monitor destinations. Preserve each rule's Firing/Resolved status filters and select the matching webhook destination. Existing Slack App channel selections do not migrate automatically. Keep the Slack App if you need to select multiple channels through a single destination.
Message updates also change: when Firing and Resolved notifications go to the same channel, the Slack App can [update the original firing message on resolution](/automate/connected-apps/slack-app.md#resolved-original-message-updated). A Slack Webhook destination sends the resolved notification as a separate message; it does not update the original alert. Keep the Slack App if you need those in-place updates.
#### Unused bot scopes
The default manifest also includes these nine bot scopes, which are not used by current groundcover features. They are included in anticipation of future features so that enabling those features will not require another permission approval for scopes the app already has.
If you remove one of these scopes and a future feature needs it, an administrator will need to add the scope back in the Slack app's OAuth settings or manifest and reinstall or reauthorize the app in the workspace to grant it. Any required workspace approval must also be completed before that feature can work. See [Reducing permissions](#reducing-permissions) before changing the app's permissions.
| Scope | Permission granted | Impact if removed |
| ------------------ | ---------------------------------------------------- | ------------------------ |
| `bookmarks:read` | Read channel bookmarks | No current feature loss. |
| `bookmarks:write` | Manage channel bookmarks | No current feature loss. |
| `channels:manage` | Create and manage public channels | No current feature loss. |
| `groups:write` | Create and manage private channels | No current feature loss. |
| `im:write` | Open and start direct-message conversations | No current feature loss. |
| `mpim:read` | Read information about multi-person DM conversations | No current feature loss. |
| `pins:write` | Pin and unpin messages | No current feature loss. |
| `usergroups:read` | Read user groups and their membership | No current feature loss. |
| `usergroups:write` | Create and manage user groups | No current feature loss. |
### User Token Scopes
User permissions apply when individuals [connect their personal Slack account](/automate/connectors/slack/slack-agent.md#connecting-your-personal-slack-account). The permissions requested depend on whether Slack MCP is enabled for the deployment.
#### Slack MCP connections
Slack's MCP server lets the groundcover agent access Slack tools using the connected user's identity and permissions. `search:read.public` is the only required user scope for this connection. Every other scope in this table is listed under `user_optional` in the manifest and can be declined during user consent. Available tools depend on the permissions granted and the tools exposed by [Slack's MCP server](https://docs.slack.dev/ai/slack-mcp-server/#oauth-scopes-needed-on-user-token-for-different-tools). Some tools may need more than one scope.
The impacts below apply to agent actions through your personal connection; declining these permissions does not remove the workspace bot's permissions or your own access to Slack.
| Scope | Agent capability | Requirement | Impact if declined |
| --------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `search:read.public` | Search public-channel messages accessible to the user | Required for the MCP connection | The Slack MCP connection cannot be established. |
| `search:read.private` | Search private-channel messages accessible to the user | Optional | The agent cannot search private-channel messages through this connection. |
| `search:read.im` | Search the user's direct messages | Optional | The agent cannot search your DMs through this connection. |
| `search:read.mpim` | Search the user's multi-person direct messages | Optional | The agent cannot search your group DMs through this connection. |
| `search:read.files` | Search files accessible to the user | Optional | The agent cannot search Slack files through this connection. |
| `search:read.users` | Search for users | Optional | The agent cannot search for Slack users through this connection. |
| `channels:history` | Read public-channel message history as the user | Optional | The agent cannot read public-channel message history through this connection. |
| `channels:read` | List public-channel conversations and their members | Optional | The agent cannot list public-channel conversations or their members through this connection. |
| `channels:write` | Create public channels as the user; it does not grant permission to send messages | Optional | The agent cannot create public channels as you. |
| `chat:write` | Send messages as the user | Optional | The agent cannot send messages as you. Bot notifications and replies use separate permissions. |
| `groups:history` | Read private-channel message history accessible to the user | Optional | The agent cannot read private-channel message history through this connection. |
| `groups:read` | List private-channel conversations and their members | Optional | The agent cannot list private-channel conversations or their members through this connection. |
| `groups:write` | Create private channels as the user; it does not grant permission to send messages | Optional | The agent cannot create private channels as you. |
| `im:history` | Read the user's direct-message history | Optional | The agent cannot read your DM history through this connection. |
| `im:write` | Open direct-message conversations as the user | Optional | The agent cannot open DMs as you. |
| `mpim:history` | Read the user's multi-person direct-message history | Optional | The agent cannot read your group-DM history through this connection. |
| `mpim:read` | List group-DM conversations and their members | Optional | The agent cannot list group-DM conversations or their members through this connection. |
| `mpim:write` | Start multi-person DM conversations; it does not grant permission to send messages | Optional | The agent cannot start group DMs as you. |
| `files:read` | Read files accessible to the user | Optional | The agent cannot read existing Slack files as you. You can still upload and share files, including screenshots, in Slack. |
| `canvases:read` | Read canvases; also required by Slack's canvas creation and update tools | Optional | The agent loses canvas reading, creation, and editing through this connection. |
| `canvases:write` | Create and edit canvases as the user, together with `canvases:read` | Optional | The agent cannot create or edit Slack canvases as you. |
| `emoji:read` | Read the workspace's custom emoji | Optional | The agent cannot list workspace custom emoji through this connection. |
| `reactions:read` | Grants permission to read reactions; Slack's published MCP tool list has no dedicated tool for this scope | Optional | Removes reaction-reading permission; does not remove the separate tool for adding reactions. |
| `reactions:write` | Add reactions as the user | Optional | The agent cannot add reactions as you. |
| `users:read` | Look up user profiles | Optional | The agent cannot look up Slack user profiles through this connection. |
| `users:read.email` | Read user email addresses | Optional | Slack user profile lookups through this connection omit email addresses. |
#### Personal connections without Slack MCP
When Slack MCP is disabled, personal connections use Sign in with Slack to link the user's identity. The requested user scopes are `openid`, `email`, and `profile` for sign-in and identity information. They do not grant access to Slack message history or permission to send messages as the user.
The groundcover Agent can still be invoked from Slack. It runs on behalf of the Slack user who invoked it, using the matching groundcover user's RBAC permissions and Agent Mode budget. Monitor notifications can also continue to be sent from groundcover to Slack because those features use the workspace bot connection rather than Slack MCP user permissions.
### App-Level Token Scope
The app-level token is separate from bot and user tokens. Its `connections:write` scope is required to establish Socket Mode connections and receive Slack events. See [Generating the App-Level Token](#generating-the-app-level-token).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.groundcover.com/automate/connectors/slack.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
