# 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](https://api.slack.com/scopes), your app most likely only needs a handful of them. When creating your Slack app at [api.slack.com/apps/](https://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](/docs/platform/salesforce-slack-sdk/guide/setup-install-app.md) for an example manifest. ## Determine Your Scopes To determine which scopes your app needs, understand which [events](https://api.slack.com/events) or [methods](https://api.slack.com/methods) your app requires first. For example, if your app checks if a private or public channel exists, it requires the [`conversations.list` method](https://api.slack.com/methods/conversations.list) 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](https://api.slack.com/methods/conversations.create), which works with the `channels:manage` scope. Next, work with the Slack Web API methods using the [Apex classes](/docs/platform/salesforce-slack-sdk/guide/apex_ref.md). In this case, `conversations.list` corresponds to the [`ConversationsListRequest` and `ConversationsListResponse` Apex classes](/docs/platform/salesforce-slack-sdk/guide/apex_ref_conversations.md). ## Basic Scopes Here's a list of basic scopes common to Slack apps created with Apex SDK for Slack. | Scope | Token Type | Description | | ------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | | [channels:read](https://api.slack.com/scopes/channels:read) | bot, user | View basic information about public channels in a workspace | | [channels:history](https://api.slack.com/scopes/channels:history) | bot, user | View messages and other content in public channels that your slack app has been added to | | [chat:write](https://api.slack.com/scopes/chat:write) | bot, user | Post messages in approved channels and conversations | | [chat:write.customize](https://api.slack.com/scopes/chat:write.customize) | bot | Send messages as @your_slack_app with a customized username and avatar | | [commands](https://api.slack.com/scopes/commands) | bot, user | Add shortcuts and slash commands that your app users can run | | [groups:history](https://api.slack.com/scopes/groups:history) | bot, user | View messages and other content in private channels that your slack app has been added to | | [groups:read](https://api.slack.com/scopes/groups:read) | bot, user | View basic information about private channels that your slack app has been added to | | [im:history](https://api.slack.com/scopes/im:history) | bot, user | View messages and other content in direct messages that your slack app has been added to | | [reactions:read](https://api.slack.com/scopes/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](https://api.slack.com/scopes). ## Bot Token and User Token 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. :::tip 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`](https://api.slack.com/methods/chat.postMessage#channels), which is handled by the Apex [`ChatPostMessageRequest` and `ChatPostMessageResponse` classes](/docs/platform/salesforce-slack-sdk/guide/apex_ref_chat.md). ![Required scopes in Slack API docs](https://a.sfdcstatic.com/developer-website/sfdocs/salesforce-slack-sdk/media/slack_api_docs.png) ### 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`](https://api.slack.com/scopes/chat\:write), which enables your app to post messages in approved channels and conversations. ![Post a message using the bot token](https://a.sfdcstatic.com/developer-website/sfdocs/salesforce-slack-sdk/media/bot_token_post.png) 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](https://a.sfdcstatic.com/developer-website/sfdocs/salesforce-slack-sdk/media/bot_token_customize_post.png) :::important 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](https://api.slack.com/methods/chat.postMessage#authorship). ::: Bot users and bot tokens can be used with a restricted set of Slack Web API methods. For example, [`bots.info`](https://api.slack.com/methods/bots.info) is handled by the Apex [`BotsInfoRequest` and `BotsInfoResponse` classes](/docs/platform/salesforce-slack-sdk/guide/apex_ref_bot.md). See [API methods available to bots](https://api.slack.com/bot-users#bot_methods). ### 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`](https://api.slack.com/scopes/chat\:write), which enables your app to post messages on the user's behalf. ![Post a message using the user token](https://a.sfdcstatic.com/developer-website/sfdocs/salesforce-slack-sdk/media/user_token_post.png) :::important 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](https://api.slack.com/methods/chat.postMessage#authorship). ::: ### 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 `.slackapp-meta.xml` file. See [SlackApp](/docs/platform/salesforce-slack-sdk/guide/meta_slackapp.md). 2. Deploy your scope update to your org. 3. Update the scopes from for your app in the Slack app manifest. To find the Slack App manifest: - View your Slack apps at [api.slack.com/apps](https://api.slack.com/apps). - Select the app you want to view from the list. - In the sidebar, select **Features > App Manifest**. :::tip 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. ::: 4. To update the Slack app in the Slack app directory, get the app re-approved. ## See Also - [Access Tokens](https://api.slack.com/authentication/token-types) - [Understanding OAuth scopes for Bots](https://api.slack.com/tutorials/understanding-oauth-scopes-bot)