Conversations API

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.

Using the Conversations API

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.

Conversations API methods

Method & DescriptionDescription
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.

Working with Shared Channels

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.

The conversational booleans

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.

Conversation membership

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.

Permission scopes

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.

Scopes for classic apps

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.

Scopes for workspace apps (deprecated)

Workspace apps were retired in August 2021.

Pagination

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.

Inconsistent page size is a feature, not a bug

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.

Known issues

🚧 Channel IDs can become unstable in certain situations

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.

🚧 MPIM events and channel types

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 object format is not yet consistent

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!

🚧 Unsharing channels

When a channel becomes unshared, conversations.history access for the channel may become unreliable.