---
title: "Self-Hosted Slack Setup | AgentRQ Docs"
url: https://agentrq.com/docs/integrations/slack-self-hosted
description: "Step-by-step guide to create and configure a custom Slack App for self-hosted AgentRQ installations."
---

[Docs](https://agentrq.com/docs/) / Integrations / Integrations

Integrations

# Self-Hosted Slack Setup

Step-by-step guide to create and configure a custom Slack App for self-hosted AgentRQ installations.

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.

**Using AgentRQ Cloud?** If you are running on the managed hosted platform, do not follow this guide. Go directly to the [Slack Cloud Connection Guide](https://agentrq.com/docs/integrations/slack).

## 🛠️ Step-by-Step App Configuration

### Step 1: Create the Slack App

1. 1.
   Go to the [Slack App Console](https://api.slack.com/apps) 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:

env

```env
# 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
```

The Slack signing secret (`AGENTRQ_SLACK_SIGNING_SECRET`) is critical for security. It prevents malicious request forgery. Never expose this secret or commit it to Git.

## 🔌 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.