|Read this if:||You're still experimenting, prototyping, and exploring.|
|Read next:||Messaging for Slack apps||Incoming Webhooks||Slash Commands|
Customize functionality for your own workspace or build a beautiful bot to share with the world. Provide your ingenious integrations with a suitably configurable container. Build a Slack app.
What your apps do is up to you — maybe it performs one distinct task incredibly well or perhaps it orchestrates a technological concert between individual Slack features and your internal accounting service.
First-timer or seasoned veteran? Often it's best to just get started and learn along the way.
Your app can do these things and more.
A journey of a thousand miles begins with a single step.
Your app can do a little. Your app can do a lot. It can be a simple tool, it can even be a bot.
Start by creating a Slack app for your workspace. Slack apps begin life locked down just for your workspace.
If you don't have a Slack workspace or just want your own personal sandbox to develop in, create a new workspace and return when ready. Just be sure to carefully decide where your Slack app will live. The app record cannot be moved to another workspace later.
Whether a Slack app first-time integrator or a seasoned veteran, it's often best to just get started and learn what's what along the way.
Here's what's in store for you on this heroic first step:
That's it. Once created, you have a Slack app to manage.
Learn more about developing great Slack apps with these best practices.
Before you start turning all the knobs and flipping all the switches, we wanted to let you know about a concept called internal integrations.
While all newly created Slack apps start their life installable only by your workspace, we recognize that the ultimate destiny of many, if not most, apps is to be used by your workspace exclusively.
Perhaps your app integrates with your hand-rolled bug tracker or that funky old database running on a 286 under the boss' desk. Perhaps it just integrates with your company culture but not necessarily with some other internal or external service. Maybe you're part of an Enterprise Grid organization and your app is useful for the team in the warehouse but not the team in the board room.
Whatever it is that these apps do is your business. We call this flavor of Slack app an internal integration.
Name, configure, twist, shape, and install your Slack apps by first logging in to api.slack.com and navigating to the My Apps section at api.slack.com/apps. There you'll find a list of the applications you own or collaborate with and their current stage of the app development lifecycle.
Just click on the name of an application to configure settings for that app.
Can't find the app you're looking for? Make sure you're signed in to the right workspace and reload as necessary. You can sign in to multiple workspaces at once on api.slack.com.
The chart below describes the states that a Slack app can be and how they flow to one another.
Slack apps begin their life void of features, uninstalled. Waiting for you to fill them with potential and functionality. We hope you move your app through the first two stages. Unless you're developing for other workspaces, stages three and four are optional. We're happy you're developing on Slack at all stages.
Just after you create your Slack app, it's not really capable of much. You probably haven't begun coding. You haven't declared the platform features you plan to use in the app, like incoming webhooks or a bot user.
It's an empty vessel somehow full with limitless potential. After you add features to your app, you'll make it installable.
By default, newly created Slack apps will begin in this state. This might be the end of the lifecycle for your app. If you only ever need your own workspace to install your app, progress no further. This stage can be your lifelong home.
Your app can either use the button-based installation available in your application management console or you can use OAuth 2.0. Rest assured, your app can only be installed on your workspace either way.
When you add or remove new Slack app features, you'll need to install your app again.
This step is completely optional. It's entirely possible you'll never want another workspace to ever install your app.
By setting your app to this state, other workspaces will be able to use OAuth 2.0 to install or sign in to your app -- all they'll need is your client ID and for you to have done all the work to support OAuth.
For historical reasons, apps created before February 28th, 2017 will already be in this state. Feel free to lock your app down to just your workspace, returning to the comforts of stage 2. See your old apps for more information.
Slack apps open to installation by other workspaces have additional security requirements: your OAuth redirect URIs, interactive message action URLs, slash command invocation URLs, and Events API delivery locations must all support SSL.
This step is also completely optional. Becoming part of the directory is a very deliberate undertaking.
Once your app is submitted or part of the directory, you are granted a "development" version of your Slack app with its own dedicated Client ID and secret and installations. You'll need to re-submit your app for approval again whenever you change app-related items like the name, icon, authorization settings, or Slack app features.
We have a detailed tutorial all about the App Directory submission process.
If you created your app before this most recent update to Slack apps on February 28th, 2017 then:
incoming-webhookif your app makes use of those features
After you create your app you will start out on the Basic Information page. Here you can see the features available for you to configure, see information about installing or distributing your app, configure your application's identity and delete your app.
There are a few options for configuring your app's identity. You can add an icon used to represent your app, change the name of your app, and add a short description for your app.
Note that there will be quite a bit more information to fill out here if you submit your app to the App Directory.
On the OAuth and Permissions panel you can add OAuth redirect URLs, choose some permission scopes, or revoke tokens from your app. For more information about OAuth and how it's used for Slack Apps see: OAuth, Add to Slack, Sign in with Slack, and Scopes.
You can also set a whitelist of IP addresses instructing Slack to accept connections from when using the Web API.
For some features, you will need to use a Signing Secret, which is provided on the Basic Information page. Verify any requests sent to your servers by Slack using your app's signing secret and our request signature verification pattern.
Every request Slack sends to your server contains a signature based on this secret. By validating the signature, you validate that the request originated from Slack.
We provide a wide range of granular scopes that allow you to request the exact permissions that your app needs. For example, if you only need to post updates to a channel once an hour, you should only request the
incoming-webhook scope. The full inventory of scopes list the API methods that each scope corresponds to. Here are some examples:
emoji:readscopes, your app can use related API methods to build a leaderboard of workspace members' reactions.
incoming-webhookscope, users can grant your app access to post messages to a Slack channel of their choice, just like a custom incoming webhook integration.
commandsscope, authenticated users will have access to any commands that you have configured in your app.
botscope, you will receive a bot user token upon completion of an OAuth flow. You can use this bot user token to connect to the Real Time Messaging API.
files:write, you will be able to call their corresponding Web API methods.
See Slack app scopes for more information on
There are many features to choose from when building a Slack app that each have a corresponding page for enabling them and setting them up. You can learn more about each by following the links below:
Once you've told us what platform features your app will use, it's time to install it.
By default, newly built Slack apps can only be installed on the workspace they belong to. Installing your app on other workspaces means learning the sad songs and waltzes of OAuth 2.0.
We've made it triumphantly easy to install apps on your own workspace without needing to learn OAuth. To distribute your app for other workspaces to install, implement our OAuth 2.0 authentication flow and submit it to our App Directory. Our team will review your submission and work with you to get it listed.
Slack apps are carefully scoped to use only the permissions & capabilities needed to fitfully function.
When installing your app, users can review its capabilities and configure settings right within our OAuth-based authentication flow. For teams needing even more control, Slack apps can be carefully managed and approved by team administrators.
Installing your app to your workspace is easy! Once you've setup your features, click on the Install App to Team button found on the Install App page. If you add new permission scopes or Slack app features after an app has been installed, you must reinstall the app to your workspace for changes to take effect.
If you do not have admin access to your workspace, you will need to request approval to install the app before you will be able to finish. If you just want to get started without worrying about that, we recommend creating your own workspace as a scratch space for development.
App collaborators can install apps this way too. If you wish to distribute it to other members of your workspace, you will need to set up an OAuth redirect URL and have them install it with OAuth and/or Add to Slack button or sharable URL.
In the past, Slack automatically uninstalled apps when the user who installed them departed a workspace or became a guest.
No more: as long as the app acts like its own bot entity, the app is safe from the app-vanishing act that accompanies a user departure. Bots that use only the
identify scopes are safe.
One caveat: this exception doesn't apply to the folks who created an app or were added as an App Collaborator. When they leave, the app is still uninstalled. Same goes for when an app uses additional scopes beyond the ones listed above, taking on the behavior of a user.
After all, your app is monumental in its own way. It deserves a chance of lasting as long as the pyramids—or at least until someone chooses to uninstall it purposefully.
Typically, Slack apps must present users with a web page containing a link to Slack's OAuth 2.0 installation flow. As users browse apps in the directory or native client and encounter an app they want to install, they first must visit this page to initiate installation.
Save users a step by providing Slack with a Direct Install URL, a location on your site that simply redirects the current user to Slack's OAuth authorize step directly.
If your app is both approved and listed in the app directory, you can utilize this Direct Install flow.
By configuring this link on your app management's basic information screen (look for Installing Your App) and enabling "Install from App Directory", users will be swiftly spirited away to the authorization flow.
When you save your Direct Install URL, Slack will attempt to send a simple HTTP GET request to your declared URL. If it doesn't detect a HTTP 302 redirect pointing back to a fully qualified
slack.com/oauth/authorize URL (see below), you'll receive an error letting you know.
All your server needs to do is build the same URL to
slack.com/oauth/authorize you would build for your on-site "Add to Slack" URL and instead of presenting it in a button, send a HTTP 302 redirect to it instead.
For example, if your app had a client ID of
12345.67890 and requested the
users:read scopes, you might build a redirect sequence reminiscent of this:
First Slack sends the user to your Direct Install URL:
GET /slack/direct_install HTTP/1.1 Host: example.com
Then your server kindly redirects back to Slack's OAuth 2.0 authorization page:
HTTP/1.1 302 Found Location: https://slack.com/oauth/authorize?client_id=12345.67890&scope=channels%3Ahistory%20users%3Aread&state=abcdefg
Resulting in the user jumping right into authorization. One point of friction removed.
You may continue to generate your own time or context sensitive
state parameters and specific, pre-registered
redirect_uri values as needed.
If you ever need to drop back to installation via your landing page, just configure your app again to use your landing page instead of your Direct Install URL.
In order to distribute your app to other workspaces you may need to make a few configuration adjustments. You will need to add an OAuth redirect URL, make sure that features have been added, and remove any hardcoded information (like tokens etc.). While SSL is not required for Slash Commands, Event Subscriptions, or Interactive Messages when you are installing only on your workspace, for security purposes it is necessary when distributing to other workspaces. Then you can pass around the sharable URL or have people click on your embedded Add to Slack button.
Consider subscribing to app events to monitor your application's lifecycle around token revocations and uninstallations.
Some workspaces restrict application installation to administrators only, or to only apps officially listed in the Slack app directory. Teams can also use admin approval features where users can't directly install apps but can solicit for installation through a guided interface. Team administrators may then screen these requests and selectively approve for installation.
There are many ways your app may present itself and be discovered by users. Typically, Slack apps deal in the art of messaging.
/in their chat box.
Want to distribute your Slack app so other workspaces can discover and install it? Once you're ready, submit it for review and consideration in our directory.
Apps submitted to the directory should be easy for workspaces to install and use. Our application review team will install and use your application and follow up with you for additional detail. As we receive many submissions, there may be a short delay before your application will be reviewed or approved.
Our Slack App Directory Checklist outlines the entire review and submission process.
When you're ready to submit:
After distribution has been activated you have the option of deactivating by clicking on the Deactivate Public Distribution button. This will remove the app from any workspaces that have installed it aside from the original one you chose.
Note that this can not be done after your app is published in the app directory.
Slackbot can suggest your directory-listed Slack app to new users. Find out all about app suggestions.
Not only can your Slack app do all those things but because it's yours, you and a chosen team of collaborators:
If you're reading this, then you, yourself, are likely an app creator and/or collaborator.
Collaborators like you may do such things as:
The Collaborators tab allows App Collaborators to manage which members of the team are allowed to configure a Slack app.
The team member that created the application (maybe that's you?) is also automatically made an App Collaborator. After another Collaborator is assigned, the application creator may "leave" or be removed from the app's list of collaborators.
Use the Add a team member control to add additional App Collaborators from the containing workspace. App Collaborators will have access to your app's credentials, so be sure and only add team members you trust with your Slack app's livelihood.
You may also assign your workspace's single or multi-channel guests as App Collaborators. These guests cannot delete a Slack app, nor modify your carefully pruned roster of co-conspirators.
Hovering over a Collaborator under Team members who can edit this app reveals buttons allowing app Collaborators to remove their fellow collaborators from the app, or for the currently signed in Collaborator to Leave the esteemed list of fellow App Collaborators.
Your team's friendly Slackbot will dispatch messages to fellow team Collaborators as changes to the roster are made — or in the unlikely event that a Slack app is deleted.
Slack apps can do a little. Slack apps can do a lot. What it does is up to you and we hope you'll give it some thought.