> 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/use-groundcover/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](/use-groundcover/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.<br>

   <div data-with-frame="true"><figure><img src="/files/zTyzwESP4pcT0WRR2fGX" alt=""><figcaption></figcaption></figure></div>
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.<br>

   <div data-with-frame="true"><figure><img src="/files/PTPMhGyvFxHHV8mftvGO" alt=""><figcaption></figcaption></figure></div>
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. Do not modify it — groundcover relies on these exact permissions to function.

The manifest requests a broad set of permissions on purpose: some are needed for current features (notifications, agent @mentions, channel-aware AI replies) and some are reserved for features we plan to release. Requesting them upfront means you won't have to reinstall the app — or get users to re-approve it — when those features ship.
{% 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).

   <div data-with-frame="true"><figure><img src="/files/id6nVsmjO5osL28KltWE" alt=""><figcaption></figcaption></figure></div>
2. In your Slack App settings, go to **Settings → Basic Information → Display Information → App Icon & Preview**.

   <div data-with-frame="true"><figure><img src="/files/Twb1B9cJDcbVcadsdhJA" alt=""><figcaption></figcaption></figure></div>
3. Click **Add App Icon** and upload the downloaded image.

   <div data-with-frame="true"><figure><img src="/files/U1qqoqZWV2bCdPcPyZmv" alt=""><figcaption></figcaption></figure></div>

### 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) |

<div data-with-frame="true"><figure><img src="/files/Io0etfWfU91WCPAiaT9Z" alt=""><figcaption></figcaption></figure></div>

#### 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**.

   <div data-with-frame="true"><figure><img src="/files/wXKNccLwfuTNxAszX8vD" alt=""><figcaption></figcaption></figure></div>
2. Click **Generate Token and Scopes**.
3. Enter a name (e.g., `groundcover`).
4. Click **Add Scope** and select **`connections:write`**.

   <div data-with-frame="true"><figure><img src="/files/Vp0Om6VGdRnCLr4MZfhM" alt=""><figcaption></figcaption></figure></div>
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.

<div data-with-frame="true"><figure><img src="/files/Nl6k1nMnNdDMhZdhNBHt" alt=""><figcaption></figcaption></figure></div>

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. This grants groundcover's bot the permissions defined in the manifest (sending messages, reading channels, etc.).

<div data-with-frame="true"><figure><img src="/files/ToqzGTrxnpFQ47cxCFRi" alt=""><figcaption></figcaption></figure></div>

Once authorization completes:

* The connector status changes to **active**.

<div data-with-frame="true"><figure><img src="/files/Hjl9tpz2NkVfmZk6NWW6" alt=""><figcaption></figcaption></figure></div>

* 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](/use-groundcover/monitors/notification-routes.md) destination picker and in the monitor wizard. You do not configure this Destination separately — it is managed by the connector.

<div data-with-frame="true"><figure><img src="/files/sD59p62DmUxxIWLQT3XG" alt=""><figcaption></figcaption></figure></div>

## 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](/use-groundcover/connectors/slack/slack-agent.md) in Slack.

See [Connecting Your Personal Slack Account](/use-groundcover/connectors/slack/slack-agent.md#connecting-your-personal-slack-account) for the full walkthrough.

## 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.<br>

   <div data-with-frame="true"><figure><img src="/files/Mh3lqP1h72C048eKwer4" alt=""><figcaption></figcaption></figure></div>
5. Search for and select the target channel.<br>

   <div data-with-frame="true"><figure><img src="/files/HQlNS13wk7cFndjFjO6t" alt="" width="174"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/qijjbUMI3LULNr4dojBa" alt="" width="185"><figcaption></figcaption></figure></div>

1. Click **Add Rule** to add more rules with different channels or status filters.

Private channels are marked with a lock icon. The bot can post to any **public** channel in the workspace, even if it has not been added to 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](/use-groundcover/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.<br>

   <div data-with-frame="true"><figure><img src="/files/k9FD4TpLt1hH5edjpSZU" alt=""><figcaption></figcaption></figure></div>
6. Pick a target channel from the drilldown panel.
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.<slack-app-id>.channels` — see [Monitor YAML structure](/use-groundcover/monitors/monitor-yaml-structure.md#notificationsettings) for the full schema.

## 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.
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 can post to all public channels without being added, but it must be invited to a private channel before that channel appears in the picker. 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**.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/connectors/slack.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.