This guide covers using the Slack Connect APIs to manage Slack Connect for a workspace or organization.
If, instead, you'd like to understand how to work with Slack Connect as a Slack app that does other things, read our general guide to Slack Connect for Slack apps.
Otherwise, dive in!
Slack Connect allows users between different workspaces and organizations to work together on Slack.
Your app can help manage Slack Connect for a workspace or organization with the Slack Connect APIs. With the right authorizations, your app can:
If you don't already have a Slack app, you'll need to create one:
Fill out your App Name and select the Development Workspace where you'll play around and build your app. Don't fuss too much over either field—no matter what workspace you select, you'll still be able to distribute your app to other workspaces if you choose.
With an app created, it's time to obtain some scopes that represent the permissions you'll need for your app to manage Slack Connect.
Three scopes will help you on your journey:
conversations.connect:write. This scope allows your app, as a bot user, to send and accept invitations to Slack Connect and receive events when invitations are accepted.conversations.connect:read. This scope allows your app, as a bot user, to receive events when your app is invited to a Slack Connect channel.conversations.connect:manage. This scope allows your app, as a bot user, to approve, decline, or list Slack Connect invitations. Since approval requires more authority than accepting invitations, apps with this feature can only be installed by a workspace owner or admin.While you're setting up your app, scroll to the Events API sidebar and subscribe to events that tell you when Slack Connect invitations have been received, accepted, approved, or declined:
shared_channel_invite_received. This event notifies your app when you have an invitation that you're able to accept. This event will fire only if you use the conversations.inviteShared API call with the
user_ids argument to invite a bot or an app to a Slack Connect channel.shared_channel_invite_accepted. This event notifies your app when an invite sent by your workspace or organization has been accepted.shared_channel_invite_approved. This event notifies your app when an invitation has been approved.shared_channel_invite_declined. This event notifies your app when an invitation has been declined.Whew, that was a whirlwind! Good news: your app is now ready to take up the slack of managing Slack Connect for your organization.
First up, your app may now invite users from external organizations to a channel, turning the channel into a Slack Connect channel in the process. Use the conversations.inviteShared to invite users via email or via user ID.
If your app is already installed on the target organization, you can invite it directly and therefore automate both inviting and accepting invitations in order to connect two or more organizations.
Your app does not need to handle approval of Slack Connect in order to invite users. You can invite users and then wait for manual approval by Admins if that approval is necessary on your workspace or the target workspace.
If you followed through with the event portion of app setup, you'll be notified when there's an invitation to a Slack Connect channel for your app to accept.
Use the conversations.acceptSharedInvite method to accept an invite to a Slack Connect channel. You'll have the option to name the channel if the channel hasn't already been created yet by passing the channel_name parameter.
You'll be able to determine the ID of the invitation from the shared_channel_invite_received event.
For an expert-level move, you can also use the free_trial_accepted parameter to start a free trial for your workspace in order to use Slack Connect (as long as you're eligible.)
Many workspaces require approval by an Admin for Slack Connect channels (in addition to a user accepting an invitation). Read on to learn how to manage approval of the channel invitations that are sent and received by your app.
Since many workspaces require approval for the creation of Slack Connect channels, your app can manage that task, with the help of an installing user who grants your app a user token. If the installing user has the authority to manage Slack Connect approval, you're good to go—your app can make use of that authority in the user's stead.
With the correct scopes and access tokens, you'll be able to call conversations.approveSharedInvite to approve a pending invitation.
You'll know the ID of the invitation from the shared_channel_invite_accepted event.
You can approve from the perspective of the originating organization or the target organization, whereever your app is installed.
You can also decline pending invitations with conversations.declineSharedInvite.
If you want to list all the pending invitations that you can act on, use the conversations.listConnectInvites. If your app is installed at the organization level, you'll be able to list all the pending invitations in all workspaces, but you can also specify a particular channel.
Finally, with a token with Admin scopes, you may also disconnect a Slack Connect channel using the admin.conversations.disconnectShared method.
With all those tools in your toolbelt, you're ready to manage Slack Connect for your organization using the Slack Connect APIs.