Beginner

Guidelines and requirements for App Directory Apps

Whether you’ve just started building an app, or are ready to submit one to the App Directory, this guide will help you prepare your app for the App Directory review.

During the review, we’ll check that your app follows the guidelines below, which you’ll see summarized when you submit your app. Remember that your customers use Slack to communicate, collaborate and streamline processes while they’re at work. Consider how your app’s design and experience will help them do just that, and build a high-quality experience with that in mind.

This guide is subject to change and will reflect updates we make to the review process as we release new features and experiences in Slack. If you have any questions or feedback about this process or guide, we’d love to hear from you. Send an email to feedback@slack.com.

But first….Apps unsuitable for App Directory

In the App Directory, our focus is to showcase apps that help our customers get work done more easily. For that reason, not every app may be the right fit for the App Directory. The list below is not exhaustive - the App Directory team may use their judgment to deny any app from being listed. Here are some apps that are unsuitable for the Directory.

  • export or backup message data;
  • are built for the sole purpose of searching Slack messages outside Slack;
  • use legacy/restricted scopes or methods (e.g. client, read, post, identity.*, search:read)
  • 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;
  • does not provide any functionality we deem to be valuable in Slack.
  • enable remote execution on a server via a downloadable third party script e.g terminal commands from Slack
  • facilitate the sharing of third party service accounts between multiple users

Read our terms and policies

In addition to the above list of unsuitable use cases, you should also review 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.

Phew - if you've read through the above and still think your app is suitable for the App Directory, keep reading to find out more about what we look for.

Your App Directory listing

If your app/service is a house, then your App Directory listing is the front door. People visiting your listing should be able to easily understand the problems your app solves, how it integrates with your service, and what the next steps are for getting started.

Name

A great name can help people understand what your app is all about. Choose a name that's unique, easy to remember, read, search for, and spell.

If your Slack app integrates with another service, include the name of that service in your app name. If you do not own the service, make sure to not infringe on any trademarks or copyright (e.g., “Task notifications for Slack” rather than “Slack task notifications”).

Short description

The short description should be used to sum up your app’s value. An app's short description is visible in App Directory search results and on app profile cards in Slack. This description should concisely state the value of your app and be attention-grabbing. Make sure to keep it short and sweet at 10 words (or fewer) so that it doesn’t get cut off anywhere. Please note: short descriptions do not support Slack message formatting.

Example of how a short description appears in search results

Long description

In a long description, you can go into more detail about what your app can do. Your long description will help customers browsing the App Directory better understand the value of your app. While there is some flexibility in how you choose to describe your app, below are some points you should cover:

  • If your app integrates with another service, include a brief overview of that service for those who may not be familiar.
  • Clearly state the problem your app solves. Framing your app in this way helps people understand how they could use it.
  • Provide a clear indication of how your app works in Slack. This helps people to understand what they can expect in Slack after installing your app.
  • Use Slack message formatting to make the long description easier to read.
  • Emoji can be added to your long description using the :emoji-code: notation and will render in your App Directory listing, however be sure only to use standard emoji codes as custom emojis will not work.
  • Please don’t try to boost searchability by filling your long description with keywords that aren’t directly relevant to your app.

Example of how a long description appears in App Directory

Icon

Your app icon should catch people's eye when they're scrolling through the App Directory. Make it unique, distinctive, and simple enough to pass the squint test. It should also be of high quality and resolution so that it doesn’t result in a blurry image in the App Directory.

A icon we like. An icon we think is bad. Don't try this at home.

Images and screenshots

Your App Directory listing allows you to upload app images and screenshots. This is a great way to highlight key app features and give customers a clear idea of how your app works in Slack. Here are some things to keep in mind:

  • Use high quality images.
  • Use a 1600px by 1000px size (8:5 ratio).
  • Show your app in the context of Slack, not other tools.
  • Use a .jpg, .jpeg, or .png file format, and make sure the size is under 21mb.

When showing an image of your app in Slack, adding text can help provide context. This is a good way to show your customer at a glance how your app will help them get their work done more seamlessly.

Helpdesk example screenshot

Video

A high-quality video is an efficient way to show people what your app can do and help your potential customers get excited about how it might help them with their work. We strongly recommend you consider adding a video and offer these suggestions:

  • Keep your video length between 30-90 seconds.
  • Make sure your video is publicly-accessible YouTube link, not a link to a channel or playlist.
  • Turn on closed captioning and turn off ads in YouTube's settings before submitting your link.
  • Make sure your video shows how your app works in Slack.
  • For screencasts, use a real-life Slack environment (e.g., realistic member names, profile pictures, and channel names). Make sure to show your production app in action, not the app you use to test during development.

