Skip to main content
Slack integration allows your team to interact with Proliferate directly from Slack channels. Users can start coding sessions by mentioning the bot, receive updates, and interact with running sessions.

​
Prerequisites

  • Self-hosted Proliferate instance running and accessible via HTTPS
  • Slack workspace admin access
  • Your instance URLs:
    • NEXT_PUBLIC_APP_URL - Your web app (e.g., https://proliferate.yourcompany.com)
    • Webhook endpoint: https://YOUR_APP_URL/api/slack/events

​
Step 1: Create a Slack App

1

Go to Slack API

Visit api.slack.com/apps and click Create New App
2

Choose manifest

Select From a manifest and choose your workspace
3

Paste the manifest

Copy the manifest below, update the URLs, and paste it

​
Slack App Manifest

display_information:
  name: Proliferate
  description: AI coding agent for your codebase
  background_color: "#000000"

features:
  bot_user:
    display_name: Proliferate
    always_online: true

oauth_config:
  redirect_urls:
    - https://YOUR_APP_URL/api/integrations/slack/oauth/callback
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - channels:history
      - channels:read
      - channels:join
      - groups:history
      - groups:read
      - im:history
      - im:read
      - im:write
      - mpim:history
      - mpim:read
      - users:read
      - users:read.email

settings:
  event_subscriptions:
    request_url: https://YOUR_APP_URL/api/slack/events
    bot_events:
      - app_mention
      - message.channels
      - message.groups
      - message.im
      - message.mpim
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
Replace YOUR_APP_URL with your actual URL before pasting.

​
Step 2: Get Your Credentials

After creating the app, collect these credentials:
  • Client ID → SLACK_CLIENT_ID
  • Client Secret → SLACK_CLIENT_SECRET
  • Signing Secret → SLACK_SIGNING_SECRET
  • Bot User OAuth Token → stored automatically per org
The Slack bot token is stored in the database after installation. You do not need to set it manually for each org.

​
Step 3: Configure Environment

Add these to your .env file: 
# Slack App Credentials
SLACK_CLIENT_ID=1234567890.1234567890123
SLACK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SLACK_SIGNING_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional (only for Slack Connect invites)
PROLIFERATE_SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx

​
Step 4: Restart Services

# If using pre-built images
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d

# If building locally
docker-compose down
docker-compose up -d

​
Step 5: Install to Workspace

1

Install the app

Go to your Slack app’s Install App page and click Install to Workspace
2

Authorize

Accept the requested permissions
3

Invite the bot

In Slack, run /invite @Proliferate in a channel
4

Test it

Mention the bot: @Proliferate hello

​
Troubleshooting

  1. Check that the event subscription URL is correct and accessible
  2. Verify the signing secret matches
  3. Check gateway logs: docker-compose logs gateway
  1. Verify the redirect URL matches exactly (including trailing slashes)
  2. Check that your APP_URL is accessible from the internet
  3. Check web logs: docker-compose logs web
  1. Go to Event Subscriptions in your Slack app
  2. Click Retry to re-verify the URL
  3. Ensure your gateway is accessible via HTTPS

​
Security Notes

Store Slack credentials securely - never commit them to git. Use HTTPS for all URLs since Slack requires it for event subscriptions. Rotate credentials if they’re ever exposed.

​
Permissions Reference

ScopePurpose
app_mentions:readDetect when users mention the bot
chat:writeSend messages and responses
channels:historyRead message history for context
channels:readList channels the bot can access
channels:joinJoin public channels when invited
groups:*Same as above for private channels
im:*Direct message support
mpim:*Group DM support
users:readGet user info for mentions
users:read.emailMatch Slack users to Proliferate accounts