Slack integration

Used for: Triggers and Context

Promptless integrates with Slack through our official Slack App, enabling automated documentation updates based on team communication and support conversations.

Promptless does not archive or store your Slack messages.

Disclaimer: Promptless uses large language models (LLMs), which can generate inaccurate results.

Installation

1. Click “Connect Slack” from the integrations page.

2. Slack opens in a new window, where you install the Promptless app. Be sure to select the right workspace to install Promptless. If your browser blocks the window, allow pop-ups for Promptless and select Connect Slack again.

3. Review and approve the requested permissions for the Promptless Slack app. Promptless requires these permissions to be able to be triggered from the right events in Slack and to notify your team when updates are available.

Understanding Slack Permissions

By default, Promptless only accesses Slack content when you explicitly trigger it by tagging @Promptless or using the “Update Docs” message action. If you enable passive listening, Promptless monitors only the specific channels you select.

Key permissions

Promptless requests these Slack permissions:

• channels:read and groups:read: List available channels and groups
• channels:join: Join a public channel when you configure it for passive listening, so you don’t have to invite Promptless manually
• chat:write: Send messages and notifications to channels where Promptless is invited
• files:write: Attach diff files to Slack threads when notifying about documentation changes
• links:read and links:write: Render preview cards when a Promptless suggestion link is shared in Slack
• users:read: Look up user information for mentions and notifications
• users:read.email: Match a documentation task’s submitter to their Slack account by email to send a direct-message notification

The groups:read permission lets Promptless list the private channels in your workspace, so you can choose one as a notification channel or trigger source. If your workspace is missing this or any other permission Promptless requests, the Slack card shows a Grant additional Slack permissions callout. The callout names each missing permission along with a short description of what it’s used for. See Update Slack permissions to add it.

The files:write permission lets Promptless attach diff files directly in Slack threads, so you can review proposed changes without leaving Slack. If this permission isn’t granted, Promptless links to the dashboard instead.

The links:read and links:write permissions let Promptless render a preview card when someone shares a suggestion link in Slack. If links:write isn’t granted, the link posts as plain text with no preview card.

The users:read.email permission lets Promptless send a direct message to the person who submitted a documentation task through an MCP editor. The message goes out when their suggestion is ready for review. Without it, Promptless notifies the configured notification channel instead. If you connected Slack before this permission was added, see Update Slack permissions to add it.

The channels:join permission lets Promptless join a public channel when you configure it for passive listening. If you connected Slack before this permission was added, reconnect to grant it, or Promptless can’t join those channels for you.

4. Verify that Slack is connected in the integrations page.

When admin approval is required

Some Slack workspaces require an admin to approve apps before they can be installed. If you’re not a workspace admin, Slack sends your request to an admin. The steps are the same from onboarding and the integrations page, and your pending request persists across page reloads and sessions.

1. Complete the Slack window: Follow Slack’s prompts in the window that opened. Slack may notify you when an admin approves Promptless.
2. Track your pending request: 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 until you finish the install.
3. Finish connecting: After an admin approves, select Continue in Slack on the pending card. This re-runs Slack authorization 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.

Update Slack permissions

As Promptless adds Slack features, the app sometimes needs new permissions. A workspace you connected before a permission was introduced lacks that permission until you grant it.

Whenever your workspace is missing any bot permission Promptless currently requests, the Slack card on the integrations page shows a Grant additional Slack permissions callout. The callout names each missing permission along with a short description of what it’s used for, and includes an Update connection button. Click Update connection to re-run Slack authorization, then approve the request in Slack. Your existing connection stays intact: Promptless swaps the stored token in place, so your channel memberships and configuration stay exactly as they were.

This callout is informational, since the connection already works and granting the permission only adds capability. A genuinely lapsed or rejected authorization is a different case: the card flags it as Needs reconnect instead. See Connection health for that flow.

What you can do with Slack

Once connected, you can use Slack for:

• Triggers: Tag @Promptless or use message actions to trigger documentation updates
• Context Sources: Search Slack conversations for team discussions and decisions
• Configuration: Ask Promptless to update your triggers, doc collections, and other configuration directly

Privacy and channel access

By default, Promptless only reads Slack content when you explicitly trigger it by tagging @Promptless or using the “Update Docs” message action. If you enable passive listening in your configuration, Promptless monitors only the specific channels you configure. When you configure a public channel, Promptless joins it. Channels shared with another workspace through Slack Connect still need a manual invite, like private channels do.

