Skip to main content

​
Slack Bot Development

Run your own instance of the GAIA Slack bot. The bot uses Socket Mode, so no public URL or port forwarding is required.
Looking to use GAIA in Slack as a user? See Using GAIA in Slack.

​
Prerequisites

  • Node.js 18+ and pnpm
  • A Slack workspace where you have admin access
  • GAIA API running (see Self-Hosting Guide)

​
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: 
    http://localhost:8000/api/v1/platform-auth/slack/callback
https://your-api-domain.com/api/v1/platform-auth/slack/callback
  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 listed in the Commands Reference. Request URL can be left blank in Socket Mode.

​
Step 5: Configure Environment Variables

Create a .env file in apps/bots/slack/: 
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret
GAIA_API_URL=http://localhost:8000
GAIA_BOT_API_KEY=your_secure_bot_api_key
For OAuth account linking, also add to apps/api/.env: 
SLACK_OAUTH_CLIENT_ID=your_client_id
SLACK_OAUTH_CLIENT_SECRET=your_client_secret
These enable users to link their Slack account from the GAIA web app settings page.

​
Step 6: Start the Bot

# Development (hot reload)
nx dev bot-slack

# Production
nx build bot-slack && nx start bot-slack

​
Troubleshooting

ProblemSolution
Bot doesn’t respondCheck Socket Mode is enabled and all tokens are correct
Command not foundVerify slash commands are created in the Slack app dashboard, then reinstall the app
Authentication failsEnsure GAIA_BOT_API_KEY matches the API config