Deprecating early methods in favor of the Conversations API
Updated: Wednesday, May 20, 2020
We released the Conversations API in September 2017 as a one-size-fits-all replacement for a variety of APIs used to read and write information about channels, private channels, direct messages, and multi-party direct messages.
Today we are announcing the deprecation of the methods that preceded the Conversations API (channels.*
, groups.*
, im.*
, & mpim.*
). On November 25th, 2020 February 24th, 2021 these methods will retire and cease functioning.
If users expect your app to work in channels of any kind, you'll want to verify you're using the Conversations API for all channel types.
- The final date for existing apps is now February 24th, 2021.
-
We'll stop allowing newly created Slack apps to use these deprecated APIs beginning June 10th, 2020.
-
All
channels.*
,groups.*
,im.*
, &mpim.*
methods will return deprecation warnings beginning June 10th, 2020.
We resolutely recommend migrating to the Conversations API immediately.
- What's changing
- Deprecated methods
- Deprecation warnings
- How to respond or prepare
- What happens if I do nothing?
- When is this happening?
What's changing
We're marking all Web API methods in the channels
, im
, groups
, and mpim
namespaces as deprecated. They will retire and cease functioning on February 24th, 2021.
Any usage of those methods should be transferred to the newer Conversations API equivalents.
You'll especially want to migrate promptly if your app works with private channels or shared channels, as the deprecated methods function poorly or not at all with them.
As February 24th, 2021 approaches, these deprecated methods will continue to degrade as they have in the past. We are certain that the groups.*
methods in particular will cease functioning with newly created private channels in the coming weeks and months.
Update: On June 10th, 2020, newly created Slack apps will no longer be able to use these deprecated methods. Apps created before June 10th, 2020 will continue having access until February 24th, 2021.
Deprecated / retiring methods
Method & Description | Description |
---|---|
channels.archive Archives a channel. | Archives a channel. Replaced by: |
channels.create Creates a channel. | Creates a channel. Replaced by: |
channels.history Fetches history of messages and events from a channel. | Fetches history of messages and events from a channel. Replaced by: |
channels.info Gets information about a channel. | Gets information about a channel. Replaced by: |
channels.invite Invites a user to a channel. | Invites a user to a channel. Replaced by: |
channels.join Joins a channel, creating it if needed. | Joins a channel, creating it if needed. Replaced by: |
channels.kick Removes a user from a channel. | Removes a user from a channel. Replaced by: |
channels.leave Leaves a channel. | Leaves a channel. Replaced by: |
channels.list Lists all channels in a Slack team. | Lists all channels in a Slack team. Replaced by: |
channels.mark Sets the read cursor in a channel. | Sets the read cursor in a channel. Replaced by: |
channels.rename Renames a channel. | Renames a channel. Replaced by: |
channels.replies Retrieve a thread of messages posted to a channel | Retrieve a thread of messages posted to a channel Replaced by: |
channels.setPurpose Sets the purpose for a channel. | Sets the purpose for a channel. Replaced by: |
channels.setTopic Sets the topic for a channel. | Sets the topic for a channel. Replaced by: |
channels.unarchive Unarchives a channel. | Unarchives a channel. Replaced by: |
groups.archive Archives a private channel. | Archives a private channel. Replaced by: |
groups.create Creates a private channel. | Creates a private channel. Replaced by: |
groups.createChild Clones and archives a private channel. | Clones and archives a private channel. |
groups.history Fetches history of messages and events from a private channel. | Fetches history of messages and events from a private channel. Replaced by: |
groups.info Gets information about a private channel. | Gets information about a private channel. Replaced by: |
groups.invite Invites a user to a private channel. | Invites a user to a private channel. Replaced by: |
groups.kick Removes a user from a private channel. | Removes a user from a private channel. Replaced by: |
groups.leave Leaves a private channel. | Leaves a private channel. Replaced by: |
groups.list Lists private channels that the calling user has access to. | Lists private channels that the calling user has access to. Replaced by: |
groups.mark Sets the read cursor in a private channel. | Sets the read cursor in a private channel. Replaced by: |
groups.open Opens a private channel. | Opens a private channel. |
groups.rename Renames a private channel. | Renames a private channel. Replaced by: |
groups.replies Retrieve a thread of messages posted to a private channel | Retrieve a thread of messages posted to a private channel Replaced by: |
groups.setPurpose Sets the purpose for a private channel. | Sets the purpose for a private channel. Replaced by: |
groups.setTopic Sets the topic for a private channel. | Sets the topic for a private channel. Replaced by: |
groups.unarchive Unarchives a private channel. | Unarchives a private channel. Replaced by: |
im.close Close a direct message channel. | Close a direct message channel. Replaced by: |
im.history Fetches history of messages and events from direct message channel. | Fetches history of messages and events from direct message channel. Replaced by: |
im.list Lists direct message channels for the calling user. | Lists direct message channels for the calling user. Replaced by: |
im.mark Sets the read cursor in a direct message channel. | Sets the read cursor in a direct message channel. Replaced by: |
im.open Opens a direct message channel. | Opens a direct message channel. Replaced by: |
im.replies Retrieve a thread of messages posted to a direct message conversation | Retrieve a thread of messages posted to a direct message conversation Replaced by: |
mpim.close Closes a multiparty direct message channel. | Closes a multiparty direct message channel. Replaced by: |
mpim.history Fetches history of messages and events from a multiparty direct message. | Fetches history of messages and events from a multiparty direct message. Replaced by: |
mpim.list Lists multiparty direct message channels for the calling user. | Lists multiparty direct message channels for the calling user. Replaced by: |
mpim.mark Sets the read cursor in a multiparty direct message channel. | Sets the read cursor in a multiparty direct message channel. Replaced by: |
mpim.open This method opens a multiparty direct message. | This method opens a multiparty direct message. Replaced by: |
mpim.replies Retrieve a thread of messages posted to a direct message conversation from a multiparty direct message. | Retrieve a thread of messages posted to a direct message conversation from a multiparty direct message. Replaced by: |
Deprecation warnings
When you issue a request to one of these deprecated methods, beginning June 10th, 2020 you'll receive a method_deprecated
warning included in every response.
Examine the response_metadata
for textual hints on how to resolve the warning. The text will mention the retirement date. If there's a method you should use instead of the one you're attempting, we'll mention that in the warning too.
For example, if you request channels.list
you'll see a warning like this:
{
"ok": true,
// ...
"warning": "method_deprecated",
"response_metadata": {
"warnings": [
"[WARN] This method is deprecated and is scheduled to cease functioning on 2021-20-24. Please use conversations.list instead. Learn more: https://api.slack.com/changelog/2020-01-deprecating-antecedents-to-the-conversations-api",
]
}
}
One day this warning will become an error...
How to respond or prepare
Almost every method beginning with channels.
, mpim.
, groups.
,im
will have a corresponding method in conversations.
.
For example, if you make requests to channels.list
, mpim.list
, groups.list
, or im.list
, you will use conversations.list
instead. Using the type
parameter you can limit results by just private channels, or just direct messages, or a hybrid of some or all conversation types. If you use groups.archive
then conversations.archive
will do the trick instead.
Each conversations.*
equivalent has response shapes standardized across conversation types. While migrating, you will encounter new fields and data structures so you'll want to review how you're treating the response as well.
If you need the members of a specific channel or conversation, use conversations.members
. If you need a list of conversations a specific user is party to, use users.conversations
.
Shared channels are only supported by migrating to the Conversations API. Channels that have had their permissions type changed between public and private may only be accessed with the Conversations API. One day, newly created private channels will only be accessible with the Conversations API.
What happens if I do nothing?
If your app doesn't use the Web API, or doesn't rely on the first letter of a channel ID to determine behavior, or if you simply don't use any of the deprecated methods — your app should continue functioning without modification.
If you use these methods in the days and weeks leading up to February 24th, 2021, your app may continue functioning but won't work with certain kinds of channels like shared channels or channels that have converted their privacy status.
If you use any of the private channel methods (groups.*
), you will at some point in the future lose access to the most recently created kinds of private channels, which only work with the Conversations API.
If you create new Slack apps often, your newly created Slack apps won't be able to access the deprecated methods after June 10th, 2020.
We strongly encourage you to migrate to the Conversations API as soon as possible.
When is this happening?
Today, January 7, 2020 these methods are officially deprecated. That means they are not only discouraged but have an explicit retirement date where they will cease functioning.
On June 10, 2020, these methods won't be usable by newly created Slack apps.
On February 24th, 2021, these methods will become retired and no longer function. You must use conversations.*
equivalents by that date or risk service interruptions for your app.
Between now and February 24th, 2021, expect these methods to continue to degrade and become incompatible with evolving channel types on Slack.
Please contact us with any concerns at feedback@slack.com
Review other recent updates