Slack integration

Overview

Connect the Promptless Slack app so your team can start documentation work from Slack conversations and get notified when suggestions are ready. One connection covers these jobs:

Capability	What Promptless does	Set it up
Triggers	Starts documentation work when someone tags @Promptless, uses the Update Docs message action, or sends a DM.	Slack messages
Context	Reads the thread where you trigger it, and Slack threads that a request links to.	Slack messages
Notifications	Posts to your notification channel when suggestions are created, updated, or published.	Customize notifications
Configuration	Updates your triggers, doc collections, and other configuration when you ask in Slack.	Ask Promptless to update your configuration

By default, Promptless reads Slack only when someone triggers it. If you turn on passive channel listening, Promptless also reads the channels you select, and only those. Promptless doesn’t archive or store your Slack messages. It uses large language models (LLMs), which can generate inaccurate results.

In this guide, you install the Slack app, add Promptless to channels, and grant permissions that Promptless adds later.

Before you start

An admin role in your Promptless organization.
Permission to install apps in your Slack workspace, or a Slack workspace admin who can approve the request.

Connect Slack

On the Integrations page, select Connect Slack. Slack opens in a new window. If your browser blocks the window, allow pop-ups for Promptless and select Connect Slack again.
In the Slack window, select the workspace where you want to install Promptless.
Review and approve the permissions the Promptless Slack app requests. Promptless needs them to respond to the right events in Slack and to notify your team when updates are available. For what each permission does, see Key permissions.
On the Integrations page, verify that Slack shows as connected.

Some Slack workspaces require an admin to approve apps before anyone can install them. If you aren’t a workspace admin, Slack sends your request to an admin, and setup waits for their approval. The steps are the same from onboarding and from the Integrations page, and your pending request persists across page reloads and sessions.

In the Slack window, follow Slack’s prompts to send the request. Slack may notify you when an admin approves Promptless.
Wait for the admin’s decision. Until you finish the install, a pending card in onboarding or on the Integrations page shows that Promptless isn’t installed in Slack yet. Promptless can’t see the admin’s decision, so the card stays pending.
After an admin approves, select Continue in Slack on the pending card. Slack runs authorization again and connects Promptless.

If you close the window or lose your network connection before you finish, the request stays pending. Select Continue in Slack to try again. If Slack reports that the attempt was denied or failed, Promptless clears the request, and you start a new one.

Key permissions

Slack’s approval screen lists every permission the Promptless Slack app requests. These are the ones that control what you can do in Slack:

Permission	What Promptless uses it for
`channels:read`, `groups:read`	Lists public channels, and private channels Promptless was invited to, so you can pick them as a notification channel or trigger source.
`channels:join`	Joins a public channel before posting there or listening to it, so Promptless receives replies to its messages without an invite.
`chat:write`	Replies in threads and posts suggestion notifications.
`files:read`	Reads screenshots and logs attached to a request to @Promptless.
`links:read`, `links:write`	Shows a preview card when someone shares a Promptless suggestion link.
`users:read`	Shows people’s names instead of user IDs when Promptless replies to mentions.
`users:read.email`	Matches the person who submitted a task through an MCP editor to their Slack account, so Promptless can DM them the result.

Add Promptless to a channel

Promptless responds to an @mention only in a channel it’s a member of. It joins a public channel on its own before it posts there, such as for a suggestion notification. It also joins a public channel when you configure the channel for passive listening. Promptless can’t join a private channel, or a channel shared with another workspace through Slack Connect, on its own.

Add Promptless to a channel yourself when you want to:

Tag @Promptless in a channel it isn’t a member of yet.
Use a private or Slack Connect channel as your notification channel, to trigger Promptless from its messages, or for passive listening.

To add Promptless, tag @Promptless in the channel, and accept Slack’s prompt to invite the app. You can also run /invite @promptless. A private channel then appears in the dashboard’s channel pickers, with no refresh needed.

Update Slack permissions

As Promptless adds Slack features, the app sometimes requests new permissions. A workspace that connected before a permission was added lacks it until you grant it. The Slack card on the Integrations page then shows a Grant additional Slack permissions callout. The callout names each missing permission and what it’s for.

In the Grant additional Slack permissions callout, select Update connection.
In Slack, approve the added permissions.

Promptless swaps the stored token in place, so your workspace stays connected and your channel memberships and configuration don’t change. The callout only adds capability to a connection that already works. When the authorization itself lapses or is rejected, the card shows Needs reconnect instead. See Connection health.

Troubleshooting

Problem	Cause	Fix
A private channel doesn’t appear when you choose a notification channel or trigger source.	Promptless isn’t in the channel, or the workspace is missing `groups:read`.	Add Promptless to the channel. If the Slack card names `groups:read` as missing, update Slack permissions.
A shared suggestion link posts as plain text, with no preview card.	The workspace is missing `links:write`.	Update Slack permissions.
Someone who submitted a task through an MCP editor gets no DM when their suggestion is ready.	The workspace is missing `users:read.email`, so Promptless notifies the notification channel instead.	Update Slack permissions.
The MCP submitter still gets no DM after you grant `users:read.email`.	Their Slack account email differs from their Promptless account email, the address shown as “Authorize as {email}” when they authorized the MCP connection.	Use the same email address for both accounts. Updating Slack permissions doesn’t fix this case.
Promptless posts suggestion notifications in a public channel but doesn’t respond to replies in their threads.	Promptless couldn’t join the channel, often because the workspace is missing `channels:join`. Slack sends thread replies only to channel members.	Run `/invite @promptless` in the channel. Promptless then receives replies, including in threads it posted earlier. If the Slack card names `channels:join` as missing, also update Slack permissions.
Promptless isn’t reading a channel you configured for passive listening, and no error appears.	The channel is private or shared through Slack Connect, or the workspace is missing `channels:join`.	For a private or shared channel, add Promptless to it. For a public channel, update Slack permissions.

If a problem persists, contact help@gopromptless.ai.