Guidelines for App Directory listings
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 email@example.com.
- User experience
- Your App Directory listing
- Links associated with your app
When developing your app for Slack, the most important thing 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),
As part of your submission, you’ll need to provide explanations for the use of each scope your app requests. Before submitting, please ensure your explanations are clear, thorough, and explain how each scope contributes directly to your app’s functionality. Doing so will help reduce the time needed to review your app.
Please note, as of February 21st 2020, we will no longer accept new submissions to the App Directory of apps that include the legacy
bot scope. By the end of 2020, we will no longer accept resubmissions of approved apps with this scope. Now is the time to get acquainted with the new granular permissions mode
In the App Directory, our focus is to highlight 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. Apps that use coarse language, facilitate financial transactions in Slack, or require more data access than necessary, for example, may not qualify to be listed.
Before submitting your app for review, make sure you’ve tested every element, including installation, onboarding, and all other features to ensure they work and match your documentation. The best way to do this is to install the app from scratch on a completely new Slack workspace, and to run through each piece of functionality. You should also test reinstalling your app on a workspace where it has been uninstalled to prevent any issues around reauthorizing the app.
The onboarding experience is important for all users, not just for the person who installs the app. Your app should provide customers with a high quality onboarding experience as part of their first interaction with the app that clearly guides users through its use. Whether that user is the installing user, or someone who came across your app on their Slack workspace, this is key to helping them get up to speed.
If your app doesn’t have any interactive elements, consider adding an App Home to your app and disabling the Messages tab so that customers can learn more about the app and how to use it.
Another part of building a great user experience is supporting your customers as they get to know your app. If your app includes a bot with messaging capabilities, we expect that it will return usage and support information if a user sends it a message asking for help. If your app is using a slash command, it should also return support and usage information if a user includes a “help” parameter after the command.
If you don’t have interactive elements, your App Home should provide guidance to customers about how to use your app and point them to your website or support page if they need help.
App messages should be formatted in a clear and consistent manner and should be presented to users in a way that’s easy to scan and digest. Block Kit will help with this, and you can even try out different message formats and text styling options using the Block Kit Builder/tools/block-kit-builder).
Your app’s messages should also not distract users unnecessarily, or post messages to channels a user hasn’t given it permission to. Posting to a workspace’s #general channel by default is a bad idea, as well as using @channel or @here notifications for anything that isn’t critical.
Additionally, your app should avoid posting to a user’s Slackbot channel as it’s not an expected place for apps to turn up and makes finding messages difficult. Make use of your app’s bot user to surface messages within a dedicated space. This means you can also help customers find more information about your app by creating an app home.
Also make sure that you’ve reviewed all copy for spelling and grammatical mistakes. This includes everything from your app’s App Directory long description, screenshots, and website, to any copy present in the app itself.
If your app makes use of email addresses obtained from a Slack workspace 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.
If your app is no longer being maintained and will be shut down, you should communicate that to users in advance. When the time comes for deprecating your app, you must revoke all of the app’s tokens and delete the app. The App Directory team also appreciates some notice in these cases, so please send a note to firstname.lastname@example.org.
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”).
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.
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.
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.
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.
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.
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!
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.
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.
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.
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.
It's important that your app respects Slack's privacy model and access controls. In short, a user shouldn't be able to view any workspace data through your app that isn't already available to them in Slack.
Your app shouldn't allow anyone to impersonate or take action as another Slack user. As part of this, we ask that you securely bind third-party accounts to make sure they’re connected to the right individual. Slack users may have different roles —owner, administrator, member, or guest — your app should recognize these roles and comply with their related permissions.
You will also need to be mindful when working with external customers in shared channels. There are special considerations for apps in shared channels that you should read up on.
Even with the best security practices in place, your app should never collect sensitive information, like passwords and credit card numbers, nor share it in Slack.
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.
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.
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.
Distributed apps can add security and compliance information on their App Directory listing page. This can make it simpler for workspace administrators to determine whether your app meets their organization's internal security requirements. These details should stay accurate and up-to-date.
If you have any reason to believe that your app security has been compromised, contact our team at email@example.com as soon as possible.
Submitting your app for review is part of your app’s ongoing lifecycle and we want your app to be successful!
Once your app is live in the App Directory, please remember that any changes to your app’s configuration must be resubmitted for review before you publish them to your live app. If you’re making substantial changes to your app’s functionality or purpose, reach out to let us know.
If you have any questions about the review process, or about anything related to your app, get in touch with us at firstname.lastname@example.org.
When your app is listed in the App Directory, you’ll need to keep it up to date and maintained. If at any point your app breaks these guidelines or requirements, we may reach out to you to fix any issues. Depending on the severity of the issue and the remediation plan, we may need to delist your app.
We regularly feature apps in the App Directory that we believe will meet customer needs. As part of our review process, we look for high quality apps, taking into account the way an app uses Slack API features, the value the app provides customers during their workday, and the overall quality of experience.
Do you think your app would be a great fit for us to feature? We'd love to hear from you! Send us an email at email@example.com and tell us more about the value your app is providing, any recent updates or improvements you've made, or feedback you're hearing from customers. Feel free to include links to blog posts or any marketing you're using to share your app with customers.