Skip to main content

​
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

1

Create the app

Go to api.slack.com/apps and click Create New App → From scratch.
  • App Name: Whilst
  • Workspace: Select your workspace
2

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
3

Set bot scopes

Go to OAuth & Permissions and add these Bot Token Scopes:
  • app_mentions:read
  • chat:write
  • channels:history
  • groups:history
  • users:read
4

Install to workspace

Click Install to Workspace and authorize the app.

​
2. Configure OAuth

Set these environment variables for the OAuth install flow: 
SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
SLACK_SIGNING_SECRET=your-signing-secret
Never commit these values to version control. Use environment variables or a secrets manager.

​
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

  • 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
  • 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