Go to Slack

Quickstart: differences between old and new Slack apps

The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read first:Installing with OAuth
Read next:Reference: Token types
Open beta for new Slack apps

This sneaky preview gives you access to new features in Slack apps. Since we're still finalizing these apps, a few features may not yet have arrived. We expect the final version of new Slack apps to be available within a few months.

This quickstart guide explains how new Slack apps differ from existing, classic apps.

If you're starting from scratch as a new developer, or if you'd simply like a refresher from the ground up, start with our installation guide for new Slack apps.

Otherwise, peruse this luxurious catalog detailing what's new in the latest model of Slack apps.


Overview

Get started by creating a new Slack app:

Create an open beta Slack app

That way, you can easily follow along with your own app.

Note: right now, only new apps can enter the beta. However, migration for existing apps is coming soon!


Configuring your app

New Slack apps use bot users as the basis for API calls. You'll notice some resulting changes while developing your app.

First things first: select the OAuth & Permissions sidebar in your app management page. You'll see some changes:

  • You can now select individual scopes for your bot token, rather than just one umbrella bot scope that grants access to many methods, some of which you may not need.
  • If you select a scope under the Bot Token Scopes selector, and then click to install your app, you'll automatically gain a Bot User OAuth Access Token, with no corresponding user tokens.

Always assign scopes to your bot user token, rather than a user token. User token scopes should be selected only for user impersonation and listening to RTM.


Installing your app

When you want to install your new Slack app on other workspaces using OAuth, your app should redirect users to a new OAuth v2/authorize URL: slack.com/oauth/v2/authorize.

Once the user checks out the scopes you've requested and okays them, the user is redirected back to your app along with a temporary access code. Exchange the code for an API access token by calling a new OAuth v2.access method: oauth.v2.access.

Dive deeper into the new OAuth flow with this in-depth guide.

Here's the response you'll see from the v2.access method:

{
    "ok": true,
    "access_token": "xoxb-17653672481-19874698323-pdFZKVeTuE8sk7oOcBrzbqgy",
    "token_type": "bot",
    "scope": "commands,incoming-webhook",
    "bot_user_id": "U0KRQLJ9H",
    "app_id": "A0KRD7HC3",
    "team": {
        "name": "Slack Softball Team",
        "id": "T9TK3CUKW"
    },
    "enterprise": {
        "name": "slack-sports",
        "id": "E12345678"
    },
    "authed_user": {
        "id": "U1234",
        "scope": "chat:write",
        "access_token": "xoxp-1234",
        "token_type": "user"
    }
}

Here's a few important things to note:

  • The response from oauth.v2.access has a slightly different shape than from the previous, non-V2 endpoint. That's because we now present the bot user access token at the top level, not the user token. Check out the method documentation page for more detail.
  • Once you initiate OAuth with the new OAuth v2/authorize URL, you have to complete it with the new v2.access method—you can't comebine the v2/authorize URL with the old V1 access method.

Making API calls

Unlike tokens imbued with the old bot scope, your new API access token requests granular scopes for each method it wishes to call.

The granular scopes work exactly like the scopes applied to the old user token. However, your new API access token is a bot token, and as such it isn't tied to a specific user.

One effect worth noting: chat.postMessage and other chat.* methods no longer mess around with the as_user parameter. You're granted a single chat:write scope (no :user or :bot is appended). If you call the chat.postMessage method with your bot token, you post as the bot. If you've obtained a user token through the new install flow, and you call the method with your user token, you post as the user.

New bot user API access tokens 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), obtain a user access token from the OAuth & Permissions page in your app management UI, and use that user token to call rtm.start.


Receiving events

Your app receives only the events it has scopes to listen for. For example, subscribing to the channels_created event automatically means that your app requests the channels:read scope.


Using Slash commands

New: Bot users in new Slack apps may request the commands scope, allowing them to implement Slash commands.

Similar to the way that user deactivation for an installing user could deactivate a Slash command with older Slack apps, revoking the bot user token may cause the Slash command to be removed from a workspace.


Using Incoming Webhooks

New: Bot users in new Slack apps may request the incoming-webhook scope, allowing them to post messages via Incoming Webhooks.

Similar to the way that user deactivation for an installing user could deactivate a webhook with older Slack apps, revoking the bot user token may cause the webhook to be removed from a workspace.


Miscellaneous

Effects of user deactivation on tokens

Here's one big step forward for bots in new Slack apps: deactivation of an installing user no longer has an effect on the app.

Revoking tokens

For a new Slack app, bot user API access tokens are still revoked in the same way, via the auth.revoke method. When that happens:

  • The bot token no longer works.
  • The bot user is removed from the workspace.
  • Slash commands associated with the bot token will be removed from the workspace if no user tokens for the same app exist and carry the commands scope.
  • Incoming webhooks that were installed and associated with the bot token will be removed.
  • If no user tokens for the same app exist, the app will appear to be uninstalled from the workspace.

Migration

Right now, classic Slack apps can't be migrated into the new beta. Soon, that will change. In fact, simply installing your old app using the new OAuth flow will automatically migrate your bot to use new, granular scopes.

Coming soon