Public channels, private channels, DMs... They're all conversations!
The Slack Conversations API provides you with a unified interface to work with all the channel-like things encountered in Slack: public channels, private channels, direct messages, group direct messages, shared channels, and so on.
The types of channels you interface with in the Conversations API are governed by corresponding permission scopes. For example; to retrieve details about a public channel, you'll need
channels:read. For details about a private channel, you'll need
Before the Conversations API, you needed to use different methods from multiple "family trees" to achieve the same thing depending on the type of channel you were working with.
For example, to list direct messages you had to call
im.list, but for public channels you had to call
channels.list. Many different objects and shapes represented the same type of timeline message container at their core. These older methods are now deprecated.
In the new model, just use
conversations to access anything channel-like. For example, the
conversation.list method returns information on public, private, and direct message channels, when accessed with the appropriate permission scopes.
|Method & Description||Description|
Accepts an invitation to a Slack Connect channel.
|Accepts an invitation to a Slack Connect channel.|
Approves an invitation to a Slack Connect channel
|Approves an invitation to a Slack Connect channel|
Archives a conversation.
|Archives a conversation.|
Closes a direct message or multi-person direct message.
|Closes a direct message or multi-person direct message.|
Initiates a public or private channel-based conversation
|Initiates a public or private channel-based conversation|
Declines a Slack Connect channel invite.
|Declines a Slack Connect channel invite.|
Fetches a conversation's history of messages and events.
|Fetches a conversation's history of messages and events.|
Retrieve information about a conversation.
|Retrieve information about a conversation.|
Invites users to a channel.
|Invites users to a channel.|
Sends an invitation to a Slack Connect channel
|Sends an invitation to a Slack Connect channel|
Joins an existing conversation.
|Joins an existing conversation.|
Removes a user from a conversation.
|Removes a user from a conversation.|
Leaves a conversation.
|Leaves a conversation.|
Lists all channels in a Slack team.
|Lists all channels in a Slack team.|
Lists shared channel invites that have been generated or received but have not been approved by all parties
|Lists shared channel invites that have been generated or received but have not been approved by all parties|
Sets the read cursor in a channel.
|Sets the read cursor in a channel.|
Retrieve members of a conversation.
|Retrieve members of a conversation.|
Opens or resumes a direct message or multi-person direct message.
|Opens or resumes a direct message or multi-person direct message.|
Renames a conversation.
|Renames a conversation.|
Retrieve a thread of messages posted to a conversation
|Retrieve a thread of messages posted to a conversation|
Sets the purpose for a conversation.
|Sets the purpose for a conversation.|
Sets the topic for a conversation.
|Sets the topic for a conversation.|
Reverses conversation archival.
|Reverses conversation archival.|
List conversations the calling user may access.
|List conversations the calling user may access.|
Each channel has a unique-to-the-team ID that begins with a single letter prefix: either
When a channel is shared across teams (see Slack Connect: working with channels between organizations), the prefix of the channel ID may be changed, e.g. a private channel with ID
G0987654321 may become ID
This is one reason you should use the
conversations methods instead of the previous API methods! You cannot rely on a private shared channel's unique ID remaining constant during its entire lifetime.
The channel type object tells you additional channel information. If the channel is shared,
is_shared is set to
true. If it is a private channel or a group DM channel, the properties
is_mpim are set to
Some of the most important fields in conversation objects are the booleans indicating what kind of conversation/channel it is and how private it is. For a list of these booleans, refer to conversation-related booleans.
Discover who is party to a conversation with
conversations.members, a paginated method allowing you to safely navigate through very large (or tiny) collections of users.
Your app's scopes act as a filter. They sort out the conversations you don't have access to, guaranteeing that Conversations API methods only return the conversations your app should see.
All Conversations API endpoints still accept multiple scopes and filter access to channels based on the provided token's scope. If you have a scope that allowed you to use a deprecated conversation method, that scope will work with the Conversations API equivalent.
If you only have
conversations.list will only return public channels and all the related methods will only deal with public channels. If you have both
im:read, then methods will only return public channels and DMs, and so on.
Workspace apps were retired in August 2021.
The Conversations API uses our cursor-based pagination model, improving the performance of requests over large sets of data.
Just set a
limit on your first request, include the
next_cursor found in
response_metadata in the response as the
cursor parameter in your next request and you're paginating with ease on the conversational trapeze. Unlike older methods, the Conversations API is paginated by default.
Keep in mind that it's possible to receive fewer results than your specified
limit, even when there are additional results to retrieve. Maybe you'll even receive 0 results but still have a
next_cursor with 4 more waiting in the wings.
When looking up MPIMs using the
conversations.list, you are likely to get far fewer results than requested number with a
next_cursor value, although
next_cursor will continue to indicate when more results await. For example, when requesting 100 MPIMs, it may return only 5.
There are a few circumstances where channel IDs might change within a workspace. You can use
conversations.list regularly to monitor change for known
#channel names if ID stability is important to you.
In the future, we'll mitigate this unexpected transition with appropriate Events API events or other solutions.
IM formats may differ from other channel objects. We're working towards making all objects the same format. You may notice
members lists that aren't meant to be there. These are almost all cleared up!
When a channel becomes unshared,
conversations.history access for the channel may become unreliable.