We know there's a lot to learn and read about all the integration points of the Slack platform. So, here's a few quick tips.

Anything else on your mind? Let us know by leaving us feedback!


How do I set up my developer environment?

There's no explicit sandbox or developer environment available to work against. Instead, you'll need to use a workspace you've created or are a member of. It's best to keep your integration or app's ownership contained within the workspace that is responsible for it. You can create a free Slack workspace to use as a sandbox by visiting this page. Once you're ready to deploy your app, distributing the app will allow you to install it in other workspaces.

Start by building a Slack app to contain all of your work β€” by default, it can only be installed on your own workspace. Follow the UI instructions to add features β€” most require that you provide a HTTP server Slack can reach.

While developing for your own workspaces, or if developing internal integrations, we strongly recommend using Socket Mode. For one such story, refer to this tutorial: Responding to app mentions.

How are incoming webhooks, slash commands, and bot users different?

All three integration types allow you to post messages within a channel, but differ both in how those messages are triggered and how users interact with your app. You can use all of these integration types together in your Slack app.

  • Incoming webhooks: send messages to a channel at will by using a specific URL. Best used when activities that would incite posting a message occur in a remote service.
    • Example: If you have an issue tracking system and want to post to a channel when a bug is created or resolved, use an incoming webhook invoked from the issue tracking system.
  • Slash commands: members execute slash commands from within Slack, resulting in us triggering your server to return them a message. The message can either be displayed only to the user who triggered it, or to the channel from which it was triggered.
    • Example: Your slash command allows users to create and resolve bugs from the Slack command line with either action resulting in a message being displayed to that channel.
  • Bot users: Your service monitors channels and direct messages for certain conversational triggers, such as specific text in messages posted or emoji responses. As appropriate, your bot user posts messages, or performs tasks inside or outside of Slack on a team's behalf.
    • Example: Your bot monitors a channel's messages for specific issue IDs and sends the channel a message containing details about them.
    • Example: Your bot tracks a team's emoji reactions and sends a message at the end of the day to celebrate those most used.

Is Slack down?

Of course we want Slack to be fully functional for users and developers at all times. Here are some tips in the unfortunate event you're having trouble and need to determine the cause of a Slack-related issue.

When possible, we report current status promptly on status.slack.com with any service disruption advisories, but you can try these tips to further divine service health:

Still unsure if Slack is down? Contact our enthusiastic support team.

I want to integrate some third-party service with Slack, how do I do that?

The best place to check if there is an app for a third-party service is the Slack App Directory. If you don't find anything there, it would best to check in with the specific third-party service and see if they have an app for Slack that isn't listed on our App Directory. If all else fails, you'll need to code one for yourself.


How do I authenticate my requests to Slack?

By token

When working with Slack apps or Web API, you'll often need to send access tokens, also known as bearer tokens, along with inbound requests within the authorization header. When creating an app for the first time, you'll be given your own user and bot token while going through the app creation process. In order to obtain other users' tokens you'll need to send users through the OAuth 2.0 authentication flow. When you're working with Slack apps, you'll be awarded access tokens after a user approves your application.

By private URL

Your incoming webhooks URLs are unique to your integration or application and do not require token-based authentication. Slash command response URLs also already encode your integration or application's identity.

How do I authenticate requests from Slack to me?

Use the signing secret to compute a signature, and verify that the signature on the request matches. This process is strongly preferred over the use of deprecated verification tokens.

You can also use Mutual TLS. Mutual TLS verifies the identity of Slack in a TLS-terminating server, before a request reaches your application code.

How does Slack authenticate its requests to my servers?

When you configure Outgoing webhooks, Slash commands and Message buttons, you specify a URL for Slack to send requests when qualifying conditions are met. Slack also provides you a token related to that integration.

Slack sends that URL a JSON payload containing a token field. Compare that field to values you've received from Slack. Refer to validating slash commands for more information.

When do authorization codes expire?

Authorization codes must be exchanged for an access token within 10 minutes by calling oauth.access as part of the authorization flow. Otherwise, the authorization code will expire and you will need to ask the user to go through OAuth again.

How do I revoke a token?

Use the apps.uninstall method to uninstall an app completely, revoking all tokens. If you want to dispose of a single OAuth access token, use auth.revoke; it works with tokens from Sign in with Slack as well as from Add to Slack.

For classic Slack apps, revoking the last token associated between your application and a workspace effectively uninstalls the app for that workspace.

