​

Slack Bot Development

​

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

​

Step 5: Configure Environment Variables

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

SLACK_OAUTH_CLIENT_ID=your_client_id
SLACK_OAUTH_CLIENT_SECRET=your_client_secret

​

Step 6: Start the Bot

# Development (hot reload)
nx dev bot-slack

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

​

Troubleshooting