Skip to main content
The Slack bot uses Socket Mode: it opens a connection to Slack instead of receiving webhooks, so it needs no public URL. Do the shared bot setup first. You also need a Slack workspace where you are an admin.

Step 1: Create a Slack App

  1. Go to api.slack.com/apps
  2. Click Create New App → From scratch
  3. Give your app a name and select your workspace

Step 2: Enable Socket Mode

  1. In the sidebar, go to Socket Mode
  2. Toggle Enable Socket Mode on
  3. Generate an App-Level Token with the connections:write scope
  4. Copy the token, it starts with xapp-

Step 3: Configure Bot Permissions

  1. Go to OAuth & Permissions
  2. Under Bot Token Scopes, add:
    • chat:write
    • commands
    • im:history
    • im:read
    • im:write
  3. Under User Token Scopes, add:
    • identity.basic
  4. Under Redirect URLs, add:
  5. Click Install App to Workspace (or Reinstall if already installed)
  6. Copy the Bot User OAuth Token (starts with xoxb-)
  7. Copy the Client ID and Client Secret from Basic Information
  8. Copy the Signing Secret from Basic Information

Step 4: Register Slash Commands

Go to Slash Commands and create each command in the Commands Reference. Leave the Request URL blank.

Step 5: Configure Environment Variables

In apps/bots/.env:
For OAuth account linking, also add to apps/api/.env:
These enable users to link their Slack account from the GAIA web app settings page.

Step 6: Start the Bot

Troubleshooting

Things to try next