Members and administrators can remove your app through their workspace administration interface.

Though it's somewhat of a nuclear option, you also have the ability to revoke all tokens from your developer dashboard by selecting your application and clicking the Revoke all tokens button found there.

How do I reset my client secret?

To reset your client secret, go to your developer dashboard, select the application you are concerned about, and click the Change secret button.

Don't forget to use your new secret when exchanging authorization codes for access tokens while authorizing users and workspaces with OAuth 2.0.

Classic vs. next-gen Slack apps

Building a classic Slack app? Start here. Building a next-gen Slack app? Start here.

What's the difference? Check out this video for a quick introduction to the new Slack Platform:

Bot users

How do I use API methods with my bot user token?

When you install Slack App that contains a bot user, you're awarded a bot user token. This token is used for performing certain actions directly as the bot user, such as posting a message or uploading a file. You can only call Web API methods based on the scopes you've negotiated. A quick way to call an API method is to head to its page here and find the tester tab. Here's an example for the chat.postMessage method.

Slash commands

Why does Slack never reach my slash command URL?

Typically, if Slack cannot reach your slash command URL it's because it's either inaccessible, does not have a valid, verifiable SSL certificate, or our request is timing out for some reason.

Slack invokes slash command URLs from its servers rather than from a Slack client app like Slack for Mac. This means that the URL we're trying to reach must be accessible to Slack's servers.

To determine whether your certificate is valid, consider using this tool provided by SSL Labs.

How do I validate a slash command's origin?

Keep track of the validation tokens and team IDs Slack gives you when commands are created and teams approve your app. Always validate that the token field in an incoming slash command request has been issued to you by Slack, and scope your data for that workspace.

Incoming webhooks

Why can't I override the channel, icon, or user name of my incoming webhook?

You won't be able to override any of these fields when using an incoming webhook attached to a Slack app. Instead, those values will be provided from your Slack app configuration and any configuration provided by the team.

Interactive messages

Can I use a self-signed certificate for my action URL?

No, SSL certificates must be signed by a reputable certificate authority.

You may want to consider using one of the following low-cost providers:


Can I send JSON when using HTTP POST?

Yes, the Web API accepts both application/x-www-form-urlencoded POSTs as well as application/json.

Refer to POST bodies for more information.

How is the API rate limited?

Slack rate limits all aspects of platform use with many factors. Review our rate limiting documentation for more detail. The guiding spirit of Slack's rate limiting is to ensure that teams are able to communicate effortlessly and without distraction.

When you've hit a rate limit, you will receive a HTTP 429 Too Many Requests rate limited message in response to a request, and will then need to wait for the next rate limiting window to open. The next rate limit is indicated by a HTTP header called Retry-After, presented in seconds to wait before attempting another request. If the value were 10, then you should wait 10 seconds or more before retrying that request.

You may find that you can't perform certain bursty actions, like attempting to message every member of a large workspace simultaneously. In some cases, hitting rate limits may be a symptom that there are better ways to to accomplish your goal. Some times you just need to work slower.

How do I work with files?

The Real Time Messaging API and other API methods reference file objects that contain a suite of details about the content type of the file and absolute URLs where those files can be retrieved or used for display.

As of January 4th, 2016, applications must provide authentication to access the actual files that file objects reference. There's a blog post discussing this change of behavior.

File objects contain url_private and url_private_download fields, as well as fields for private thumbnail URLs as applicable. To retrieve these URLs, you must provide a HTTP Authentication header containing a bearer token that's been awarded the files:read or read scopes. For example, to retrieve a thumb_360 field containing https://files.slack.com/files-tmb/Z0CHK-THSCH5-5SZ0UT/cheese.jpg and your bearer token was VALID_TOKEN, you'd need to send a request like this:

GET https://files.slack.com/files-tmb/Z0CHK-THSCH5-5SZ0UT/cheese.jpg
Authorization: VALID_TOKEN

How do I find a channel's ID if I only have its #name?

There are currently no methods to directly look up channels by name. Use conversations.list to retrieve a list of channels. The list includes each channel's name and id fields.

Many developers keep the list of channels in memory for swifter lookups. Poll the method occasionally to refresh your inventory or keep keep it updated with the Events API.

How do I find a channel's name if I only have its ID?

You can use similar instructions to the question above, or you can use dedicated methods to look up a channel by its ID.

Use conversations.info to obtain a specific channel's information, including its name.

Do channel IDs stay the same when the name of the channel changes?

