Conversations API and new scopes available for workspace apps

Workspace apps can now use a simplified interface for working with the Conversations API methods. A workspace app can request three new scopes: conversations:history, conversations:read, and conversations:write. These three scopes cast an umbrella of permission over each different conversation type: channels, DMs, or anything in between.

These new scopes make it even easier to use Conversations API methods, allowing apps to negotiate permissions for, and then interact with, all types of conversations at once.

What's changing?

Workspace apps can now make full use of our Conversations API methods, using a simplified scope model that covers all conversation types. To use the Conversations API, your workspace app can request three scopes: conversations:history, conversations:read, and conversations:write.

The workspace permission model revolves around the specific resources awarded to your app. By using our new scopes with the Conversations API, your app can ignore the many scopes pinned to specific conversation types. This way, your app can use a normalized interface for all types of conversations: public, private, or otherwise.

Use new scopes that match the Conversations API methods

We already made similar logical changes to our API by introducing the Conversations API methods. With the conversations.list method, for example, we return all conversations that the requester should be able to see, regardless of whether they're private channels, public channels, or direct messages.

Now, if a workspace app calls conversations.list, it'll find all the conversations the app is entitled to participate in, right in one place.

Request the new scopes that cover all conversations, instead of individual scopes for each type

These new shiny scopes cover all that workspace apps need to converse, so we're deprecating use of the older scopes by workspace apps:

• im:history
• mpim:history
• groups:history
• channels:history
• im:read
• mpim:read
• groups:read
• channels:read
• im:write
• mpim:write
• groups:write
• channels:write

You'll have plenty of time to migrate your app to the new conversations scopes before the old ones are retired.

To rid your app of deprecated scopes, just head to the OAuth & Permissions panel of your Slack app management console and click the trash button next to the scopes you no longer need:

What isn't changing?

Conversations API methods like conversations.list will continue to accept the old type-specific scopes, even from workspace apps, for now. However, we strongly encourage workspace apps to upgrade to the umbrella conversations: scopes. They're just better.

How do I prepare?

Visit the OAuth & Permissions panel of your Slack app management console to request the new scopes and stop requesting the old ones.

Be sure to reinstall your app to take advantage of the new scopes!

If you're installing your app on multiple workspaces, chances are high that you've entered into the brave new-ish world of OAuth. In that case, you'll want to change the URI you redirect your users to by passing the new conversations scopes among the GET parameters.

Finally, if you're requesting any of these deprecated scopes via the Permissions API for the purpose of progressively gaining permissions: hooray! Gold star for you. You can request the new scopes directly in calls to apps.permissions.request.

When did this happen?

We launched these changes today, June 22, 2018.