DevSpec
DevSpec
Sign In
Start Your Project
All Docs/Slack Integration

Slack Integration

The Slack integration lets your team move naturally from a Slack conversation to a full AI-assisted DevSpec session. When a discussion reaches a point where action is needed, simply mention the DevSpec bot in the thread. DevSpec captures the entire conversation, identifies participants, and creates a session where the AI has access to your code, database, past decisions, and documents. When the work is done, a completion notification is posted back to the original Slack thread.

How It Works

The entire flow happens with a single @mention in Slack.

  • Your team is discussing in a Slack channel linked to a DevSpec project.
  • Someone mentions @DevSpec in the thread.
  • DevSpec captures the full thread transcript plus recent channel context and identifies all participants.
  • A new DevSpec session is created with the conversation as context.
  • The bot replies in the thread with a link to the session.
  • The session opens in DevSpec with an AI welcome message that shows it has already understood the conversation. The team continues brainstorming with full AI assistance — code, database, past decisions.
  • When a developer completes the work, a notification is posted back to the Slack thread.

Setup Guide

Setting up the Slack integration takes about 5 minutes. You will create a Slack App, configure it with the right permissions, and connect it to DevSpec.

What you need before starting

  • A DevSpec organisation. If you don't have one yet, go to Settings → Billing and create one, or ask your team admin to invite you.
  • Admin or owner role in your DevSpec organisation. The "Organisation" tab appears in Settings once you have this role.
  • Admin access to your Slack workspace (to install apps).

1. Step 1 — Create a Slack App

Create a new Slack App that will act as the DevSpec bot in your workspace.

  • Go to https://api.slack.com/apps and click "Create New App".
  • Choose "From scratch" (not from a manifest).
  • Enter the app name: DevSpec (or any name your team prefers).
  • Select the Slack workspace you want to connect.
  • Click "Create App".

Copy your credentials

On the "Basic Information" page, scroll to "App Credentials". You will need three values. Send these to your DevSpec administrator — they must be added to the server configuration before the integration will work.

  • Client ID
  • Client Secret (click "Show" to reveal)
  • Signing Secret (click "Show" to reveal)

2. Step 2 — Configure Bot Permissions

Tell Slack what the DevSpec bot is allowed to do.

  • In the left sidebar, click "OAuth & Permissions".
  • Scroll down to "Scopes" and find the "Bot Token Scopes" section.
  • Click "Add an OAuth Scope" and add each of these scopes:

Required scopes

  • app_mentions:read — Allows the bot to see when it is @mentioned. (This may be added automatically in Step 3 when you subscribe to the app_mention event.)
  • channels:history — Allows the bot to read messages in public channels (to capture thread transcripts).
  • groups:history — Allows the bot to read messages in private channels.
  • chat:write — Allows the bot to post messages (session links, notifications).
  • users:read — Allows the bot to look up user profiles.
  • users:read.email — Allows the bot to read user emails (for matching Slack users to DevSpec accounts).

3. Step 3 — Configure Event Subscriptions

Tell Slack to notify DevSpec when someone mentions the bot.

  • In the left sidebar, click "Event Subscriptions".
  • Toggle "Enable Events" to ON.
  • In the "Request URL" field, enter your DevSpec webhook URL:
https://devspec.ai/api/webhooks/slack/events

Slack will verify this URL automatically. You should see a green checkmark once it succeeds.

Subscribe to bot events

  • Scroll down to "Subscribe to bot events".
  • Click "Add Bot User Event".
  • Select "app_mention" from the list. It will show the scope "app_mentions:read" next to it — that is correct and expected.
  • Click "Save Changes" at the bottom.

4. Step 4 — Enable Interactivity

Allow the bot to use interactive buttons (for project selection when a channel is not linked).

  • In the left sidebar, click "Interactivity & Shortcuts".
  • Toggle "Interactivity" to ON.
  • In the "Request URL" field, enter:
https://devspec.ai/api/webhooks/slack/interactions

Click "Save Changes".

5. Step 5 — Add the OAuth Redirect URL

Tell Slack where to redirect after an admin approves the connection.

  • Go back to "OAuth & Permissions" in the sidebar.
  • Scroll to "Redirect URLs" and click "Add New Redirect URL".
  • Enter:
https://devspec.ai/api/integrations/slack/oauth/callback

Click "Add", then "Save URLs".

6. Step 6 — Connect in DevSpec

Now connect the Slack workspace to DevSpec.

  • In DevSpec, navigate to Organisation Settings (Settings → Organisation).
  • You will see a "Slack Integration" section with a "Connect Slack" button.
  • Click "Connect Slack".
  • You will be redirected to Slack's OAuth consent screen showing the permissions DevSpec needs.
  • Click "Allow" to approve.
  • You are redirected back to DevSpec. The workspace name and icon appear with a "Connected" status.

Verify the bot is active

In Slack, go to any channel and type @DevSpec. The bot should appear in the autocomplete suggestions. If it does, the connection is working.

Add the bot to your channels

After the bot is added, it will respond to all @mentions in that channel going forward.

