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 25, 2020 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.
We resolutely recommend migrating to the Conversations API immediately.
We're marking all Web API methods in the channels, im, groups, and mpim namespaces as deprecated. They will retire and cease functioning on November 25, 2020.
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 November 25, 2020 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.
| 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. |
| 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. |
| 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. |
| 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. |
| 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: |
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.
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 November 25, 2020, 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.
We strongly encourage you to migrate to the Conversations API as soon as possible.
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 November 25, 2020, 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 November 25, 2020, expect these methods to continue to degrade and become incompatibility with evolving channel types on Slack.
Please contact us with any concerns at developers@slack.com
Review other recent updates