Permission Scopes

Permission scopes grant access for your app to perform functionalities in Slack. They define the API methods your app is allowed to call. Although Slack provides a comprehensive list of permission scopes, your app most likely only needs a handful of them.

When creating your Slack app at api.slack.com/apps/, you can add or remove scopes in one of several ways.

  • In the app manifest on the App Manifest page
  • On the OAuth & Permissions page

See Sample Apex SDK for Slack App for an example manifest.

To determine which scopes your app needs, understand which events or methods your app requires first.

For example, if your app checks if a private or public channel exists, it requires the conversations.list method so you can get the names of private and public channels. You can then determine that your app needs the channels:read and groups:read scopes.

Then, if your app also creates a channel, it requires the conversations.create method, which works with the channels:manage scope.

Next, work with the Slack Web API methods using the Apex classes. In this case, conversations.list corresponds to the ConversationsListRequest and ConversationsListResponse Apex classes.

Here's a list of basic scopes common to Slack apps created with Apex SDK for Slack.

ScopeToken TypeDescription
channels:readbot, userView basic information about public channels in a workspace
channels:historybot, userView messages and other content in public channels that your slack app has been added to
chat:writebot, userPost messages in approved channels and conversations
chat:write.customizebotSend messages as @your_slack_app with a customized username and avatar
commandsbot, userAdd shortcuts and slash commands that your app users can run
groups:historybot, userView messages and other content in private channels that your slack app has been added to
groups:readbot, userView basic information about private channels that your slack app has been added to
im:historybot, userView messages and other content in direct messages that your slack app has been added to
reactions:readbot, userView emoji reactions and their associated content in channels and conversations that your slack app has been added to

For the complete list of scopes, see Permission scopes.

Some scopes are unique to a particular token type, for example, bot or user token.

  • Bot tokens are ideal for most apps. They provide granular permissions to request only the scopes your app needs.

  • User tokens allow you to work directly on behalf of users.

The permission scope to perform a task can often apply to both the bot or user. When picking either a bot or user token for your app to perform tasks, consider your user's experience. It depends on what your bot is allowed to do based on its permissions and what your users are allowed to do in a workspace.

We recommend that you review the Slack API docs for supported permission scopes and any corresponding restrictions on them.

For example, bots are only allowed to post in channels where they are members. Bots can't post to a DM conversation between two users using chat.postMessage, which is handled by the Apex ChatPostMessageRequest and ChatPostMessageResponse classes.

Required scopes in Slack API docs

Bot Tokens

Bot token strings begin with xoxb-. Bot tokens are not tied to a user's identity and will remain installed when an installing user is deactivated.

One of the most common scopes your app can use with a bot token is chat:write, which enables your app to post messages in approved channels and conversations.

Post a message using the bot token

Alternatively, set the chat:write and chat:write.customize scopes on the bot token while setting the username and icon_url properties. The chat:write.customize scope sends messages as @your_slack_app with a customized username and avatar.

Post a message using the chat.customize scope on the bot token

Consider using chat:write.customize only in response to an inciting user action and inform users that a message will be posted on their behalf. See Sending messages as other entities.

Bot users and bot tokens can be used with a restricted set of Slack Web API methods. For example, bots.info is handled by the Apex BotsInfoRequest and BotsInfoResponse classes. See API methods available to bots.

User Tokens

User token strings begin with xoxp-. Use user tokens with care as they take actions on behalf of users.

One of the most common scopes your app can use with a user token is chat:write, which enables your app to post messages on the user's behalf.

Post a message using the user token

Consider using chat:write scope on the user token only in response to an inciting user action and inform users that a message will be posted on their behalf. See Sending messages as other entities.

Considerations and Limitations

Updating scopes in Slack or a Slack app can cause installation issues if the scopes become out of sync with the Slack app's core definition.

We recommend updating your scopes as follows.

  1. Update scopes in your <appname>.slackapp-meta.xml file. See SlackApp.

  2. Deploy your scope update to your org.

  3. Update the scopes from http://api.slack.com/ for your app in the Slack app manifest. To find the Slack App manifest:

    • View your Slack apps at api.slack.com/apps.
    • Select the app you want to view from the list.
    • In the sidebar, select Features > App Manifest.

You must be a collaborator on the app in order to see the app in your list. If you don’t see the app, reach out to the app owner.

  1. To update the Slack app in the Slack app directory, get the app re-approved.