Documentation Menu
Back to Channels

Slack App Setup

Workspace bot with slash commands and events

Overview

The Slack app enables SingularCore to receive commands and send notifications through your Slack workspace. It supports slash commands, event subscriptions, and direct messaging for maximum flexibility.

Difficulty

Moderate

Setup Time

10 minutes

Notification Tiers

Normal, High, Urgent

Prerequisites

  • Slack workspace admin access
  • Python 3.9+
  • slack-sdk library
  • Public URL or ngrok for webhooks

Step-by-Step Setup

1

Create Slack App

  1. Go to api.slack.com/apps
  2. Click Create New App
  3. Select From scratch
  4. Name your app (e.g., "SingularCore")
  5. Select your workspace
  6. Click Create App
2

Configure OAuth Scopes

In the left sidebar, go to OAuth & Permissions:

  1. Scroll to Scopes section
  2. Add the following Bot Token Scopes:
  • chat:write - Send messages
  • chat:write.public - Send messages to public channels
  • im:write - Send direct messages
  • commands - Add slash commands
  • app_mentions:read - Read app mentions
3

Install to Workspace

  1. Go to OAuth & Permissions
  2. Click Install to Workspace
  3. Authorize the app
  4. Copy the Bot User OAuth Token (starts with xoxb-)
  5. Also copy the Signing Secret from Basic Information page
4

Enable Events

In Event Subscriptions:

  1. Toggle Enable Events to On
  2. Set Request URL to your webhook endpoint (e.g., https://your-domain.com/slack/events)
  3. Subscribe to bot events:
  • app_mention - When app is mentioned
  • message.im - Direct messages to app
5

Create Slash Commands

In Slash Commands:

  1. Click Create New Command
  2. Add the following commands:

/singularcore-status

Request URL: https://your-domain.com/slack/commands

Description: Get system health status

/singularcore-skills

Request URL: https://your-domain.com/slack/commands

Description: List available skills

/singularcore-approve

Request URL: https://your-domain.com/slack/commands

Description: Approve pending action

6

Configure App

Edit config/comms.json:

{
  "slack": {
    "enabled": true,
    "bot_token": "xoxb-your-bot-token-here",
    "signing_secret": "your-signing-secret-here",
    "webhook_url": "https://your-domain.com/slack/events",
    "allowed_channels": ["#general", "#alerts"],
    "allowed_users": ["U12345678"],
    "auto_setup": true
  }
}

Supported Commands

CommandDescriptionTier
/singularcore-statusSystem health check0
/singularcore-skillsList all skills0
/singularcore-dreamView last dream summary0
/singularcore-approve <id>Approve pending action1+
/singularcore-reject <id>Reject pending action1+
@SingularCore <message>Mention app to submit goal1+
DM (direct message)Submit text as goal1+

Troubleshooting

App Not Responding

  • Verify bot token starts with xoxb-
  • Check webhook URL is publicly accessible
  • Verify signing secret is correct
  • Ensure app is installed to workspace

"invalid_auth" Error

  • Reinstall app to workspace to refresh token
  • Check token hasn't been revoked
  • Verify correct workspace is selected

Slash Commands Not Working

  • Verify Request URL is correct and responds with HTTP 200
  • Check webhook endpoint handles POST requests
  • Ensure commands are saved and app is reinstalled

Events Not Received

  • Verify Request URL responds to challenge request
  • Check bot is invited to channel for app mentions
  • Ensure events are subscribed in app settings

Need More Details?

View the complete setup guide with code examples, advanced configuration, and security best practices.

View Full Documentation