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.
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
Then, if your app also creates a channel, it requires the
conversations.create method, which works with the
Next, work with the Slack Web API methods using the Apex classes. In this case,
conversations.list corresponds to the
ConversationsListResponse Apex classes.
Here's a list of basic scopes common to Slack apps created with Apex SDK for Slack.
|channels:read||bot, user||View basic information about public channels in a workspace|
|channels:history||bot, user||View messages and other content in public channels that your slack app has been added to|
|chat:write||bot, user||Post messages in approved channels and conversations|
|chat:write.customize||bot||Send messages as @your_slack_app with a customized username and avatar|
|commands||bot, user||Add shortcuts and slash commands that your app users can run|
|groups:history||bot, user||View messages and other content in private channels that your slack app has been added to|
|groups:read||bot, user||View basic information about private channels that your slack app has been added to|
|im:history||bot, user||View messages and other content in direct messages that your slack app has been added to|
|reactions:read||bot, user||View 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
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.
Alternatively, set the
chat:write.customize scopes on the bot token while setting the
icon_url properties. The
chat:write.customize scope sends messages as
@your_slack_app with a customized username and avatar.
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
BotsInfoResponse classes. See API methods available to bots.
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.
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.
Update scopes in your
<appname>.slackapp-meta.xmlfile. See SlackApp.
Deploy your scope update to your org.
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.
- To update the Slack app in the Slack app directory, get the app re-approved.