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.
Use this API family to review history, create or archive channels, invite team members, set conversation topics and purpose, and more — no matter what type of conversation you're working with.
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 groups:read.
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 the im.list method, but for public channels you had to call the channels.list method. Many different objects and shapes represented the same type of timeline message container at their core. These methods are now deprecated.
In the new model, use conversations.* methods 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 |
|---|---|
| conversations.acceptSharedInvite Accepts an invitation to a Slack Connect channel. | Accepts an invitation to a Slack Connect channel. |
| conversations.approveSharedInvite Approves an invitation to a Slack Connect channel | Approves an invitation to a Slack Connect channel |
| conversations.archive Archives a conversation. | Archives a conversation. |
| conversations.canvases.create Create a channel canvas for a channel | Create a channel canvas for a channel |
| conversations.close Closes a direct message or multi-person direct message. | Closes a direct message or multi-person direct message. |
| conversations.create Initiates a public or private channel-based conversation | Initiates a public or private channel-based conversation |
| conversations.declineSharedInvite Declines a Slack Connect channel invite. | Declines a Slack Connect channel invite. |
| conversations.externalInvitePermissions.set Upgrade or downgrade Slack Connect channel permissions between 'can post only' and 'can post and invite'. | Upgrade or downgrade Slack Connect channel permissions between 'can post only' and 'can post and invite'. |
| conversations.history Fetches a conversation's history of messages and events. | Fetches a conversation's history of messages and events. |
| conversations.info Retrieve information about a conversation. | Retrieve information about a conversation. |
| conversations.invite Invites users to a channel. | Invites users to a channel. |
| conversations.inviteShared Sends an invitation to a Slack Connect channel | Sends an invitation to a Slack Connect channel |
| conversations.join Joins an existing conversation. | Joins an existing conversation. |
| conversations.kick Removes a user from a conversation. | Removes a user from a conversation. |
| conversations.leave Leaves a conversation. | Leaves a conversation. |
| conversations.list Lists all channels in a Slack team. | Lists all channels in a Slack team. |
| conversations.listConnectInvites 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 |
| conversations.mark Sets the read cursor in a channel. | Sets the read cursor in a channel. |
| conversations.members Retrieve members of a conversation. | Retrieve members of a conversation. |
| conversations.open Opens or resumes a direct message or multi-person direct message. | Opens or resumes a direct message or multi-person direct message. |
| conversations.rename Renames a conversation. | Renames a conversation. |
| conversations.replies Retrieve a thread of messages posted to a conversation | Retrieve a thread of messages posted to a conversation |
| conversations.requestSharedInvite.approve Approves a request to add an external user to a channel and sends them a Slack Connect invite | Approves a request to add an external user to a channel and sends them a Slack Connect invite |
| conversations.requestSharedInvite.deny Denies a request to invite an external user to a channel | Denies a request to invite an external user to a channel |
| conversations.requestSharedInvite.list Lists requests to add external users to channels with ability to filter. | Lists requests to add external users to channels with ability to filter. |
| conversations.setPurpose Sets the channel description. | Sets the channel description. |
| conversations.setTopic Sets the topic for a conversation. | Sets the topic for a conversation. |
| conversations.unarchive Reverses conversation archival. | Reverses conversation archival. |
| users.conversations 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 C, G, or D.
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 C0987654321.
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_private or is_mpim are set to true.
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.
For instance, conversations.list accepts channels:read, groups:read, mpim:read, and im:read.
If you only have channels:read, then conversations.list will only return public channels and all the related methods will only deal with public channels. If you have both channels:read and 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.
In a Multiparty Direct Message Channel (MPIM) with a foreign user, events like member_joined_channel and member_left_channel may dispatch an incorrect value for channel_type.
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.