Migration guide for classic Slack apps
If you're a developer who has built a Slack app before, you may know that apps have changed recently. With the help of explicit permissions tied to the app, rather than an installing user, new Slack apps are more pleasant to build and install.
New Slack apps act independently of an installing user. They have more functionality, and they're more likely to be approved by a Slack admin—and less likely to be accidentally uninstalled.
Good news: existing, classic Slack apps won't be left out in the cold. You can migrate an existing Slack app to use the sunny new system of permissions. Along the way, you'll gain more control over the permissions you request.
Before starting migration: if you've never built a Slack app before, you can read our guide to starting a new Slack app from scratch.
And if you've already got a new Slack app up and running, check out our overview of what's new in the world of Slack apps.
Otherwise, read on to start your app's great migration.
- Upating scopes with the update UI
- Update your OAuth flow
- Clean up
- Resubmit your app to the App Directory
Migrating your app is a trip in two parts.
First, you'll update your app's scopes on its Development Workspace, the workspace where you originally built and tested your app. Good news: to change the scopes your app has on the workspace, you'll follow the update UI and touch no code.
At the end of the update flow, you'll obtain a new OAuth redirect URL.
In the second part of migration, you change the URL to which you redirect users to initiate the v2 OAuth flow.
Start your journey of a few miles with a tiny first step—read on.
This section of the migration guide walks you through updating scopes for your app on its Development Workspace. That's the workspace where you first built and tested your app.
All of the migration here is powered by a UI. You won't have to touch a line of code.
Updating your app begins close to home: your app management page. When you navigate to your app's page, your classic Slack app will now display a Tools section in the sidebar.
Click on the Update to Granular Scopes button under the Tools section to begin your app migration.
Work through the checklist on the Update your app's scopes page to select the right scopes for your newly scope-conscious app.
The scope updater page does not automatically select the specific scopes your app needs. You'll still need to individually select the right scopes for your app.
Read through each part of the checklist and select scopes needed. If you're not sure whether you need a particular scope to call a Slack API method or listen to a Slack API event, look at the reference pages for methods and events to see details on what scopes are needed for each.
You'll notice that incoming webhooks and Slash commands are attached to your app's bot user only, rather than an authenticated user. That's great news: it means that webhooks and Slash commands no longer unexpectedly get uninstalled when an installing user departs. If you use either webhooks or Slash commands, add the
If your legacy app used the deprecated umbrella
bot scope, you'll see that all the scopes contained in it— all the permissions that the
bot scope previously conferred on your app—begin as checked in the checklist.
You probably don't need each of those scopes (for example, the
remote_files:* scopes are rarely required), which is why the old umbrella
bot scope caused some problems in the first place. Uncheck the scopes you don't want!
Next, you'll find fancy new features that previously required a user scope, now available to your app's bot user. Request these scopes for your bot and not the equivalent user token scopes.
Rule of thumb: new Slack apps do nearly all work from the perspective of the app, not from the perspective of an installing user. If you're not sure whether to select a bot scope or user scope, select it as a bot scope.
One last aside: if you're worried about taking a wrong step, remember that this update tool only applies to your app on its Development Workspace. Missteps are no big deal. If you miss a scope that your app eventually requires, your app will simply receive an error from Slack API noting which scope it needs. Once you add that scope, request it via the App Management page, and you'll be on your way.
After selecting all the bot user scopes your app needs, click Continue to select user scopes—i.e., scopes that allow you to act from the perspective of the installing user.
These scopes should be restricted or avoided if possible. Only request a scope for acting as your authenticating user if the action needs to be performed from the user's perspective: for example, reading or starting group DMs for a specific user.
New Slack apps may not access RTM. For most apps, the Events API lets your app listen to Slack goings-on in a more structured, safe way. If you require access to RTM (say, because you're building your app behind a corporate firewall), continue to use a classic Slack app bot token to call
After one more Continue, you'll find a Verification page that shows you all the scopes your app now requests during installation.
If the list seems long, rest assured that admins and installing users will now have a much clearer idea of what your app can actually do. And your app is less likely to be accidentally uninstalled if an installing user departs.
Click Yes, this looks good.
You'll see a button on the following page that allows you to reinstall your app with the new, granular scopes. Before you hit the button, copy down the OAuth redirect URL listed at the bottom of the page. You'll use that in part 2 of migration, where you slightly change your OAuth flow to receive granular scopes on other workspaces.
Click Reinstall. Congratulations, your app now uses new permissions on its Development Workspace and can act independently of the installing user!
If your app is not distributed beyond your development workspace, your great migration is complete. Touch down in the sand, stretch your feet out, grab some bread and coffee, and go on with life in the new land of apps. Check out the quickstart guide to see a list of differences between classic Slack apps and new, granular apps.
If your app is distributed to other workspaces, you'll want to update your OAuth flow. Read our guide to the Slack V2 OAuth flow.
Spoiler: you don't have much additional migration ahead of you. With the redirect URL obtained above, you'll automatically initiate the new V2 OAuth flow whenever you redirect a user. Then, you'll simply have to update to the
oauth.v2.access method, which you call after obtaining a temporary code from the installing user. After parsing the slightly different endpoint response, you'll be ready for reinstall.
Now that you've updated your code to the Slack V2 OAuth flow, you'll want to make sure your app is reinstalled on each workspace. You might gently direct users to reinstall with a DM containing an updated redirect to your oauth/v2/authorize URL. If you're comfortable forcing a reinstall, you can even use the auth.revoke method to revoke a previous installation on a given workspace.
Remember: there's no hurry to force a reinstall if you're comfortable dealing with two sets of scopes at once, depending on whether each installation of your app is a classic installation or uses the new V2 flow. However, for simplicity we think it's easiest to get all installations of your app updated to new permissions as soon as possible.
There's no automatic way to convert existing bot and user tokens into the new kind of app, except on your Development Workspace using the update UI.
If your app is listed in the App Directory, migrating your app requires more care. Upgrading your app to granular permission will likely mean creating a separate testing app that we can install and test.
As an example, if your app is called
cycling_tips, create a staging app called
cycling_tips-dev that we can install. You can use this staging app to test updates.
Creating a distributed, staging version of your app allows us to test how the new scopes will work on your app, leaving your published (live) app as is until those changes can be approved.
The staging app should use the same scopes requested in the resubmission for your published app.
You can add these details to the test instructions box in the "Help us review your app" section when you resubmit. If your web service requires an account or paid plan to access, please include test details for this as well.
If it's been a while since you’ve submitted your app, or if you're also making other changes to your app, please review our general guidelines again.
- Choose new scopes
- If you haven’t done so, create a separate Slack app for testing and use in development/staging environments e.g. [app_name]-staging Make sure that this app can be distributed on other workspaces.
- Use separate [app_name]-staging app to test the new scopes and OAuth endpoints. Ensure that the scopes on your staging app match the requested scopes in your resubmission.
- Test that code and features work
- Switch production app over to new scopes and endpoints
- Submit to App Directory with credentials and environment for test app
- Take app and new code live at the same time 🎉
- (Optional) Send message to existing users asking them to upgrade their app to granular permissions
Check out our quickstart guide for a rundown on updated behavior for new apps.
User scopes and tokens should only be requested as necessary when the app must perform an action on behalf of the user.
New Slack apps can explicitly request the ability to post in any public channel using the
Slack apps typically act and post on their own behalf. However, if you'd like to adjust the authorship of your app's messages, request the
chat:write.customize scope. Read the
chat.postMessage documentation for more details.
My app uses RTM, not supported by granular permissions. What do we need to do to migrate to the Events API?
If you are using RTM for security reasons with an app you’ve built for your own team (internal integration), please wait for our public release of Socket Mode in early 2021.
If your app is distributed, you’ll first need to identify the events your app is consuming from Slack’s RTM API and determine their equivalents in the Events API. Once you’ve done that work, you’ll need to configure event subscriptions in your app configuration, as well as an endpoint where Slack can send those event payloads. Store the data your app is consuming from the Events API as you currently do with RTM events.
Besides RTM being a much more robust and undiscerning stream of events from Slack, there are a few features not available in the Events API.
- Events API is not websocket-based
- Events API does not make the typing indicator available
- The team plan information available by calling rtm.start is not available via the Events API
bot scope consisted of many scopes that are now broken down and requested separately, allowing developers to request the least access possible on a Slack customer workspace. The new scopes are a better, more honest representation of the permissions your app has on a workspace. Please be sure to request only the scopes absolutely necessary to enable your app’s features in Slack. When your app goes to our App Directory team for review, they will review your app’s use of each scope.
If you still need to create a classic Slack app, either to use the
rtm.connect method, or for any other reason, click here:
In order to migrate users, direct them to reinstall via a DM containing an updated redirect to your
Will classic bot tokens still work after someone else has installed the app on the same workspace using V2 OAuth?
Classic bot tokens will continue to work after another user has installed the app using V2 OAuth.
No, once an app’s configuration has been migrated it’s no longer possible to use the V1 OAuth endpoint.
To assist with migrating to granular permissions, we recommend that developers create a separate Slack app for testing and use in their development/staging environments e.g. [app_name]-staging. This provides a few of key benefits:
It allows you to configure the app to work in your development/staging environment without impacting the settings for your published app e.g. you can use staging specific endpoints. It allows you to test new features and scopes (granular permissions) without being subject to the restrictions associated with your published app e.g. you can add new scopes/redirect URIs. It gives us a handy way to test new changes as part of reviewing resubmissions.
Use this app to test your granular permissions before adding these new scopes to your published app’s settings and resubmitting. Please be sure to include instructions for how to install the app you tested with in your submission.
Unfortunately there is no avoiding a small window of time where app installations cannot be performed while the switchover is taking place. The best way to coordinate this is to first deploy any code changes required to update the authorization flow, and then publish your app’s changes as the latter process will take effect almost instantaneously.
Submissions should be made as soon as possible, however some flexibility exists if it’s going to be tough to meet the December deadline. Submissions can be made by visiting our app portal, navigating to the app in question, and heading to the “Submit changes for review” section.
Yes, we can roll the app back to the previous set of non-granular scopes your app is using if you confirm the scope list with us. The most common reason for rollback is an app developer migrating an app’s OAuth settings and scope selections before any development work has been done.
Note: it is not a simple process and there may be a delay in the rollback.
December 4, 2020 - no updates accepted to App Directory listings using classic bot tokens.
November 18, 2021 - apps using classic bot tokens will be delisted from the App Directory.
Yes, you can do so until this date.
As part of reviewing your resubmission we need to be able to install and test a version of your Slack app that is using the new granular permissions e.g. the Slack app you use in your dev/staging environment.
Please note: we can't use your published app to test with as it is restricted to requesting approved scopes.