Add Promptless to private channels

Promptless can’t join a private channel or a channel shared with another workspace through Slack Connect on its own. To read messages there, add Promptless yourself. Tag @Promptless in that channel, and Slack prompts you to invite the app. Inviting Promptless this way is also how the channel becomes available in dashboard channel pickers, such as when you choose a notification channel. You don’t need to refresh the Slack integration separately.

This is required if you want to:

• Use a private channel as your notification channel for suggestions
• Trigger Promptless from messages in a private channel
• Enable passive listening on a private channel

Troubleshooting

Private channels not listing

A private channel may not appear when you’re choosing a notification channel or trigger source. If so, your Slack integration is likely missing the groups:read permission, which lets Promptless list private channels. This can happen if your workspace connected before Promptless requested groups:read, or is otherwise missing it. The Slack card shows a Grant additional Slack permissions callout naming groups:read.

To fix this, re-authorize the Slack integration:

1. Go to the integrations page.
2. On the Slack card, click Update connection in the Grant additional Slack permissions callout, which names the missing permission.
3. Approve the added permission in Slack.

Reconnecting keeps your workspace connected and preserves public-channel access throughout. After re-authorizing, Promptless can list private channels again. If issues persist, contact help@gopromptless.ai.

Diff files not appearing in Slack threads

If Promptless notifications appear in Slack but diff files aren’t attached, your Slack integration may be missing the files:write permission. This can happen if you connected Slack before this permission was added to the Promptless app.

To fix this, re-authorize the Slack integration:

1. Go to the integrations page.
2. On the Slack card, click Update connection in the Grant additional Slack permissions callout, which names the missing permission.
3. Approve the added permissions in Slack.

Reconnecting keeps your workspace connected while granting the missing permission. After re-authorizing, diff files appear as thread attachments. If issues persist, contact help@gopromptless.ai.

Suggestion link previews not rendering in Slack

If sharing a Promptless suggestion link in Slack posts as plain text instead of a preview card, your Slack integration may be missing the links:write permission. This can happen if you connected Slack before this permission was added to the Promptless app. The integrations page shows a Grant additional Slack permissions callout on the Slack card, naming the missing permission.

To fix this, re-authorize the Slack integration:

1. Go to the integrations page.
2. On the Slack card, click Update connection in the Grant additional Slack permissions callout, which names the missing permission.
3. Approve the added permissions in Slack.

Reconnecting keeps your workspace connected while granting the missing permission. After re-authorizing, shared suggestion links render as preview cards. If issues persist, contact help@gopromptless.ai.

Direct-message notifications not arriving for MCP submitters

People who submit documentation tasks through an MCP editor might not receive a direct message when their suggestion is ready. One of two causes is usually behind it.

Your Slack integration may be missing the users:read.email permission. This can happen if you connected Slack before this permission was added to the Promptless app. To fix it, re-authorize the Slack integration:

1. Go to the integrations page.
2. On the Slack card, click Update connection in the Grant additional Slack permissions callout, which names the missing permission.
3. Approve the added permissions in Slack.

Reconnecting keeps your workspace connected while granting the missing permission. After re-authorizing, submitters receive direct-message notifications again when the missing permission was the cause.

Otherwise, the submitter’s Slack account email may not match their Promptless account email. That is the address shown as “Authorize as {email}” when they authorized the MCP connection. When the two differ, Promptless can’t identify the submitter’s Slack account and falls back to the configured notification channel. Reconnecting doesn’t resolve this: the submitter’s Slack account email and their Promptless account email must be the same address. If issues persist, contact help@gopromptless.ai.

Passive listening not reading a configured channel

You configured a channel for passive listening, but Promptless isn’t reading it or producing anything. One of two things is usually keeping Promptless out, and a failed join never surfaces as an error. Check these two causes first.

The channel may be private, or a channel shared with another workspace through Slack Connect. Promptless can’t join those on its own, so add Promptless to the channel in Slack: tag @Promptless in the channel, or run /invite @promptless.

Otherwise, the workspace may have connected Slack before the channels:join permission was added, so Promptless can’t join the public channels you configure. Reconnect on the integrations page to grant it. If issues persist, contact help@gopromptless.ai.

For more details about using Slack with Promptless, see Reviewing from Slack and Teams.