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

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.

Check your app is suitable

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, scopes that provide extensive access to workspace data, or workflow automations scopes (e.g. client, read, post, search:read, admin.*, identity.*, workflow.steps:execute, user token *:history, triggers:*).
  • allow possibly destructive behavior (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.
  • are installed on less than 10 active workspaces. An active workspace is a workspace that has been used in the past 28 days.
  • enable financial transactions, including cryptocurrency transactions, or the minting or transfer of NFTs in Slack.

In addition, workflow automations are currently not eligible for listing in the App Directory.

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.

Prepare your app for public distribution

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!

Read our terms and policies

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.

Security and Compliance

You'll add Security & Compliance information during the App Directory submission process. Read our App Directory Guidelines for more information.

Providing a great experience

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 some resources that can help your app reach this point:

Make installation more direct

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:

Install from your landing page

Save users a step by providing a Direct Install URL—a location on your site that redirects to the authorize step directly:

Install from App Directory

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 an HTTP GET request to your declared URL.

That URL must then HTTP 302 redirect to a fully qualified slack.com/oauth/v2/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.

Boost app discovery using App Suggestions

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:

An example app suggestion for an app called Paraglider.

Enabling app suggestions

While managing your Slack app settings, you'll find a snippet of HTML customized for your app under Manage Distribution. It's a 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">
        <meta charset="utf-8">
        <meta name="slack-app-id" content="YOUR_APP_ID_HERE">
        <title>Beforebot highlights bots before it</title>

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.

How app suggestions are triggered

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 https://before.bot/.

On a workspace where @beforebot is not installed, @seo posts a message talking about the link https://before.bot/movies/flight-of-the-navigator/trimaxion.

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:

An example app suggestion for a bot called @beforebot.

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 @seo to the app directory
  • Not now will dismiss the ephemeral message but possibly suggest to @seo again when posting links to before.bot
  • No thanks will dismiss the ephemeral message and won't prompt @seo to 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.

Complete the submission checklist

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.

Review the checklist now

Submitting your app for review

When you're done with the preparation of your app, and have gone through our guidelines, you're ready to send your app for review.

  1. Go to your app's settings dashboard.
  2. Click into the Review and Submit page in the Submit to App Directory section.
  3. Review the resources on the How to prepare and submit your app page.
  4. Go through the submission flow and click the Submit App for Review button.
  5. In the Preview Your App Submission modal, verify everything is correct, and click the Submit App button.

Once you’ve submitted, we’ll start the review process which is split into two parts:

The preliminary review
This makes sure that the listing information and associated pages meet our guidelines, and that we have everything we need to install and test the app. Feedback from this part of the review generally takes up to 1 week and you'll need to make all of the changes outlined before the submission can be moved to the next part of the review. If these changes aren't made or there is missing information, this step is repeated until the requirements are met. Your place in the queue is reset each time you resubmit and restarts the timeline for the next part of the review.

The functional review
Once you've satisfied the requirements for the preliminary review, the submission will be moved to the functional part of the review. At this point, the submission is assigned to a reviewer who will install and test the app to assess the user experience. Feedback from this part of the review generally takes up to 8 weeks and once your submission has been assigned to a reviewer and you receive your first set of feedback, your place in the queue is not reset when you resubmit with changes.

After you address our feedback and everything is passed, we’ll approve your app and you can make it live in the App Directory straight away 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.

Maintaining your published app

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.

Expectations for published apps

  1. 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.

  2. Your app's functionality and customer experience matches or exceeds the quality of experience at submission, and you maintain your app’s performance.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. You must resubmit your app for review when you make substantial changes or updates to the features, purpose or functionality of your app.

  8. 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.

Possible enforcement actions

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;
  • the support page or privacy policy page links for the app are broken.

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.

Testing and developing updates to a published app

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 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

Updating your published 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:

  1. Open your app's settings dashboard
  2. Click Submit changes for review.
  3. Complete the submission checklist.
  4. 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.
  5. Click the Preview Submission button.
  6. On the Review Your App Submission modal, verify everything is correct, and click the Submit button.

Resubmitting your app with granular permissions

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 granular permissions. Read on for a walkthrough on how to migrate your published App Directory app.

Note: Upgrading to 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.

Upgrading scopes

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.

Communicating with customers

While updating your app to use 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.

Making app settings changes

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.

Removing your app from the App Directory

You can remove your published app from the App Directory in the Published app settings section of your app's settings dashboard.

Discontinuing your published app

If your app is no longer being actively maintained or developed, you should ensure you adequately sunset your app by:

  • removing it from the App Directory;
  • contacting the App Directory team at feedback@slack.com;
  • contacting your customers where appropriate;
  • deleting and revoking any tokens your app generated.