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
-
Click Create New App
-
Choose From scratch
-
Enter an App Name and select the Workspace to develop in
-
Click Create App
-
In the left sidebar, go to OAuth & Permissions
-
Scroll down to Scopes and add the User Token Scopes you need
-
Scroll up and click Install to Workspace
-
Review the permissions and click Allow
-
In the left sidebar, go to Basic Information
-
Under App Credentials, copy the Client ID and Client Secret
-
In Willow, paste the Client ID and Client Secret
-
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
- For SaaS deployments:
-
In Slack, go to OAuth & Permissions and add the Redirect URL under Redirect URLs
-
In Willow, select the same scopes you configured in Slack
-
Click Save Changes
OAuth Scopes
The following scopes are available for Slack OAuth:
| Category | Scope | Access |
|---|---|---|
| Channels & Conversations | channels:history | Read |
channels:read | Read | |
channels:write | Write | |
groups:history | Read | |
groups:read | Read | |
groups:write | Write | |
im:history | Read | |
im:read | Read | |
im:write | Write | |
mpim:history | Read | |
mpim:read | Read | |
mpim:write | Write | |
chat:write | Write | |
| Reactions & Pins | reactions:read | Read |
reactions:write | Write | |
pins:read | Read | |
pins:write | Write | |
| Bookmarks | bookmarks:read | Read |
bookmarks:write | Write | |
| Reminders | reminders:read | Read |
reminders:write | Write | |
| Canvases & Lists | canvases:read | Read |
canvases:write | Write | |
lists:read | Read | |
lists:write | Write | |
| Files | files:read | Read |
files:write | Write | |
| Users & Workspace | team:read | Read |
usergroups:read | Read | |
usergroups:write | Write | |
users:read | Read | |
users:read.email | Read | |
users:write | Write | |
users.profile:read | Read | |
users.profile:write | Write | |
| Search | search:read | Read |
search:read.public | Read | |
search:read.private | Read | |
search:read.im | Read | |
search:read.mpim | Read | |
search:read.files | Read | |
search:read.users | Read |
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)
-
Select your app or create a new one
-
Go to OAuth & Permissions
-
Under Bot Token Scopes, add the scopes you need
-
Install the app to your workspace
-
Copy the Bot User OAuth Token (starts with
xoxb-) -
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 asin:#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'ssearch.messagesmethod, which needssearch: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 asmissing_scopeornot_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 anaction_tokenfrom 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.
- 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, andsearch:read.mpim. Addsearch:read.filesandsearch:read.usersas well if you want file and user results from Semantic Search. Keep your existing scopes, includingsearch:read. - In Willow, open the Slack server's Setup tab and add the same scopes under the OAuth scopes.
- 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:
| Condition | Effect |
|---|---|
| Block specific channels | Blocks reads from the channels you select. |
| Block channels by name | Blocks reads from channels whose name matches a glob pattern, for example *sensitive* or exec-*. Applies to channels created later. |
| Only allow channels by name | Blocks 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.