Channel IDs remain the same even when names are changed.

Do channel IDs stay the same when moving between public and private?

As of September 2018, channel IDs remain static even when a channel is converted between public and private.

Use the Conversations API to safely work with channels that have transitioned between public and private.

How do I retrieve a single message?

Use conversations.history and a token with the channels:history scope to retrieve a specific message in a public channel. Learn more about this approach.

Events API

How do I re-enable event subscriptions for my app?

If your app's subscriptions are disabled due to exceeding Events API failure limits, manually re-enable them by visiting your application's settings. If your app is part of the directory, use your Live App Settings instead of your development app.

When should I use the Events API and when should I use Socket Mode or the RTM API?

Choose the Events API if:

  1. You want to precisely scope the data you receive to just what your app needs.
  2. You prefer or must use an inbound request model due to one of the following: a) your hosting service is not able to maintain an outbound WebSocket connection, or b) you prefer to scale your application on an inbound request model instead of maintaining multiple long-lived WebSocket connections.
  3. You're converting a outgoing webhook integration into something installable as a Slack app.
  4. You find the retry behavior reassuring for redundancy reasons.

Choose Socket Mode if:

  1. You're building an on-premise integration or have no ability to receive external HTTP requests.
  2. You're working on a distributed or mobile application without a server backend.
  3. You just prefer working with WebSockets. That's cool.
  4. You want data feed redundancy by opening additional WebSocket connections.
  5. You want messages to be delivered to you in real time.

Finally, choose the Real Time Messaging API only if:

  1. You need events that just aren't supported by the Events API.
  2. You need compatibility with today's existing tools.
  3. Sending user_typing events is important for your app or bot user's sense of self and agency.
  4. Receiving events in absolute order is important to you.

How do I make my bot appear active and present?

The answer depends on whether you're using the Events API with or without the RTM API:

  • With the Events API, you must toggle your presence by managing your app's bot user config.
  • With the RTM API, your bot is marked active while connected to a WebSocket.