Pricing

Slack allows you to charge users for your app. If you do so, you should handle payments securely and provide transparent information on your billing policy. You can select one of the following pricing models to be displayed on your app's listing page.

  • Paid: users pay to use your app.

  • Paid with free trial: users pay to use your app, but there's a free trial available.

  • Free and paid plans available: users don't need to pay to use your app, but there are paid features available.

  • Free: your app is free!

  • Included with service subscription: the app is free so long as users have a paid plan with your service.

Language Support

Supporting multiple languages with your Slack app is great. Before adding this information to your app settings, it’s important to understand what it means to fully support a language:

  • People can select to use your Slack app and any related service in this language entirely.
  • All messages and interactive components sent by your app in Slack, as well as any other interfaces related to your service, are available in this language.

As this relates to the language used in your App Directory listing, this is entirely up to you! The only thing we ask is that the experience is consistent i.e. the language used for your descriptions, images, videos, and pages associated with your listing is consistent.

Direct Install

Enabling direct install can be a great way to shorten the distance between discovering your app and installing it. With this enabled, instead of people having to visit your landing page to install your app:

Direct install screenshot

They can install your app directly from your App Directory listing:

Direct install screenshot

To configure this link on your app's settings dashboard:

  1. Open the Basic Information page
  2. Scroll down to Installing Your App
  3. Select and enable Install from App Directory

Things to note when enabling direct install:

  • The URL you provide must HTTP 302 redirect to a fully qualified slack.com/oauth/v2/authorize URL, as per the first step of the OAuth flow.
  • As installation of your Slack app will be accessible to anyone with a Slack workspace who views your App Directory listing, your onboarding flow needs to account for this. For instance, in the case of a Slack app that requires an account with a third party service to function, it is possible that people will install your Slack app without first having an account. Your Slack app’s onboarding flow should account for this and guide people to either create a new account or connect an existing account.

Pages associated with your app

Your landing page

Your landing page is the place for you to provide your potential customers with all the information they need to get started with your Slack app. There are some things that you should make sure to include:

  • A clear overview of your Slack app, any associated services, and the problem your app solves.
  • A detailed explanation of how your app works in Slack. Screenshots and GIFs are a good way to show people what they can expect in Slack after installing your app.
  • A clear path to installing your Slack app, whether that is an Add to Slack button on your landing page or instructions for accessing your Add to Slack button.
  • A clear path to using your app. Once people install your app to their workspace, they should be redirected to a page that confirms the installation was successful and provides clear next steps for getting started with your app.
  • In addition your landing page needs to be publicly accessible i.e. not behind a login.
  • Your landing page is, well, a landing page crafted by you, specifically for your Slack app - not a link to a PDF, document or code repository.

Google calendar landing page

Your support page

We expect all App Directory developers to provide accessible and responsive support for their apps. You know your app best, which means you’re the expert when it comes to providing customers with a great support experience when they have questions or encounter issues. Please make sure your support follows these guidelines:

  • How to get support is obvious. There is a clear way to get in touch with you if someone needs help, such as an email address or contact form.
  • Getting support doesn’t require signing up for any additional accounts. While using Github issues or Twitter as support channels is completely reasonable, you must also provide support that does not require an additional account.
  • Your support experience is responsive. We expect support requests to receive a response within 2 business days.
  • Your support page needs to be publicly accessible i.e. not behind a login.

Your privacy policy page

All App Directory apps must include a clear privacy policy that details how third-party data is handled and this page should be accessible on your app’s landing page. At a minimum it should include:

  • What data is collected.
  • How the data that is collected is used.
  • How long data is kept.
  • How an individual can request to access, transfer, or delete their data
    • For deletion, we require a generalized (i.e not specific to GDPR/CCPA) statement regarding how someone can request deletion of their data,
  • Information on how to contact the service for making a request related to their data.
    • At a minimum should be an email address or a webform.
    • A physical address alone is not sufficient.

It’s important to think about how third-party data passes through your app. While your app may not make use of data as a feature of your product, it is possible that data is received by your service when your app is used (e.g., IDs from slash command payloads, data from system logging, etc.). If your app receives data but never uses it, this must be stated in your privacy policy.

User experience

It goes without saying (but we’ll say it anyway): people should have a good experience using your Slack app! This encompasses everything from making sure an app meets basic utility requirements, all the way to the finer details of how your app interacts with people in Slack. As part of reviewing your submission to the App Directory we will install and test your Slack app to assess the user experience; below are some of the things we will be looking for.

UI/UX Fundamentals

The Slack platform provides an extensive array of options for developers to choose from when building an app. However, the same general considerations someone makes when designing a website/desktop app/mobile app/any-kind-of-software-with-an-interface still apply. You should always look to create interfaces and experiences in your app that adhere to common best practices i.e what people expect from modern software. Some things to think about:

  • DO provide clear visual feedback when a user takes an action e.g buttons appear ‘clicked’, information submitted is confirmed as submitted, loading gifs etc
  • DO provide explicit user guidance where needed e.g input hints
  • DO provide meaningful & actionable error messages e.g “You need to invite our app to the channel before you can use this command. Type /invite @bestapp and try again” rather than “Oops! something went wrong!”.
  • DO actively onboard first time users - help them get started!
  • DO make help and support easily accessible as part of using the app e.g include support information in your app “Home” tab by default
  • DO make it clear what the output will be for any given input e.g no “I didn’t realize it would post that in channel!” moments for users
  • DO clearly attribute app actions to a user where there could be confusion e.g no “who let this app post in this channel!?” moments for users
  • 🚫 DON’T lead users through one-way doors e.g users should always have an easy way to go back when completing an action with an app
  • 🚫 DON’T lead users to dead ends e.g no “well what do I do now?” moments for users

The above list is by no means exhaustive but you get the picture: give the folks using your app everything they need to make the most of it.

Org wide deployment

Enabling org wide deployment for your app allows people to deploy your app across multiple workspaces within an Enterprise Grid organization. Since this is a powerful feature, it requires some thoughtful planning. In particular your app needs to be prepared to function in Slack Connect channels where Slack users from another workspace in the org will be able to interact with your app. Having a clear understanding how your app’s features work in this environment is a requirement for any app in the App Directory with org wide deployment enabled. To find out more about preparing your app head here.

Onboarding

Good onboarding is transparent, directed, and designed to welcome a new customer to a product by setting them up for success! Onboarding is a broad topic and there are as many ways to do it as there are ways to build a Slack app, however here are some common things we think underpin a good experience (and a few that don’t):

  • DO be transparent about where a user is within the onboarding flow e.g provides goals and clear progress markers
  • DO provide clear next steps
  • DO close the gap between installation and usage - get to the value! e.g. have people try out app features as part of onboarding
  • DO request explicit consent to send emails (if you intend to send messages to emails collected via the Slack API)
  • DO clearly surface ways to get support throughout the process
  • DO remember to think about onboarding in terms of both the installing user and first time users - both need to be guided!
  • DO provide a clear and easy way for users to connect their Slack account with your service’s account if required e.g a ‘connect account’ step that asks people to authorize the app.
  • 🚫 DON’T ask people to manually map external service accounts to Slack accounts (invites potential for human error/impersonation).
  • 🚫 DON’T leave users stranded e.g no “Hello? What do I do now?” moments for users
  • 🚫 DON’T make people think!

The above list is not exhaustive but should provide a fair idea of what we will be looking for when reviewing your app.

Notifications and sending messages

For many apps, notifications are the core of their service, and for many customers, notifications are what they think of when they think of Slack apps. A well timed, actionable notification has the potential to genuinely make someone’s working life simpler, more pleasant, and more productive. But with great power comes great responsibility! Poorly timed, persistent, uninformative notifications have the potential to ruin someone’s experience of using Slack. Here are some of the things we hope (and don’t hope) for from App Directory apps:

  • DO provide a way for customers to configure notification type and frequency
  • DO make notifications relevant and actionable e.g message buttons!
  • DO try to batch-send high volume notifications or create digests
  • DO attribute notifications in shared spaces to the person who configured them e.g if notifications have been configured for a public channel, send an intro message into the channel to inform channel members of this fact and who configured them
  • DO double (triple) check notification copy for spelling and grammar
  • DO use Block Kit to create beautifully formatted, easily parsable notifications that deliver their message clearly and succinctly
  • 🚫 DON’T send notifications to people who would not expect to receive them
  • 🚫 DON’T spam people with high volume notifications
  • 🚫 DON’T impersonate a user on a workspace when sending messages
  • 🚫 DON’T send notifications to a user’s Slackbot channel. Use the app home Messages tab instead.
  • 🚫 DON’T use @channel, @everyone unless there is a supremely relevant and unavoidable reason (nearly never)
  • 🚫 DON’T post to a workspace’s #general channel by default.

Home Tab

The “Home” tab is one of the most powerful tools in your toolbox when it comes to building a robust user experience right in the heart of Slack. The highly customizable layout will allow you to provide an experience closer to using full-fledged standalone software. Here are some of our top tips on how to maximize the space:

  • DO load relevant and useful content for any user on a workspace who views the tab regardless of whether they have authorized your app or not
  • DO adhere to standard UI best practices e.g. pagination for long lists, auto update view when changes are made by user etc
  • DO make support information clearly visible and surface any pricing plan information (if applicable)
  • DO use it as a place to surface app settings
  • DO allow people to customize how things are organized/presented (more relevant to apps who make heavy use of the “Home” tab)
  • DO understand who is viewing the tab and only show information they should have access to
  • DO think about the hierarchy of information and functionality being displayed e.g customers shouldn’t have to think too hard to do common tasks or find information
  • 🚫 DON’T enable the tab if the app does not use it. This doesn’t only include cases where it doesn’t load content, but also cases where the content is detracting from the experience of the app e.g a tab displaying only “[APP NAME] is installed on your workspace”.

Messages Tab

The "Messages" tab is part of the App Home and is the equivalent of a direct message conversation between a user and your app. It is a great place for notifications along with more complex, conversation-like interactions.

  • DO send a welcome message the first time any user opens the “Messages” tab*
  • DO respond to users’ direct messages if the message input is enabled
  • 🚫 DON’T have this tab enabled if your app is not actively using it

*If the “Home” tab has been enabled for your app and is sufficiently ‘welcoming’ then we are happy to relax this requirement.

Shortcuts

Shortcuts come in two flavors:

Global shortcuts: a great way to provide people with access to your app’s functionality anywhere in Slack via the quick switcher or by clicking on the plus icon to the left of the message field in Slack.

Message shortcuts: perfect for in-context use of your app and turning messages into action! Accessible via the ‘More actions’ menu on selected messages.

When working with shortcuts the following guidelines apply:

  • DO start your shortcut name with a verb
  • DO acknowledge the request with a 200 OK response in 3000ms to avoid a timeout error
  • DO open a modal when the shortcut is used, send appropriate confirmation and error messages
  • DO understand that your shortcut is accessible to anyone on a workspace where your app is installed, so you should handle unrecognized users with grace and clarity.
  • 🚫 DON’T expose private channel metadata (e.g channel name, members) if sharing a message from a private channel using a message shortcut

Slash Commands

Slash commands are a long lived stalwart of the Slack platform (and messaging software generally). Used by entering a forward slash and the given command in the message field or by clicking on the plus icon to the left of the message field in Slack. When working with slash commands:

  • DO try to use a unique name for your slash commands in order to maximize discoverability and minimize the potential for name collisions e.g instead of /help use /[your_app_name]-help
  • DO respond with usage instructions when someone adds “help” or unknown input after the slash command
  • DO respond with a helpful and appropriate error message if something goes wrong
  • DO consider whether to respond with an ephemeral or in-channel message — it’s usually always best to use an ephemeral response to minimize disruption for others and allow your slash command to be used anywhere.
  • DO understand that your slash command is accessible to anyone on a workspace where your app is installed, so you should handle unrecognized users with grace and clarity.
  • DO use the response_url included in the slash command payload to respond to users
  • DO include a clear and useful hint and short description text for your slash command.
  • 🚫 DON’T overload a slash command with too many arguments. Whittle things down to key workflows and explore things like message buttons as ways for people to navigate your slash command functionality

Scope & Data access

When developing your app for Slack, one of the most important things to bear in mind is the level of access it needs to work: the less access your app requests, the more comfortable users will feel about installing your app. From the customers’ perspective, they must give your app access for it to function and they may be reluctant to install apps that request a lot of access to their Slack data (particularly sensitive data like their message history).

  • DO adhere to the ‘principle of least privilege’ when thinking about the scopes your app will use
  • DO provide clear reasons for each of the scopes you include in your submitted app. Don’t just tell us what the scope does (we know that already) but rather tell us how your app uses it
  • 🚫 DON’T include scopes in your submitted app intended for future functionality. We will only approve scopes related to functionality we can test
  • 🚫 DON’T request legacy/restricted scopes. See here for more details

