Distributing your app in the Slack App Directory
The Slack App Directory helps users discover apps. The apps published are ones that our review team determine to be high-quality, reliable, and useful.
You can distribute your apps without using the App Directory, but listing on the Directory can boost visibility and usage.
In this guide, we'll help you prepare your app for submission to the App Directory and outline that submission and review process. We'll also show you how you should maintain your listing after a successful review.
- Preparing your app for submission
- Submitting your app for review
- Maintaining your published app
- Testing and developing updates to an existing app
- Updating your published app
- Resubmitting your app with granular permissions
- Making app settings changes
- Discontinuing your published app
The process for getting apps published in the App Directory involves a manual review by our App Directory team. They will ensure that your app meets the quality and utility standards of App Directory apps.
There are a number of steps to follow before submitting your apps, so let's walk through them.
Before we go further, it's important to note that there are some types of apps that we aren't currently accepting in the App Directory. This includes apps that:
- export or backup message data;
- are built for the sole purpose of searching Slack messages outside Slack;
- use legacy scopes or methods (e.g. client, read, post);
- allow possibly destructive behaviour (e.g. deleting files);
- embed Slack into another site;
- only use Sign in with Slack functionality;
- replicate Slack client functionality, or are third-party Slack clients;
- request large number of scopes for simple, non-work related functionality;
- share sensitive information in Slack;
- circumvent admin features in Slack;
- do not provide any functionality we deem to be valuable in Slack.
This list is not exhaustive - the App Directory team may use their judgment to deny any app from being listed - but it's useful to know upfront when your app is not suitable.
If you think your app is suitable, keep reading to see the kinds of policies that listings in the App Directory are subject to, and how to prepare your app for review.
If you haven't enabled public distribution for your app, follow our guide to distributing apps publicly. This is a pre-requisite for submitting your app for App Directory review — you and your app won't make it far without doing this!
By distributing your app through the App Directory, you agree to abide by the following core policies and terms:
Apps that do not follow these terms will not be accepted in the App Directory.
You'll add Security & Compliance information during the App Directory submission process. Read our App Directory Guidelines for more information.
Beyond the strict policies and terms mentioned above, the App Directory team will generally ensure that your apps provide a great experience for users.
There are a number of resources that can help your app reach this point:
- Our interaction guidelines provide tips for making interactions with your app as pleasant and productive as possible.
- A set of design guidelines shows you how to optimize your app visually.
- Our guidelines for the App Directory outline how to raise your app's descriptive info to the App Directory listing standard.
Typically, App Directory apps must present users with a web page containing a link to Slack's OAuth installation flow. As users browse apps in the App Directory or a Slack client and encounter an app they want to install, they first must visit this page to initiate installation:
Save users a step by providing a Direct Install URL—a location on your site that simply redirects to the authorize step directly:
When your app is published in the App Directory, you can utilize this direct install flow.
Configure this link on your app's settings dashboard:
- Open the Basic Information page;
- Scroll down to Installing Your App;
- Select and enable Install from App Directory.
When you input and save your Direct Install URL, Slack will attempt to send a simple HTTP GET request to your declared URL.
That URL must then HTTP 302 redirect to a fully qualified
slack.com/oauth/authorize URL, as per the first step of the OAuth flow. You'll receive an error letting you know if the redirect wasn't successful.
If you ever need to revert to installation via your landing page, just configure your app again to use Install from your landing page in the dashboard.
Once you get published in the App Directory, Slack can suggest your app to new users. This will happen when links containing the domain name associated with your app are mentioned in conversation:
While managing your Slack app settings, you'll find a snippet of HTML customized for your app under Manage Distribution. It's a simple
META tag declaring your Slack app's ID, which typically begins with
A. If you already know the ID, you can build one of these tags yourself.
The snippet looks something like this:
<meta name="slack-app-id" content="YOUR_APP_ID_HERE">
Place this brief piece of HTML in your website template's
HEAD section, beside other metadata rubble you've accumulated, like so:
<html lang="en"> <head> <meta charset="utf-8"> <meta name="slack-app-id" content="YOUR_APP_ID_HERE"> <title>Beforebot highlights bots before it</title> </head> </html>
With this HTML in place - and once your app is listed in the App Directory - Slack is ready to suggest your app to new users on workspaces it isn't yet installed on.
Let's take a hypothetical example.
@beforebot is a Slack app in the directory that has placed its app ID meta tag in the template of all pages on
On a workspace where
@beforebot is not installed,
@seo posts a message talking about the link
Within moments of posting, Slack crawls the URL and extracts the app ID, correlating it to the
@beforebot app. Slackbot then posts an ephemeral message only
@seo can see:
This message contains the app's icon and short description, along with a link back to the app directory. It also contains three decisive links:
- Yes please takes
@seoto the app directory
- Not now will dismiss the ephemeral message but possibly suggest to
@seoagain when posting links to
- No thanks will dismiss the ephemeral message and won't prompt
@seoto install again
App suggestions are a great way for users and workspaces that are curious about, or already using your product or service to discover your Slack app.
Once installed, your app can attach custom unfurling behavior to relevant links shared in messages, among all the other nifty things bots and apps can do.
A review submission checklist is available within the Manage Distribution page of your app's settings dashboard - you can find it under the section called Submit to the Slack App Directory.
The comprehensive App Directory checklist covers the most common points of failure during reviews. Follow the checklist to help your app through the review process quickly and smoothly.
The checklist is interactive, allowing you to tick off the items as you complete them, showing your progress through the list. It will also highlight specific items that are missing or insufficient. You'll also have the opportunity to provide some information that will help our team to review your app, such as details of associated test accounts or mobile apps.
When you're done with the preparation of your app, and have gone through the submission checklist, you're ready to send your app for review.
- Go to your app's settings dashboard.
- Click into the Submit to App Directory page.
- Complete the checklist and click the Preview Submission button.
- On the Review Your App Submission modal, verify everything is correct, and click the Submit button.
Once we've reviewed your app, we'll email you. If your app is approved, you can then publish to the App Directory by returning to the app's settings dashboard.
Congratulations! You're now listed in the App Directory. Flocks of admiring visitors are now on their way to experience your wonderful app. You'll want to keep the place looking neat and tidy — keep reading to find out about our expectations for developers maintaining their apps in the App Directory.
The App Directory helps users find high-quality, dependable apps to aid in getting work done in Slack. This means that the process of getting published to the App Directory is not just about the initial submission and review.
In order to provide everyone with the highest quality experience when using apps from the App Directory we have some expectations around your app's performance, maintenance, support, and security standards.
Your app's listing is kept up to date.
Any changes to functionality, pricing, visual appearance, or any other updates should be accurately reflected in your app's listing.
Your app's functionality and customer experience matches or exceeds the quality of experience at submission, and you maintain your app’s performance.
You provide timely support to customers.
If we hear from customers that they’ve not received responses from their support requests, we will reach out to you. If we do not receive a prompt reply to our own messages to you, we may de-list your app.
You regularly update your app to ensure that it makes use of our newest platform security features.
We regularly add new security features to our API, so please make sure you’re using those that are applicable to your app. Stay up to date with those new features by subscribing to our changelog.
You keep your app contact details up to date and are responsive to messages from us.
We will occasionally need to get in touch with you with questions about your app or to resolve any issues.
Please make sure the developer and support contact details in your app submission are kept up to date so that we can contact you easily. Otherwise, you may miss important notices from us.
You must add a collaborator to your app.
Adding app collaborators ensures that multiple people can access your app’s configuration, in the event that the app creator leaves the associated workspace.
Edit your app's collaborator list by going to your app's settings dashboard and clicking into the Collaborators page.
You must resubmit your app for review when you make substantial changes or updates to the features, purpose or functionality of your app.
Your app is being actively used.
We want the App Directory to provide people with a choice of useful and used apps to help make their work days more productive. If your app is published in the App Directory but it is not being used, we will reach out to you to learn more about your plans for the app.
If you do not plan to update your app, or people continue not to use your app, we will delist your app after communication with you.
In order to do maintain the health of the App Directory and provide everyone with the best possible experience, there are circumstances in which we will contact you and possibly delist or take further action on your app.
We may contact you for response when:
- our expectations for published apps are not being met;
- we hear about issues from our mutual users, including but not limited to: spammy app behavior, broken or unexpected functionality, poor support experiences, lack of responses to support requests;
- we see increased instances of your app being uninstalled;
- we see large numbers of errors for your app;
If we do not hear back from you after reaching out to you for any reason, we will reach out again while simultaneously delisting your app to protect users. If we hear back from you, and confirm that issues are resolved, we'll be able to re-list your app.
We may delist your app without prior notice (other than to inform you of that action) when:
- your app's landing page or installation flow are broken;
- your app appears to be unmaintained or abandoned;
- your app's functionality changes substantially without notice and without the app being resubmitted for review.
We reserve the right to revoke access and tokens for your app if we receive no response from you about security-related issues.
Apps change, and that's a good thing. When you need to make changes to your app, deploy the updates with a test app (staging app) that will be identical to your published app so that you (and we!) can test during the review process. If you try to make these changes to your live app, it can break your app's experience for users.
For example, if your app is
cycling_tips, create a staging app called
cycling_tips-dev that can be distributed. Use this staging app to test updates to your app's functionalities, such as adding a new feature, scopes, or events.
A staging app should:
- have identical scopes of your submitted app
- be distributable on other workspaces
If you're making simple changes to your app's long description or app name, a test app isn't necessary, but we may still ask for one.
In order for us to test your app thoroughly please include any login credentials for any account or paid web service your staging app uses.
Changes that don't require a test app:
- Updating Display information (app name, descriptions, icon)
- Changes to pricing, languages your app supports
- Adding another instance of an existing functionality
Please note that in cases where you've added significant changes to an existing feature, (such as a very different shortcut or slash command), we may need a staging app for testing.
Changes that will require a test app:
- Enabling new functionalities to your app
- Toggling on Messages or App Home tabs for the first time
- Adding new scopes to your app
If you plan to make changes to the functionality of your app, you must submit those changes for review and approval. Before you do that, be sure to test and develop your changes using a separate test app, as described above.
Once you've tested your changes, you can resubmit for review:
- Open your app's settings dashboard
- Click Submit changes for review.
- Complete the submission checklist.
- Under the Help us review your app section, add information about the functionality changes you've made in the Other notes fields, as well as the testing information for your staging/test app and web service, if applicable.
- Click the Preview Submission button.
- On the Review Your App Submission modal, verify everything is correct, and click the Submit button.
If you maintain a classic Slack app in the App Directory, perhaps making use of the umbrella
bot scope, you'll want to migrate to new, granular permissions. Read on for a walkthrough on how to migrate your published App Directory app.
Note: Upgrading to new, granular permissions is a fundamental change to your app. It cannot be undone. Make sure you test your app fully, including your modified OAuth flow with updated scopes and provide a staging app with those scopes in your submission.
Read on for more details on migrating your App Directory app.
To migrate your app, you must upgrade your OAuth flow to use the Slack V2 of OAuth 2.0—if you do not upgrade your OAuth flow, you will not be able to use new permissions. Our quickstart will help you see the differences in new and old Slack apps at a glance.
The migration guide fully walks you through choosing new scopes and using the new OAuth flow, but here's a helpful tip: use only the absolute minimum number of scopes for your app to work. Do not automatically select all the scopes listed during migration.
The easiest way to find a minimum set of scopes is to list which API methods your app uses. Select the scopes needed for those methods. Avoid scope duplication: choose only the scopes you need for a bot token and any user tokens—and use the bot token unless you need to act on behalf of a specific user.
While updating your app to use new, granular permissions, you've most likely changed the scopes that your app requires. Your existing users will need to reinstall the app. To alert your users about those changes, consider using your app's App Home, or context block messages) from your app, to let users know an update is available.
When your app is published to the App Directory, you'll be able to safely make settings changes in the dashboard.
Changes made in this dashboard won't affect a published app until you submit the app for re-review (as above) and this review is successful.
You can view the settings that apply to the published app under the Published app settings section of the dashboard.
You can remove your published app from the App Directory in the Published app settings section of your app's settings dashboard.
If your app is no longer being actively maintained or developed, you should ensure you adequately sunset your app by: