> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecompiler.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Connect a Slack workspace so people can mention @Compiler and get answers in the thread.

This guide connects your self-hosted instance to a Slack workspace, so people can mention `@Compiler` with a question and get the answer in the thread.

You create a Slack app of your own and give Compiler its credentials in **Settings** > **Slack**. Nothing goes in environment variables, and nothing needs a restart.

## Prerequisites

* You're an owner or admin of your Compiler organization.
* You can create apps in your Slack workspace. Some workspaces need an admin to approve a new app.
* `PUBLIC_URL` is set to the address your instance is reached on, such as `https://compiler.yourdomain.com`. Slack sends questions to that address, so it has to be reachable from the internet over HTTPS. The Slack page in settings tells you if it's missing.

## Step 1: Create the Slack app

1. In Compiler, open **Settings** > **Slack**.
2. Click **Create the Slack app**. Slack opens with a manifest already filled in, pointing at your instance.
3. Choose your workspace and create the app.

If the button doesn't suit you, click **Copy the manifest** instead, go to [api.slack.com/apps](https://api.slack.com/apps), choose **Create New App** > **From a manifest**, and paste it.

The manifest asks for these permissions and no more:

| Scope | Why |
| - | - |
| `app_mentions:read` | To hear a question when someone mentions the bot |
| `assistant:write` | To show Slack's own "working" indicator, Stop button and starter prompts |
| `chat:write` | To reply |
| `channels:history` | To hear a follow-up in a thread the bot answered in, without a mention |
| `groups:history` | The same, in private channels |
| `im:history` | To hear a question sent as a direct message |

The manifest also turns on Slack's agent features for the app. It appears under **Agents** in the Slack sidebar with a split-view pane and suggested prompts, shows a "working" indicator with a Stop button while it answers, and streams its reply.

<Note>
  Slack doesn't let workspace guests use agent-enabled apps.
</Note>

Compiler only acts on messages in threads it has already answered in. Other channel messages are acknowledged and dropped.

## Step 2: Give Compiler the credentials

In your new Slack app, open **Basic Information** and find **App Credentials**. Copy these three into **Settings** > **Slack** in Compiler and save:

| Field | Notes |
| - | - |
| **Client ID** | Two numbers joined by a dot. It isn't the App ID. |
| **Client Secret** | Click **Show** to reveal it. |
| **Signing Secret** | Click **Show** to reveal it. Compiler uses it to check that a request really came from Slack. |

Both secrets are stored encrypted and are never shown again. To change them later, click **Replace credentials**.

## Step 3: Let Slack verify the address

Slack only sends events to an address it has verified, and it couldn't verify yours before Compiler had the Signing Secret.

1. In your Slack app, open **Event Subscriptions**.
2. Next to the Request URL, click **Retry**. It should change to **Verified**.
3. Save the page if Slack asks you to.

If it doesn't verify, check that `PUBLIC_URL` is right and that `https://your-instance/api/slack/events` is reachable from the internet.

## Step 4: Add Compiler to your workspace

Back in **Settings** > **Slack**, click **Add to Slack**, choose the workspace and approve.

<Warning>
  Do this from Compiler, not with the **Install to Workspace** button on the app's page at api.slack.com. That button installs the app without telling Compiler, and questions from the workspace are then dropped.
</Warning>

The page now shows the connected workspace. Invite the bot to a channel with `/invite @Compiler`, or message it directly.

## Optional: add an icon

A manifest can't carry an icon, so the app starts with Slack's placeholder. To give it one, open the app's **Basic Information**, scroll to **Display Information** and upload an image.

## Who can ask, and what they can see

Anyone in the connected workspace can ask a question. Questions from Slack are asked by a Compiler account that belongs to your organization, called **Compiler for Slack**, so an answer can draw on every project in the organization, whoever asked.

Each answer links to the full conversation in Compiler. Opening that link needs a Compiler login in your organization.

## Disconnect

Click **Disconnect** in **Settings** > **Slack**. Compiler removes itself from the workspace. Conversations it already had stay in Compiler, and links to them keep working.

You can then remove the credentials as well, or leave them in place to reconnect later.

## Update an existing app

When a new version of Compiler asks for more permissions, the manifest changes. Open the app's **App Manifest** page at api.slack.com, replace it with the manifest from **Settings** > **Slack**, save, then click **Add to Slack** in Compiler again to approve the new permissions. Nothing else needs redoing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.