Important: The first time you @mention the bot in a channel, Slack will show "DevSpecAI is not in this channel". Click "Add them" to invite the bot. You only need to do this once per channel.

7. Step 7 — Link Channels to Projects

Link your Slack channels to DevSpec projects so the bot knows which project context to use when creating sessions.

How to link a channel

  • In DevSpec, go to the project you want to link.
  • Open the project settings page.
  • Find the "Slack Channel Links" section (below API Tokens).
  • Click "Link Channel".
  • Enter the Slack Channel ID and channel name.

Finding your Slack Channel ID

  • In Slack, right-click the channel name in the sidebar.
  • Select "View channel details".
  • Scroll to the bottom of the details panel.
  • The Channel ID is shown (e.g. C01234ABCDE). Click to copy it.

Without a link

If someone mentions the bot in a channel that is not linked to any project, the bot will show a project selection menu directly in Slack. Linking channels just removes this extra step.

Using the Bot

Once connected and channels are linked, the bot is ready to use. Any @mention of the bot in a thread creates a DevSpec session.

Creating a session

  • Make sure the DevSpec bot has been added to the channel (see Step 6 above). You only need to do this once per channel.
  • Start or join a conversation thread in a linked Slack channel.
  • When the discussion reaches a point where you want AI assistance, type @DevSpec in the thread (not as a top-level message — it must be inside a thread reply). If you mention the bot in the main channel instead of a thread, it will prompt you to use a thread instead.
  • The bot captures the entire thread plus the recent conversation from the main channel leading up to it. This means the AI gets both the focused thread discussion and the broader context of what the team was talking about.
  • Within 30 seconds, the bot replies with a link to the new DevSpec session.
  • Click the link to open the session in DevSpec. The AI already has the full conversation context.

What happens in DevSpec

The session opens with an AI welcome message that acknowledges what the team was discussing and offers to help. The AI has already read the full imported conversation and will reference it naturally. A "Created from Slack" banner appears at the top of the session with a link back to the original Slack thread.

AI-generated session titles

Each session is automatically given a descriptive title based on the conversation content (e.g. "Site Agent Performance and Model Selection" instead of a generic timestamp). This makes it easy to find sessions later in the sessions list.

Completion notifications

When a developer later completes work from this session (via their IDE using the MCP endpoint), DevSpec automatically posts a notification back to the original Slack thread. The team sees what was done without leaving Slack.

Disconnecting

You can disconnect the Slack integration at any time.

  • Go to Organisation Settings in DevSpec.
  • Click the "Disconnect" button next to the Slack integration.
  • Confirm the disconnection.
  • The bot immediately stops responding to @mentions in Slack.
  • Existing sessions created from Slack are not affected — they remain accessible in DevSpec.

Troubleshooting

Common issues and how to resolve them.

Bot doesn't appear in Slack autocomplete

The bot is not installed in the workspace.

  • Make sure you completed Step 6 (Connect in DevSpec) and approved the OAuth consent.
  • Check that the workspace shows as "Connected" in Organisation Settings.
  • Try searching for the app name in Slack's app directory (Apps section in the sidebar).
  • If the app is there but not responding, verify the Event Subscriptions URL is correct and Slack verified it successfully.

Bot doesn't respond to @mentions

The bot is installed but nothing happens when mentioned.

  • Verify Event Subscriptions are enabled and the Request URL passed verification (green checkmark in Slack app settings).
  • Check that you subscribed to the "app_mention" bot event.
  • Make sure the bot is mentioned inside a thread, not just as a standalone message (the bot captures thread context).
  • If the issue persists, contact your DevSpec administrator.

Session not created after mention

The bot acknowledged the mention but no session appeared in DevSpec.

  • Check that the channel is linked to a project, or that you selected a project from the bot's prompt.
  • Session creation runs in the background — wait up to 30 seconds.
  • If the session still doesn't appear after 30 seconds, contact your DevSpec administrator.

Participants not matched to DevSpec accounts

Slack users show as "unmatched" in the session.

DevSpec matches Slack users to DevSpec accounts by email address. For a match to work, the Slack user's profile email must be the same as their DevSpec account email. If emails differ, an admin can manually link users in the future. Unmatched users' messages are still imported — they are attributed by Slack display name.

Completion notification not posted to Slack

Work was completed but the Slack thread was not updated.

  • Completion notifications are triggered by MCP write-backs from IDEs (Claude Code, Cursor). They are not triggered by actions in the DevSpec web app.
  • Verify the developer used update_action_item or add_commit_reference via MCP.
  • Check that the original Slack channel has not been archived.
  • If the notification fails, DevSpec retries up to 3 times. After that, the failure is logged.

Event Subscriptions URL verification failed

Slack cannot verify the Request URL during setup.

  • Make sure your DevSpec instance is running and accessible.
  • The URL must be exactly: https://devspec.ai/api/webhooks/slack/events (replace with your DevSpec URL).
  • Try clicking "Retry" next to the Request URL field in Slack.
  • If the issue persists, contact DevSpec support.