In addition to the above guidance there are some additional caveats worth thinking about before submitting:

  • We are unlikely to approve broad access to workspace message/file data (e.g user token *:history scopes) outside of strong security & compliance use cases.
  • We are unlikely to approve use of admin* scopes by apps submitting to the App Directory who are not part of our partner program
  • Use of user token scopes should be restricted or avoided if possible. Only request a scope for acting as your authenticating user if the action needs to be performed from the user's perspective: for example, reading or starting group DMs for a specific user. We will return submissions where user token scopes are being used unnecessarily. To find out more about access tokens and how they work check out this doc.

If you have questions about the above or are unsure as to whether your app would be impacted please drop us a line at feedback@slack.com before submitting and we can chat it through.

The privacy model

It is very important to understand Slack’s privacy model to ensure that your app doesn’t unintentionally circumvent or undermine how data is managed in Slack. In short: an app should not give people access to information/abilities that they would not otherwise have access to in Slack. Some examples:

  • An app should not expose private channel information (e.g channel name) to anyone who is not a member of the channel in Slack
  • An app should not expose messages/files to anyone who would not have access to them in Slack
  • An app should not allow people to exercise restricted actions they would not normally have access to e.g create channels in a workspace where channel creation has been restricted

It is also worth making sure you understand how to comply with the above in shared channels where you may be dealing with external companies. Check out this doc to find out more.

These sorts of things can be tricky and the above list of examples is not exhaustive, so if you have questions about the above or are unsure as to whether your app would be impacted please drop us a line at feedback@slack.com before submitting and we can chat it through.

User emails

If your app makes use of email addresses obtained via the Slack API for any reason, you must take special care. If you do need to contact users by email, make sure you get explicit consent from each customer to use any email addresses before contacting them. You can do this as part of the installation process (with an explicit opt-in option before installation), or as part of your app’s onboarding flow.

Security

When using Slack’s API, you should follow our best practices for security. In addition, we’ve detailed other security requirements for distribution in the App Directory below. Our team may also perform an advanced security review at any point after an app is submitted to the App Directory. Please note that your app may be blocked or removed from the App Directory if it doesn’t meet our security requirements.

OAuth and tokens

When building for the App Directory, you'll be working with credentials from Slack and API tokens granted through an OAuth flow. It’s important that you handle these with care.

Your app must store API tokens securely. They should never be logged, stored in client-side code and public repositories, or made accessible to end-users. When your app is no longer supported, these API tokens need to be invalidated by deleting your app from your app settings page.

To prevent forgery attacks, your app must use the state parameter when requesting access to customer data during the OAuth flow.

TLS

Your app needs Transport Layer Security (TLS) to encrypt all traffic between clients and servers. As of February 19, 2020, your app must use TLS version 1.2 or greater to continue using Slack endpoints.

Authenticating requests

Your app may have configured endpoints for certain interactions, including slash commands, actions, interactive messages, menus, and the Events API.

Before your server responds to a request, you must verify that any requests received at these endpoints are authentic by using signed secrets or mutual TLS. These methods should be used instead of verification tokens, an older form of request authentication which is now deprecated.

The signing secret should be protected like a password. If accidentally exposed, you can regenerate it from your app settings.

Security incidents

If you have any reason to believe that your app security has been compromised, contact our team at feedback@slack.com as soon as possible.


Post-approval requirements

Your app being approved is only the beginning! As a member of the App Directory there are certain ongoing requirements that you must meet to maintain a good experience for our shared customers.

Maintaining your published app

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.
  • 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, to resolve any issues, or in the case where your app is subject to security testing. 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.
  • Your app's functionality and customer experience matches or exceeds the quality of experience at submission, and you maintain your app’s performance.

Possible enforcement actions

In order to 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.

Discontinuing your published app

All good things come to an end. If your app is no longer being actively maintained or developed, you should ensure you adequately sunset your app. This means:

  • Removing it 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.
  • Contacting the App Directory team at feedback@slack.com
  • Contacting your customers where appropriate
  • Deleting and revoking any tokens your app generated

To find out more about the nuts and bolts of the App Directory submission and review process check out this guide.

To see a list of all the other things we look for when reviewing apps check out our submission checklist.

Was this page helpful?