Go to Slack

Managing Slack apps

The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read next:Messaging for Slack appsIncoming WebhooksSlash 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.

Building Slack apps

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.

Create a Slack app Manage your apps

App capabilities

Your app can do these things and more.

Send rich & timely notifications with incoming webhooks.

Empower users to invoke workflows at will using slash commands and message actions.

Keep things friendly and conversational with bot users.

Install internal integrations exclusively to your workspace. No OAuth required.

Make messages more actionable and interactive with message buttons.

Read and write data with the Web, RTM, and Events APIs.

Carefully select and limit your apps access to fine-grained permission scopes.

Let teams install & log in to your app using OAuth, Add to Slack, & Sign in with Slack.

Building for everyone? Distribute your Slack app in our App Directory.

A journey of a thousand miles begins with a single step.

Creating apps

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.

Create a Slack app

Here's what's in store for you on this heroic first step:

Creating an app dialog

That's it. Once created, you have a Slack app to manage.

Storyboard your app with these templates, including design elements for Sketch and a PDF.

A partial view of the design templates.

Learn more about developing great Slack apps with these best practices.

Internal integrations

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.

Managing Slack apps

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.

App Development Lifecycle

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.

1. Your app begins void of features, uninstalled

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.

2. Your app has features but can only be installed by your workspace

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.

3. Your app is open to installation by other workspaces

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.

4. Your app is submitted to and/or part of the Slack app directory

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.

Applications from antiquity

If you created your app before this most recent update to Slack apps on February 28th, 2017 then:

  • By default your app is not locked to the workspace it was created on.
    • to restrict other workspaces from installing your app, you'll want to mark it as "undistributed"
    • un-distributing your app will result in it being un-installed from any workspace other than the one that owns it. Of course, it might just be the only workspace that has installed it! You know best.
  • the OAuth scopes used by your application may not be yet part of your official application profile
    • you'll want to navigate to your app's OAuth & Permissions section add your scopes to the inventory -- including commands, bot, or incoming-webhook if your app makes use of those features
    • this is mainly to make re-installation easier when not using OAuth
  • Familiarize yourself with the new management UI. Yes, we've moved some of your cheese.

Slack app management tour

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.

Basic Information Page

Your application's identity

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.

Display Information

OAuth & permissions

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.

Permission Scopes Picker

Signing secrets

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.

Permission scopes

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:

  • With the reactions:read and emoji:read scopes, your app can use related API methods to build a leaderboard of workspace members' reactions.
  • By requesting the incoming-webhook scope, users can grant your app access to post messages to a Slack channel of their choice, just like a custom incoming webhook integration.
  • By requesting the commands scope, authenticated users will have access to any commands that you have configured in your app.
  • By requesting the bot scope, 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.
  • By requesting other granular object scopes, like channels:read or files:write, you will be able to call their corresponding Web API methods.

See Slack app scopes for more information on incoming-webhook, commands, and bot scopes.

Enable features & functionality

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:

  • Incoming webhooks are the simplest way to send messages into Slack. Often these are notifications of activity happening externally, but they are capable of many tricks, including...
  • Interactive messages allow your messages to evolve beyond the conversation with attached action buttons
  • Slash commands allow users to perform actions by typing commands into Slack at will. It's a kind of magic.
  • Event subscriptions deliver need to know information as it happens to your servers, so you can choose what to do next
  • Bot users are full of personality, allowing you to engage users conversationally

Of course, if you want to use the Web API or the RTM API you can do that with a Slack app too! The tokens yielded in the installation process are used to engage with both.

Once you've told us what platform features your app will use, it's time to install it.

Installing apps

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.

Installing your app to your workspace

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.

Install App Page

A pleasant vacation from unexpected uninstallation

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 bot, incoming-webhook, commands, and 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.

Make installation more direct

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.

Install from your landing page

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.

Install from App Directory

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.

Building a Direct Install URL redirector

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 channels:history and 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.

Distributing your app to other workspaces

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.

Before Distribution: Distribute Page Before Distribution

After Distribution: Distribute Page After Distribution

Consider subscribing to app events to monitor your application's lifecycle around token revocations and uninstallations.

Team app installation restrictions

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.

How users interface with your app

There are many ways your app may present itself and be discovered by users. Typically, Slack apps deal in the art of messaging.

  • Messages your app produces surface in the conversational user interface typical of working in Slack, whether your app contains a bot user or not, your app is capable of having an in-channel identity.
  • Installed apps containing slash commands will be present in the list of commands found by users invoking the workspace's slash command directory, typically by typing / in their chat box.
  • Apps featuring bot users have a home in the sidebar under the Apps heading. Similar to the presentation of direct messages, only open conversations will be displayed.
  • App suggestions are a superb way to train Slackbot to help you get the word out about your app.
  • Admin and installation interfaces — the images, words, and other information you provide about your app will be made visible to teams and their users.
  • Your app may appear in app directory interfaces, including directory interfaces in Slack and on the web.
  • Your installed app has a home in Slack. When users click your app's icon, they'll encounter an About this app information pane.

To look your best in all these surfaces, be sure and follow our best practices and guidelines.

Learn more about submitting your app to the Directory

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.

Additionally, please review our API Terms of Service, Brand Guidelines, and Slack App Developer Policy.

When you're ready to submit:

  1. Select your app from https://api.slack.com/apps
  2. Choose Submit to App Directory from the left-hand menu
  3. Complete the presented checklist and proceed with the submission process

Deactivating Distribution

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.

Suggesting apps to new users

Slackbot can suggest your directory-listed Slack app to new users. Find out all about app suggestions.

An example app suggestion for a bot called @beforebot.

Managing apps

Not only can your Slack app do all those things but because it's yours, you and a chosen team of collaborators:

  • Slack apps are owned and contained by the team they are created on.
  • Slack apps may have multiple App Collaborators associated with it, and they can review & manage the application record. They can also add or remove other 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:

  • View and alter basic information about your app, like its credentials and user-facing identity
  • Select and configure which types of integrations your app is composed of: message buttons, the Events API, incoming webhooks, slash commands, bot users, etc.
  • Assign and manage other Slack App Collaborators
  • Install your Slack app on your workspace
  • Submit a Slack app to be reviewed for inclusion in the App Directory, as well as manage the ongoing submission and re-submission process of a submitted app's associated beta application record.
  • Delete a Slack app

Managing your app's Collaborators

The Collaborators tab allows App Collaborators to manage which members of the team are allowed to configure a Slack app.

A list of App Collaborators

The app creator is also a Collaborator, until they're not

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.

Adding trusted 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.

Adding App Collaborators

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.

Removing Collaborators

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.

A Slackbot notification about a change to App Collaborators

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.