Self-Hosted Slack Setup

If you are running a self-hosted AgentRQ instance, you must create and configure a custom Slack App within your Slack workspace. This allows your self-hosted server to receive event subscriptions, webhook interactive actions, and register custom slash commands.

🛠️ Step-by-Step App Configuration

Step 1: Create the Slack App

1. 1.
   Go to the Slack App Console and click Create New App.
2. 2.
   Select From scratch.
3. 3.
   Name your app (e.g., AgentRQ) and choose your Slack Development Workspace.

Step 2: Configure Scopes & OAuth

1. 1.
   Navigate to OAuth & Permissions in the sidebar.
2. 2.
   Under Redirect URLs, click Add New Redirect URL and add your endpoint:

• → For Production: https://your-domain.com/api/v1/auth/slack/callback
• → For Local Development (using Ngrok): https://your-subdomain.ngrok-free.app/api/v1/auth/slack/callback
• → Click Save URLs.

1. 3.
   Scroll down to Scopes -> Bot Token Scopes and add the following:

• → groups:write — Allows the bot to automatically provision private channels.
• → groups:read — Allows the bot to find and reuse existing private channels.
• → chat:write — Allows the bot to post task updates and reply in threads.
• → commands — Registers the /t slash command.
• → app_mentions:read — Allows the bot to sync thread replies.

Step 3: Configure Slash Commands

1. 1.
   Go to Slash Commands and click Create New Command.
2. 2.
   Enter the details:

• → Command: /t
• → Request URL: https://your-domain.com/api/v1/slack/commands (or your Ngrok tunnel URL: https://your-subdomain.ngrok-free.app/api/v1/slack/commands)
• → Short Description: Create an AgentRQ task
• → Usage Hint: [task description] or "[title]" "[description]"

1. 3.
   Click Save.

Step 4: Configure Events & Interactions

#### Enable Event Subscriptions

1. 1.
   Go to Event Subscriptions and toggle it On.
2. 2.
   Under Request URL, enter: https://your-domain.com/api/v1/slack/events (or your Ngrok tunnel URL: https://your-subdomain.ngrok-free.app/api/v1/slack/events)
3. 3.
   Under Subscribe to bot events, click Add Bot User Event and select:

• → app_mention (Triggered when the user mentions the bot in a task thread)

1. 4.
   Click Save Changes.

#### Enable Interactive Components

1. 1.
   Go to Interactive Components and toggle it On.
2. 2.
   Under Request URL, enter: https://your-domain.com/api/v1/slack/interactions (or your Ngrok tunnel URL: https://your-subdomain.ngrok-free.app/api/v1/slack/interactions)
3. 3.
   Click Save Changes.

Step 5: Configure Backend Environment

Retrieve your credentials from the Slack App Console under Basic Information -> App Credentials and append them to your self-hosted backend environment or .env file:

# Enable Slack Integration
AGENTRQ_SLACK_ENABLED=true

# Slack OAuth and App Configurations
AGENTRQ_SLACK_CLIENT_ID=your_client_id_here
AGENTRQ_SLACK_CLIENT_SECRET=your_client_secret_here
AGENTRQ_SLACK_SIGNING_SECRET=your_signing_secret_here
AGENTRQ_SLACK_APP_ID=your_app_id_here

🔌 Linking Slack

After restarting your self-hosted backend server to load the environment variables, you can link your workspace channels:

1. 1.
   Open your self-hosted AgentRQ dashboard and log in.
2. 2.
   Select your workspace, then navigate to the Settings tab.
3. 3.
   Click the Slack sub-tab in the settings sidebar.
4. 4.
   Click the green Link Slack Channel button to initiate the secure OAuth flow.
5. 5.
   Review the requested permissions in Slack and authorize your custom Slack App.
6. 6.
   Upon redirect, associate your workspace with a private Slack channel. Each AgentRQ workspace maps to exactly one private channel to guarantee strict data separation between your projects:

• → Automatic Provisioning (Recommended): If left blank, the app automatically creates a secure private channel named agentrq-[workspace-name] and invites the installer.
• → Manual Provisioning: Enter your preferred Slack Channel ID and Name in the input fields manually.