Slack Connect APIs

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!

Overview

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:

  • Invite users from an external organization to a new channel on the host workspace, making the channel into a Slack Connect channel for the host organization in the process.
  • Accept Slack Connect channel invitations when your app's installed on the target workspace, making a Slack Connect channel in the target organization.
  • Approve or decline Slack Connect channel invitations once they've been made.
  • Disconnect a Slack Connect channel.

App setup

If you don't already have a Slack app, you'll need to create one:

Create a Slack app

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.

Scopes

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.

Events

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:

Whew, that was a whirlwind! Good news: your app is now ready to take up the slack of managing Slack Connect for your organization.


Invite users and make Slack Connect channels

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.


Accept invitations

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.


Approve and decline invitations

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.


Disconnect Slack Connect channels

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.