Skip to main content

Slack

Slack is a team communication tool that allows you to chat, share files, and collaborate with your team.

Authentication Types​

Slack supports 3 authentication methods:

  • OAuth - Create your own Slack app with custom scopes. Every user connects with their Slack account.

    • Pros: Full control, per-user tracking, production-ready
    • Cons: ~2 min setup
  • Instant OAuth - Use Willow's pre-configured Slack app for the fastest setup.

    • Pros: Fastest setup, no configuration needed
    • Cons: Limited scopes
  • API Key - Use a bot token or user token for all users.

    • Pros: Easy setup
    • Cons: Less secure, no per-user tracking

Setting up OAuth​

  1. Go to https://api.slack.com/apps

  2. Click Create New App

  3. Choose From scratch

  4. Enter an App Name and select the Workspace to develop in

  5. Click Create App

  6. In the left sidebar, go to OAuth & Permissions

  7. Scroll down to Scopes and add the User Token Scopes you need

  8. Scroll up and click Install to Workspace

  9. Review the permissions and click Allow

  10. In the left sidebar, go to Basic Information

  11. Under App Credentials, copy the Client ID and Client Secret

  12. In Willow, paste the Client ID and Client Secret

  13. Note the Redirect URL for your deployment:

    • For SaaS deployments: https://{org}.withwillow.ai/{org}/api/auth/callback
    • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback
  14. In Slack, go to OAuth & Permissions and add the Redirect URL under Redirect URLs

  15. In Willow, select the same scopes you configured in Slack

  16. Click Save Changes

OAuth Scopes​

The following scopes are available for Slack OAuth:

CategoryScopeAccess
Channels & Conversationschannels:historyRead
channels:readRead
channels:writeWrite
groups:historyRead
groups:readRead
groups:writeWrite
im:historyRead
im:readRead
im:writeWrite
mpim:historyRead
mpim:readRead
mpim:writeWrite
chat:writeWrite
Reactions & Pinsreactions:readRead
reactions:writeWrite
pins:readRead
pins:writeWrite
Bookmarksbookmarks:readRead
bookmarks:writeWrite
Remindersreminders:readRead
reminders:writeWrite
Canvases & Listscanvases:readRead
canvases:writeWrite
lists:readRead
lists:writeWrite
Filesfiles:readRead
files:writeWrite
Users & Workspaceteam:readRead
usergroups:readRead
usergroups:writeWrite
users:readRead
users:read.emailRead
users:writeWrite
users.profile:readRead
users.profile:writeWrite
Searchsearch:readRead
search:read.publicRead
search:read.privateRead
search:read.imRead
search:read.mpimRead
search:read.filesRead
search:read.usersRead

The search:read.* scopes are what the Search Messages (Real-time) and Semantic Search tools need, so a connection made before they were added must be reconnected before those tools work. Keep search:read as well: the legacy Search Messages tool still uses it. Scopes are granted when a user connects. The file tools (List Files, Get File Info, Download File) need files:read, so if a user's connection was made without it, those tools fail until the user reconnects Slack in Willow and approves all permissions.

Generating an API Key (Bot Token)​

  1. Go to https://api.slack.com/apps

  2. Select your app or create a new one

  3. Go to OAuth & Permissions

  4. Under Bot Token Scopes, add the scopes you need

  5. Install the app to your workspace

  6. Copy the Bot User OAuth Token (starts with xoxb-)

  7. Paste the token into Willow

Search tools​

  • Search Messages (Real-time) (search-messages-realtime) is the default keyword search, with Slack's query operators such as in:#channel, from:@user, exact phrases, and dates. It runs on Slack's Real-time Search API with semantic retrieval turned off, returns up to 20 messages per page, and pages with a cursor.
  • Search Messages (search-messages) is the legacy keyword search on Slack's search.messages method, which needs search:read. Slack is retiring that method, so the tool descriptions tell the AI client to use Search Messages (Real-time) first and to retry with this tool only when the real-time call fails with a permission error such as missing_scope or not_allowed_token_type.
  • Semantic Search (semantic-search) takes a natural-language question and returns relevant messages, files, and channels without exact keyword matches. It calls Slack's Real-time Search API. With a bot token (xoxb-), Slack requires an action_token from a Slack message event, so it works best with user-token OAuth connections.

If you connect through your own Slack app (OAuth), move message search to the Real-time Search API like this. Nothing breaks until you do, because the AI client falls back to the legacy tool.

  1. In Slack, open your app at api.slack.com/apps, go to OAuth & Permissions > User Token Scopes, and add search:read.public, search:read.private, search:read.im, and search:read.mpim. Add search:read.files and search:read.users as well if you want file and user results from Semantic Search. Keep your existing scopes, including search:read.
  2. In Willow, open the Slack server's Setup tab and add the same scopes under the OAuth scopes.
  3. Have each user disconnect and reconnect Slack in Willow once, so their connection picks up the new scopes.

Slack rate limits​

If a Slack tool fails with ratelimited and status 429, the limit came from Slack, not Willow. Slack counts calls per method, per Slack app, per workspace, so every token issued through the same Slack app in a workspace draws from one budget. Loops that call get_thread_replies or get_channel_history back to back are the usual cause. Wait the retryAfterSeconds in the error before retrying, space the calls out, and use Semantic Search rather than Search Messages for natural-language lookups, since it is a separate Slack method with its own limit. Slack publishes the limits in its rate limits documentation.

Restricting which channels tools can read​

Slack ships predefined conditions that keep sensitive channels out of reach of the model, without disabling the read tools entirely. Attach them to get_channel_history and get_thread_replies from the Tools tab:

ConditionEffect
Block specific channelsBlocks reads from the channels you select.
Block channels by nameBlocks reads from channels whose name matches a glob pattern, for example *sensitive* or exec-*. Applies to channels created later.
Only allow channels by nameBlocks every channel whose name matches none of your allowed patterns.

Slack also ships webhook conditions that filter workflow events by channel or user. See Conditions.