Migration guide for classic Slack apps

The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read first:Installation & permissions
Read next:Quickstart: differences between old and new 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.

Overview

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.

Link to new scope update tool found in app management page

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.

The v2 OAuth flow is nearly identical to the old OAuth flow. The only differences are a couple new v2s added to method names and a slightly altered structure for the final oauth.v2.access response.

Start your journey of a few miles with a tiny first step—read on.

Updating scopes with the update UI

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.

Start an app migration

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.

Select bot user scopes

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 incoming-webhook or commands scopes.

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.

Select authenticated user scopes

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 rtm.connect.

Reinstall your app

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!

Update your OAuth flow

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.

Clean up

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.

Frequently Asked Questions

Why can't I use the as_user parameter for chat.postMessage any more?

Slack apps act on their own behalf. There's no need for an as_user parameter when posting a message, because Slack apps post as themselves.

[chat.postMessage] no longer accepts an as_user argument from new Slack apps.

How do I create a classic Slack app?

If you still need to create a classic Slack app, either to use the rtm.connect method, or for any other reason, click here:

Create a classic Slack app

Do I need to be a member of a channel to post a message?

Currently, your app must be a member of any channel it wishes to post messages to. To join a channel, request the channels:join scope and call the conversations.join method. However, apps will soon be able to post in any public channel, without gaining additional access to the channel, by requesting a new scope.

Can I automatically determine which new scopes my app needs?

At this time, there's no way for Slack to determine which scopes your app needs. You'll have to run through each method and event that your app makes use of, requesting the scope for each.

How do new Slack apps differ from classic Slack apps?

Check out our quickstart guide for a rundown on updated behavior for new apps.