We want to update you about our previous announcement regarding the retirement of our old documentation experience on api.slack.com. We have moved the date from the end of June 2025 to the end of August 2025.
Long a staple of workflow apps built with the Deno Slack SDK—and now with recent support for Bolt frameworks—we're proud to make the ever-growing Slack CLI part of our collection of open source tooling.
We love contributions from our community, so we encourage you to explore and interact with the GitHub repo. Contributions, bug reports, and any feedback are all helpful; let us nurture the Slack CLI together to help make building Slack apps more pleasant for everyone.
Not familiar with the Slack CLI? Visit the docs and follow the installation guide to begin your journey.
As previously announced, the Slack platform and developer tools documentation are moving: the Slack platform documentation is now in beta on docs.slack.dev, and the developer tools documentation has moved to its new home on tools.slack.dev.
Our next step is to sunset the old documentation experience on api.slack.com, and we plan to do so by the end of June August 2025. In the meantime, you may want to update any bookmarks you have pointing to api.slack.com—but not to worry, we'll have redirects in place to make sure you end up right where you need to be!
Today is the day! As previously mentioned, the Slack platform and developer tools documentation are moving: the shiny new Slack platform documentation is now in beta on docs.slack.dev, and the developer tools documentation has fully moved to its new home on tools.slack.dev. The doors are open for our housewarming party 🥳 so come on in, take a look around, and let us know what you think. Thanks for coming along on this journey with us!
On December 10, 2024, we updated the Slack App Developer Policy to add clarity to guidance from our documentation that apps intended for commercial distribution at scale should go through Slack Marketplace review.
While gathering feedback from early customers helps improve your apps, the Slack Marketplace is the right place for apps as they begin to grow. The Slack Marketplace guidelines and our review process help keep the Slack app ecosystem working and customer data secure.
We also clarified existing guidelines about the usage of data collected by your app. Specifically, we are making explicit that the use of data to train an LLM is prohibited.
As you may have read in our November newsletter, Slack platform API documentation is moving! The Slack Documentation team is currently overhauling the API documentation—both front-end and back-end—to enhance your developer documentation experience.
While you won’t see any changes until March 2025, we promise to keep you in the loop. Change is a journey, and we’re here with you every step of the way!
We updated our developer policy to clarify guidance around circumventing Slack limitations. We also tweaked our developer program agreement. Read on to see the short list of changes.
We're modifying text presented in Slack message attachments (links to other messages in Slack) via the footer and channel_name fields for consistency.
Today we're announcing that the Slack automations platform—which provides a faster, more flexible way to build automations on top of Slack–is generally available to developers. The platform's overhauled architecture gives developers more ways to build, code, and ship custom apps and workflows more quickly and easily in an environment that's both secure and compliant. Read the announcement or follow the Quickstart to get started today.
On September 1, 2021, the link_shared event is changing. The change will happen for free teams on September 1, and will roll out to paid teams over the following weeks.
The chat.unfurl method will also accept new arguments.
Changes to link_shared will help enable a smoother unfurl experience for apps that haven't yet been installed.
Until now, it's often been confusing to understand when and where an app may provide customized unfurl behavior for links appearing in conversations. We're gradually rolling out changes that will make this behavior consistent and easily understood. Read on to learn more.
Tokens may no longer be passed in the query string for apps created after Feb 24, 2021
On February 24, 2021, we will stop allowing newly created Slack apps to send requests to Web API methods with access tokens presented in a URL query string. Instead, apps must send tokens in the Authorization HTTP header or alternatively as a URL-encoded POST body parameter.
Existing apps will be allowed to continue sending their tokens in the token query string parameter, though we recommend all apps to use authorization headers whenever possible.
On September 30, 2020 we updated the Slack Application Developer Policy and API Terms of Service to clarify existing guidelines.
Free teams feature a 5 GB limit on file uploads. However, as in the Wild Wild West of yore, the limit wasn't enforced. As of March 5, 2019, we're starting to enforce the file upload limit more firmly: only the last 5 GB of files will be visible to Free teams. In APIs that return file uploads, older files beyond the limit will be shown as 'tombstoned,' with redacted information and a "hidden_by_limit" field.
On August 31, 2018 we'll update the Slack Application Developer Policy and API Terms of Service to clarify existing guidelines that keep Slack a safe and secure platform for work.
We've added the message.app_home event for workspace apps building on our developer preview.
If you subscribe to message.im events to receive messages between users and your app in the special kinds of 1:1 conversations had in your app homes, you must add a subscription to message.app_home to continue receiving and acting on those messages.
Workspace apps grant apps a dedicated space within Slack where members can interact directly— we call it your App Home. Apps can use this space for personal notifications, onboarding information, and other helpful features.
We're fixing file comments and in the process we're phasing out some related API methods and events.
File comments look like messages in a channel but they aren't. They travel with files, wherever shared, disrupting conversation at inopportune moments.
We started to gradually roll out file threads on July 23, 2018. Sharing a file with a channel will now create an actual message instead of something that looked convincingly like a message. People and bots may reply to that message as they would any other message. You can even upload files into threads.
We're simplifying the installation process for workspace apps.
Now workspace apps can and should use the oauth.access method instead of oauth.token during the verification code exchange phase of app installation via OAuth 2.0.
When used with workspace apps, the response for oauth.access morphs into a response similar to that of oauth.token, but with a few improvements detailed below.
Now oauth.access may be used by workspace apps instead of oauth.token, simplifying a common hurdle when getting started with workspace apps.
Finally, we're replacing apps.permissions.info with apps.permissions.scopes.list and apps.permissions.resources.list.
We're simplifying some permission scopes as part of the workspace apps developer preview.
Beginning today, workspace apps must request files:write instead of files:write:user during installation or when seeking elevated permissions.
Now files:write represents your app's ability to upload and manage files.
Experiencing déjà vu? This is just like that time we did this for chat:write.
We're tidying up the character limits on the text field of posted messages.
Beginning April 25th, 2018, we truncated messages sent to Slack that are longer than 500,000 characters. As of July 12, 2018, we truncate at 100,000 characters.
Over the next several weeks, we slowly lowered the allowed character count.
On August 12, 2018 we started truncating messages containing more than 40,000 characters.
Until now, the rate limits governing the Slack Web API have been vague, even sometimes undefined.
This week we are rolling out an evolved rate limiting system granting a greater number of requests to most methods and sets responsible defaults in the few cases where limits were more mysterious or unenforced.
We've granted a brief grace period to a small number of apps & integrations to adjust.
Legacy workspace apps are deprecated and will retire in August 2021. Learn more.
We're simplifying some permission scopes as part of the workspace apps developer preview.
Beginning today, workspace apps must request chat:write instead of chat:write:user during installation or when seeking elevated permissions.
Now chat:write represents your app's ability to post messages in the channels and contexts granted to it.
As of January 2018, presence_change events are not dispatched without presence subscriptions established with presence_sub. Relatedly, current user presence status is no longer communicated in rtm.start. Learn more.
Beginning November 15, 2017, the RTM API's presence_sub event will be available via presence subscription only.
Back in June, we introduced new ways to track user presence and the presence_change event in the RTM API.
Dispatching presence events for all users in a workspace is an expensive operation for Slack. A flood of presence events from large workspaces can also disrupt your app's ability to process more useful, timely messages.
By subscribing only to the presence events your app needs to provide presence-dependent functionality, you can reduce unnecessary websocket traffic.
Arrays of members found in API methods will become truncated beginning December 1, 2017.
members continues to decrease regularlyAs of March 2018, the limit is set to 500 results. Use conversations.members for channels with large memberships.
Initially, Slack will limit members to the first 1,500 users and then gradually lower the number of users returned. You should expect API methods will cease returning members entirely at some point in the future. If you rely on the members array, you should instead begin using conversations.members for a full list of members.
As Slack teams continue to grow in size, returning the full members array in these methods is no longer practical or performant, for the Slack APIs or developers. The conversations.members method will allow you to request a list of members at a time that makes sense for your app and should keep these method calls nice and zippy.
Slack is phasing out the @username artifact in favor of the more expressive and flexible concept of display names.
Handles, aliases, call-signs, and usernames — in chat, they all repersent the same concept: a way for an individual or entity to indicate a preferred identification noun, in whichever way is appropriate to the apparatus at work.
Users will be even better equipped to present their preferred nomenclature while giving organizations the option to work primarily with so-called real names as suits "the suits."
The transition should be technically "backwards compatible" to you, the developer. But the social ramifications, changes in user behavior, and treatments given in Slack clients will inevitably alter the way your apps approach interpreting, storing, and utilizing the now deprecated name field.
As fellow developers, we know you'll have some feelings about the sunset of @username considering its historical significance in computing, networking, and digital identity. From mainframes to UNIX to BBSes to IRC, maybe you've used the same name for what seems like centuries.
Fly your freak, geek, or mild-mannered flag proudly by just setting your display name to your preferred @username.
As of January 2018, presence_change events are not dispatched without presence subscriptions established with presence_sub. Relatedly, current user presence status is no longer communicated in rtm.start. Learn more.
If you've been developing on Slack for awhile you may have noticed a continued theme with updates we make to the platform and APIs: larger teams and evolving use cases mean previous ways of enumerating collections of data become unwieldy and even problematic.
In this exciting edition of the changelog, I'd like to introduce you to new ways to work with presence_change events in the RTM API.
If you don't work with the RTM API or don't utilize presence_change events, there's very little of value for you in this changelog.
We've long delivered a message subtype event to everyone in a channel as members come and go.
As a message, its main purpose is to communicate facts to users but it was never a very good vehicle for communicating these facts to bots and applications.
We're introducing new, more frugal logic behind when Slack dispatches message.channel_join and message.channel_leave message subtype events in the RTM API and Events API.
If you've relied on these events for programmatic notice when members leave or join a channel, we've got new, strongly structured signals for you to subscribe to and consume instead, member_joined_channel and member_left_channel.
The [users:read.email](/reference/scopes/users.read.email OAuth scope is now required to access the email field in user objects returned by the users.list and users.info web API methods. users:read is no longer a sufficient scope for this data field. Learn more.
Back in November 2016, we introduced the users:read.email OAuth permission scope, allowing more explicit access to email addresses.
To help developers with the transition, we automatically grandfathered apps asking for users:read created before January 4th, 2017.
We'd like to complete this transition and remove this grandfathering entirely on August 21, 2018 October 16, 2018 a future date we'll one day announce.
Apps created before January 4th, 2017 with user tokens granted only the users:read scope will no longer receive the email field in user objects.
If you want access to email addresses, you'll need the new OAuth permission scope, users:read.email. It provides an explicit, additive way to request access to team email addresses.
Additionally, the bot scope will no longer grant bot user tokens access to email addresses. Bot users must utilize a user token and the users:read.email scope instead.
Don't need access to email address but do need access to user data? users:read should be all you need.
It's almost spring and we're doing a little cleaning early this year.
Ever notice how the username field of a file object in channels.history or [file_shared](/reference/events/file_shared event isn't like typical username fields and contains a bunch of markup usually reserved only for message text?
And why is there a top-level skype field in user profile objects when really, shouldn't that be a custom field?
Well, we've noticed. And so...
The [users:read.email](/reference/scopes/users.read.email OAuth scope is now required to access the email field in user objects returned by the users.list and users.info web API methods. users:read is no longer a sufficient scope for this data field. Learn more.
Grandfathering is no longer in effect. Please see this post from April 2017 for more information.
We've added a new OAuth permission scope called users:read.email and it provides a new explicit, additive way to request access to team email addresses. If you don't need email addresses but do need other user info, users:read is still all you need.
Apps created before January 4th, 2017 are grandfathered and will continue behaving in a backwards-compatible way. Apps created after that date must request the new users:read.email scope. Regardless of creation date, we encourage all apps to migrate to this new scope.
Beginning next month, newly issued tokens will be longer than previously issued tokens.
Until now, we haven't documented the string length of tokens, so we hope you've used caution when preparing your token storage apparatuses.
As Slack works to serve the needs of larger businesses by building an enterprise product offering, some aspects of our infrastructure and platform are evolving.
Long ago, a small number of enterprising users and developers scoured through client-side code to discover embedded user tokens and began posting messages and performing other skunkworks operations with them. We applaud this adventurous spirit!
Today we take the first step in retiring usage of these antiquated tokens, by changing their behavior when used to post messages through chat.postMessage.
Today, incoming webhooks either work or they don't. Usually they do, but when they don't, you get a somewhat nasty umbrella HTTP 500 error, even when error conditions were due to something well-understood, like malformed requests or non-existent destination channels.
We will diversify our responses to include commonly-interpreted HTTP status codes. For most developers using incoming webhooks, this change will not require additional effort. Most HTTP clients readily consume and predictably react with these status codes.
If you parse events referencing files in the real-time messaging API, you may have noticed we send a sometimes comically large packet of information when streaming nearly anything related to a file.
To improve performance and provide a better user experience, we're reducing the payload of most file-related events in the RTM API to include only the file's ID. You'll need to use the files.info API method to retrieve additional information about files.
These changes will roll out gradually beginning May 16th, 2016 — read below to understand how this change may effect you, especially if you work with bot users.
Bot users will gain comparable capabilities, allowing bot user tokens to work with files.info based on the channel memberships and related capabilities granted to them.