Therefore, the presence of the bot depends on whether you are using the RTM API (the bot is online when it's connected through the WebSocket), or it's always online when you turn this setting on. Refer to bot presence for more information.

Socket Mode

Socket Mode allows you to use the Events API and interactive features of the platform β€” without exposing a static HTTP endpoint to receive payloads. Instead, you use the WebSocket Protocol and generate a URL at runtime.

The Real Time Messaging (RTM) API is another way of connecting your application to Slack. For most applications that can't use a static HTTP endpoint, Socket Mode is preferred over RTM.

Real Time Messaging API

For most applications, Socket Mode is a better way to communicate with Slack.

How do I connect to a WebSocket?

The first step is making a typical HTTP request to the rtm.connect method. Within that response, you'll find a url field beginning with the URI protocol wss://. Then, use a Websocket client to open a long-lived connection to that time-sensitive URL. While the connection is open, you'll be streamed events associated with the workspace you're connecting on behalf of and can in turn send messages.

Typical HTTP client libraries and tools do not support connecting to WebSockets directly. You will need to find a client library for your preferred programming environment.

App approvals

How does my app get approved for the directory?

  1. Create a Slack app record to package your integration points and to obtain your app's platform credentials for use in authentication and the "Add to Slack" button.
  2. Review this checklist to ensure your app is prepared for the approval process.
  3. Submit your application for review.
  4. Slack will review your application and approve it if it meets our criteria.

Please be patient, as our team regularly reviews submissions. To help the process go as smoothly as possible, we strongly recommend following the checklist before submitting.

What happens if I make changes to an application that has been approved for the directory?

If you need to update your approved app to request new OAuth scopes, or to include new features, find your application's settings page at https://api.slack.com/apps. Any changes you make here will not affect the published app.

Once you're ready to apply these changes to the published app, re-submit it for review using the process described above.

What kind of changes to my app will require being reviewed again?

If you've submitted your app to the directory but need to make changes to how your app or bot is described, to the integration types packed into your app, or to request additional permissions, you'll need your app to be reviewed again.

Use the beta application corresponding to your submitted Slack app to make modifications to any of these features, such as:

  • Requesting new OAuth permission scopes
  • Changing your message button action URLs
  • Changing your slash command execution URLs & other details about your slash command
  • Changing your Events API subscription URLs or subscriptions
  • Changing your bot user's username
  • Changing your app's OAuth configuration
  • Changing details about how your application is presented in the directory
    • Application description
    • Contact information
    • Application icon
    • Policy & Website URLs
    • etc.

Your client secret and signing secret may be regenerated as needed, without requesting further review.

Do I need to submit my Slack App to the directory if I don't want to?

No, only submit your app to the directory if you want your app to be discoverable and installable from the App Directory. If you don't submit your app, we won't display it there, but it will be installable by any workspace you give the authorization URL to.

Who moved my cheese?

It was @colonel_mustard in the #conservatory with the :fork_and_knife:. A custom and internal investigation will follow this Slack app fact.

Scaling your app

How do I avoid long response times and timeouts while working on behalf of large workspaces?

  1. If you're using the RTM API, use rtm.connect to initiate your WebSocket connection instead of rtm.start. rtm.connect returns just the data you need to open your connection.
  2. If you must rtm.start, use the no_latest parameter to remove the latest field from each channel object.
  3. If using channels.list, use the exclude_members parameter to trim long membership lists from each channel object.

Team vs. workspace

Why is an ID for a workspace is called team_id, not workspace_id?

Our bad. We used to overuse the term team which could mean two different things β€” the people you talk to, as well as the Slack workspace, the place you do work!

Now we use workspace for all the Slack workspaces; however our API remains the same as before. Wherever you see some objects containing team_id, it really is an ID for the workspace! In the API world, we use the two terms interchangeably.

Transitioning from IRC & XMPP gateways

How can I test basic Slack messaging behavior from the command line?

There are some community-authored open source tools that provide an IRC-like experience on top of Slack APIs. Although they are not directly supported or built by Slack, you can leverage these resources to build your own tools:

How do I build a bot using Slack APIs?

Bots and integrations with Slack can be built a few different ways.

One common pattern is:

  1. Create a Slack app to contain all the pieces of your bot integration at api.slack.com/apps.
  2. Using app management, add the bot user and event subscriptions features to your app and configure them.
  3. Under Event Subscriptions, subscribe to "Bot Events" like app_mention, messages.mpim, and messages.im to receive events whenever users send your bot messages in channels and direct messages. Subscribe to other events your bot may be interested in.
  4. Install your Slack app to your workspace through app management to activate subscriptions and receive your bot user token.
  5. Use the bot user token to send messages to chat.postMessage to post new messages or reply to users.

The RTM API may be used instead of the Events API to receive messages (and many more events) over a WebSocket. Messages can also be sent via the RTM API without needing to use chat.postMessage.

How do I build an IRC or XMPP gateway for myself using the API?

Building your own gateway for personal use is an undertaking.

The part of the gateway that reads from Slack should either connect to the RTM API over a WebSocket or listen for events using the Events API. Use the Web API to post messages and perform channel operations. The XMPP or IRC part of the gateway is its own adventure to explore.

Choose the token type that works best for you. Bot user tokens work well if your user is a bot but poorly if your user is you. Properly scoped user tokens work best, as they model your own relationship to Slack. The client scope is useful but overly broad and not suitable for an app distributed on the App Directory. Using your user token to post as yourself when posting messages with chat.postMessage is best.

Apps operating as a gateway should never distribute their API keys, secrets, or tokens. Refer to these open source CLI apps for some inspiration.

Workflow Builder

Is it possible to add a workflow to multiple channels?

While you cannot add a single workflow to multiple channels, you can download a workflow file and then import it into Slack and update the channel in which it triggers in. To download a workflow file, within the Workflow Builder, click on the three dots beside the workflow you would like to download and click "Download workflow file".

Is it possible to have workflows branch into different paths based on form answers?

No, at the moment it isn't possible to have conditionals within a Workflow but we're definitely considering this for a later iteration of the Workflow Builder.

Outlook Calendar app

The Outlook Calendar app is frozen and hasn't updated in a couple days. How do I reset it?

The best way to to reset the Outlook Calendar app is to start fresh by removing and re-adding your Outlook Calendar authorization. Here are the steps to do that:

  1. Log out of all your Outlook accounts in all your web browsers, OR log in from within an incognito/private web browser window.
  2. Revoke your Outlook Calendar authorization from the following page, making sure to only remove your own: https://my.slack.com/apps/AFV5ECLBZ-outlook-calendar?next_id=0
  3. Once you've removed your Outlook Calendar authorization, go back and try to reauthorize the app again by clicking the Allow button on the following page.
  4. After that, you may be prompted to connect your calendar in Slack. If not, enter the /ocal command and see if that prompts you. When it does, connect to your Office 365 calendar.