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

# Slack Setup

> Install and configure the Whilst Slack bot

## Prerequisites

* A Slack workspace where you have admin permissions
* The Whilst web app running (locally or production)
* AWS infrastructure deployed (for Lambda endpoints)

## 1. Create a Slack App

<Steps>
  <Step title="Create the app">
    Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** → **From scratch**.

    * **App Name**: Whilst
    * **Workspace**: Select your workspace
  </Step>

  <Step title="Configure event subscriptions">
    Navigate to **Event Subscriptions** and enable events.

    * **Request URL**: `https://api.staging.whilst.app/slack/events` (or your API Gateway URL)
    * **Subscribe to bot events**: `app_mention`
  </Step>

  <Step title="Set bot scopes">
    Go to **OAuth & Permissions** and add these Bot Token Scopes:

    * `app_mentions:read`
    * `chat:write`
    * `channels:history`
    * `groups:history`
    * `users:read`
  </Step>

  <Step title="Install to workspace">
    Click **Install to Workspace** and authorize the app.
  </Step>
</Steps>

## 2. Configure OAuth

Set these environment variables for the OAuth install flow:

```bash theme={null}
SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
SLACK_SIGNING_SECRET=your-signing-secret
```

<Warning>
  Never commit these values to version control. Use environment variables or a secrets manager.
</Warning>

## 3. Complete the Install Flow

Visit `/slack/install` on your running instance to complete the OAuth handshake. This registers the workspace and stores the bot token (encrypted) in the database.

## 4. Test the Bot

In your Slack workspace, mention the bot in any channel:

```
@whilst What's the latest PR about authentication?
```

You should see:

1. An instant acknowledgement
2. Progressive status updates
3. A final answer with citations

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bot doesn't respond to mentions">
    * Verify the bot is in the channel (invite with `/invite @whilst`)
    * Check the Event Subscriptions URL is correct and verified
    * Review CloudWatch logs for the Event Intake Lambda
  </Accordion>

  <Accordion title="OAuth flow fails">
    * Ensure `SLACK_CLIENT_ID` and `SLACK_CLIENT_SECRET` are set correctly
    * Check the redirect URI matches your API Gateway URL
    * Verify the Slack app has the required scopes
  </Accordion>
</AccordionGroup>