Caddi connects to Slack through an app you create at api.slack.com. The one concept worth understanding before you start is that Slack issues two kinds of token from a single install, and which capabilities you get depends on which one you configure.
Bot tokens vs user tokens. A Slack app can receive a bot token (the app acts as itself, and keeps working when the installing person leaves) and a user token (the app acts as that person). They are not interchangeable, and the same capability often has a different scope name on each.
Most Caddi loops want bot token scopes. Searching Slack messages is the exception — it requires a user token, because Slack provides no bot equivalent.
If your loops read large volumes of channel history, read the note on rate limits under How the connection behaves before rolling out. Slack tightened limits on conversations.history and conversations.replies for newly-created apps that aren't Slack Marketplace–approved.
Before you start
You'll need:
A Slack account in the workspace where you'll create the app — any plan works
Owner or Admin access to your Caddi organization
A Slack Owner or Admin to approve the install if your workspace has app approval enabled
Step 1: Create the app
Go to api.slack.com/apps and click Create New App → From scratch.
Name it
Caddiand pick the workspace to develop in.Click Create App.
Step 2: Add the redirect URL and scopes
Watch for the asymmetric pairs. channels:manage is bot-only; channels:write is user-only. They do similar things but belong in different sections. Leave all admin.* scopes off — those are Enterprise Grid administration.
In the left sidebar, open OAuth & Permissions.
Under Redirect URLs, click Add New Redirect URL, enter
https://app.trycaddi.com/oauth-callback, click Add, then Save URLs.Scroll to Scopes and add them in the two sections separately:
Bot Token Scopes — a good working set is
channels:read,channels:history,channels:join,channels:manage,groups:read,groups:history,groups:write,im:read,im:history,im:write,chat:write,chat:write.public,files:read,files:write,reactions:read,reactions:write,users:read,users:read.email,team:readUser Token Scopes — add
search:readif any loop needs to search Slack messages. Slack has no bot equivalent for search, so without this those loops cannot work.
Open Basic Information → App Credentials and copy the Client ID and Client Secret.
Step 3: Activate public distribution
Required if the app will be installed into any workspace other than the one you created it in. This is *unlisted* distribution and needs no Slack review.
Open Manage Distribution in the sidebar.
Work through the Share Your App with Other Workspaces checklist.
Click Activate Public Distribution.
Listing in the Slack Marketplace is a separate, reviewed process. It's optional — but see the rate-limit note below, because it has practical consequences.
Step 4: Configure Slack in Caddi
This step must be completed by a Caddi organization owner or admin.
In Caddi, open Integrations in the left sidebar, then click the Integration Setup tab at the top of the page. This tab is only visible to organization owners and admins.
Find Slack in the list and click Configure.
Enter the following values:
Client ID — from Basic Information → App Credentials
Client Secret — from the same section. This is behind a Show button and can be viewed again later.
OAuth Scopes — space-separated list matching what you configured on the app. Leave blank to use Caddi's defaults.
Click Save Configuration. Caddi validates the credentials immediately — if something is wrong you'll see an error right away, and nothing is stored until validation passes.
Step 5: Connect your account
Go back to the My Connections tab and find Slack.
Click Connect + and choose the Slack workspace.
Review the permissions and click Allow. If your workspace requires admin approval, this becomes a request an Owner or Admin has to approve.
You'll be returned to Caddi with the connection active.
How the connection behaves
Bot tokens survive staff changes; user tokens don't. A bot token keeps working when the installing person leaves; anything relying on a user token stops.
Access tokens do not expire by default. If you enable token rotation on the app, access tokens expire every 12 hours and each refresh revokes the previous refresh token — Caddi handles the rotation.
Rate limits are per method, per workspace, per app. Since May 2025, newly created apps that are commercially distributed but not Marketplace-approved get materially stricter limits on
conversations.historyandconversations.replies. Internal customer-built apps and Marketplace-approved apps are exempt. If your loops read channel history at volume, factor this in.Users can decline optional scopes, so a connection may come back with less access than you configured.
A custom connection replaces the standard one. Members of your organization will only see the option to connect through your app.
Revoking access. Uninstall the app from the Slack workspace, or delete it at api.slack.com.
Troubleshooting
Loops can't search Slack messages
Message search requires a user token with search:read. Add it under User Token Scopes — not Bot Token Scopes — and have users reconnect.
Caddi can't post to a public channel it hasn't joined
Add the chat:write.public bot scope, which allows posting without joining.
Installing into a second workspace fails
Public distribution isn't activated. Open Manage Distribution and activate it — no Slack review is needed for unlisted distribution.
Install turns into a pending request
App approval is enabled in that workspace. A Slack Owner or Admin needs to approve it.
History-reading loops are throttled heavily
Post-May-2025 rate limits on conversations.history for non-Marketplace apps. Narrow the channels and date ranges the loop reads, or contact Caddi support to discuss options.
A redirect error at sign-in
The redirect URL must be HTTPS, cannot contain a # fragment, and must match https://app.trycaddi.com/oauth-callback or be a subdirectory of a configured URL.
Still stuck? Contact Caddi support with the exact error message you're seeing and the time it occurred.
Automation ideas
Law Firms
Slack request → tracked matter task
Caddi reads a request in a practice-group channel, creates the task against the right matter, and posts back the confirmation with a link.
Matter milestone → channel update
When a filing goes out or a deadline shifts, Caddi posts the update to the matter's channel so the team doesn't have to check the system.
Client communication in Slack → matter record
Caddi logs relevant Slack threads to the matter file, keeping a complete communication record without copy-paste.
RIAs
Advisor request → operations ticket
Caddi turns requests posted in an operations channel into tracked work items and reports completion back in the thread.
Compliance flag → escalation thread
When a monitoring loop flags something, Caddi opens the escalation thread with the relevant detail already attached.