You must enable javascript in order to use Slack. You can do this in your browser settings.

Deprecating early methods in favor of the Conversations API

Published: Tuesday, January 7, 2020
Updated: Wednesday, May 20, 2020
APIs

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

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 & DescriptionDescription
channels.archive
Archives a channel.
Archives a channel.

Replaced by: conversations.archive 

channels.create
Creates a channel.
Creates a channel.

Replaced by: conversations.create 

channels.history
Fetches history of messages and events from a channel.
Fetches history of messages and events from a channel.

Replaced by: conversations.history 

channels.info
Gets information about a channel.
Gets information about a channel.

Replaced by: conversations.info 

channels.invite
Invites a user to a channel.
Invites a user to a channel.

Replaced by: conversations.invite 

channels.join
Joins a channel, creating it if needed.
Joins a channel, creating it if needed.

Replaced by: conversations.join 

channels.kick
Removes a user from a channel.
Removes a user from a channel.

Replaced by: conversations.kick 

channels.leave
Leaves a channel.
Leaves a channel.

Replaced by: conversations.leave 

channels.list
Lists all channels in a Slack team.
Lists all channels in a Slack team.

Replaced by: conversations.list users.conversations 

channels.mark
Sets the read cursor in a channel.
Sets the read cursor in a channel.

Replaced by: conversations.mark 

channels.rename
Renames a channel.
Renames a channel.

Replaced by: conversations.rename 

channels.replies
Retrieve a thread of messages posted to a channel
Retrieve a thread of messages posted to a channel

Replaced by: conversations.replies 

channels.setPurpose
Sets the purpose for a channel.
Sets the purpose for a channel.

Replaced by: conversations.setPurpose 

channels.setTopic
Sets the topic for a channel.
Sets the topic for a channel.

Replaced by: conversations.setTopic 

channels.unarchive
Unarchives a channel.
Unarchives a channel.

Replaced by: conversations.unarchive 

groups.archive
Archives a private channel.
Archives a private channel.

Replaced by: conversations.archive 

groups.create
Creates a private channel.
Creates a private channel.

Replaced by: conversations.create 

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: conversations.history 

groups.info
Gets information about a private channel.
Gets information about a private channel.

Replaced by: conversations.info 

groups.invite
Invites a user to a private channel.
Invites a user to a private channel.

Replaced by: conversations.invite 

groups.kick
Removes a user from a private channel.
Removes a user from a private channel.

Replaced by: conversations.kick 

groups.leave
Leaves a private channel.
Leaves a private channel.

Replaced by: conversations.leave 

groups.list
Lists private channels that the calling user has access to.
Lists private channels that the calling user has access to.

Replaced by: conversations.list users.conversations 

groups.mark
Sets the read cursor in a private channel.
Sets the read cursor in a private channel.

Replaced by: conversations.mark 

groups.open
Opens a private channel.
Opens a private channel.
groups.rename
Renames a private channel.
Renames a private channel.

Replaced by: conversations.rename 

groups.replies
Retrieve a thread of messages posted to a private channel
Retrieve a thread of messages posted to a private channel

Replaced by: conversations.replies 

groups.setPurpose
Sets the purpose for a private channel.
Sets the purpose for a private channel.

Replaced by: conversations.setPurpose 

groups.setTopic
Sets the topic for a private channel.
Sets the topic for a private channel.

Replaced by: conversations.setTopic 

groups.unarchive
Unarchives a private channel.
Unarchives a private channel.

Replaced by: conversations.unarchive 

im.close
Close a direct message channel.
Close a direct message channel.

Replaced by: conversations.close 

im.history
Fetches history of messages and events from direct message channel.
Fetches history of messages and events from direct message channel.

Replaced by: conversations.history 

im.list
Lists direct message channels for the calling user.
Lists direct message channels for the calling user.

Replaced by: conversations.list users.conversations 

im.mark
Sets the read cursor in a direct message channel.
Sets the read cursor in a direct message channel.

Replaced by: conversations.mark 

im.open
Opens a direct message channel.
Opens a direct message channel.

Replaced by: conversations.open 

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: conversations.replies 

mpim.close
Closes a multiparty direct message channel.
Closes a multiparty direct message channel.

Replaced by: conversations.close 

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: conversations.history 

mpim.list
Lists multiparty direct message channels for the calling user.
Lists multiparty direct message channels for the calling user.

Replaced by: conversations.list users.conversations 

mpim.mark
Sets the read cursor in a multiparty direct message channel.
Sets the read cursor in a multiparty direct message channel.

Replaced by: conversations.mark 

mpim.open
This method opens a multiparty direct message.
This method opens a multiparty direct message.

Replaced by: conversations.open 

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: conversations.replies 

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

Was this page helpful?