Slack Connect API methods

Slack Connect allows users between different workspaces and organizations to work together on Slack.

Slack Connect API methods offers capabilities for managing and automating your Slack Connect processes. Here's some of the ways these API methods can empower you:

✨ Invite users from external organizations to new channels and accept Slack Connect channel invitations when installed on the target workspace.

✨ Integrate Slack Connect management into your onboarding and offboarding processes. Automatically invite new partners and collaborators, or disconnect from those who are leaving.

✨ Schedule regular audits and maintenance tasks to keep your Slack Connect connections current and secure. Automate the disconnection of outdated or unnecessary connections.

Read on for more details and use cases.

Creating an app to interact with Slack Connect

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.

Managing your app's Slack Connect invitations

Your app can be invited to a Slack Connect Channel. Make sure it's notified when suitors call by subscribing to the proper event:

You can subscribe your app to the shared_channel_invite_received event within the Events API section of the App Management page.

Accept invitations

In order for your app to act upon the invite, it'll need to have the proper scopes:

  • conversations.connect:read β€” This scope allows your app to receive events when your app is invited to a Slack Connect channel.
  • conversations.connect:write β€” This scope allows your app to send and accept invitations to Slack Connect and receive events when invitations are accepted.

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. Provide the invitation ID from the shared_channel_invite_received event response.

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.

Inviting users to Slack Connect channels

Your app can invite users from external organizations to a channel, turning the channel into a Slack Connect channel in the process.

It'll need the proper scope:

  • conversations.connect:write β€” This scope allows your app to send and accept invitations to Slack Connect and receive events when invitations are accepted.

Then use the conversations.inviteShared method 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.

Many workspaces require approval by an Admin for Slack Connect channels (in addition to a user accepting an invitation). Alternatively, you can manage approval of the channel invitations.

Managing workspace invitations

Since many workspaces require Admin 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.

Subscribe to the following events to stay on top of workspace invitations:

In order for your app to act upon the the invitations, it'll need to have the proper scope:

  • conversations.connect:manage β€” This scope allows your app 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.

Approve invitations

With a user token and the conversations.connect:manage scope, your app can call the conversations.approveSharedInvite method to approve a pending invitation. Provide the invitation ID from the shared_channel_invite_accepted event response.

You can approve from the perspective of the originating organization or the target organization, depending on where your app is installed.

Decline invitations

You can also decline pending invitations with the conversations.declineSharedInvite method. Provide the invitation ID from the shared_channel_invite_accepted event response.

List invitations

To list all the pending invitations that you can act on, use the conversations.listConnectInvites method. 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.

Viewing connected organizations and users

You can use Slack Connect API methods to find information on connected organizations and users. The relevant methods will require a Slack Connect specific scope: the conversations.connect:manage scope.

To view details about external teams connected via Slack Connect, use the team.externalTeams.list method.

To look up if a specific user is on Slack (and is also discoverable), use the users.discoverableContacts.lookup method.

Setting Slack Connect channels posting permissions

Slack Connect channels have two types of posting permissions:

  • Permission only to post
  • Permission to post, invite, and more

You can pick the permission level using the conversations.externalInvitePermissions.set method. Be sure to provide your app the conversations.connect:manage scope.

Disconnecting a Slack Connect channel

Your app can disconnect Slack Connect channels. It'll need the proper Admin scope:

  • admin.conversations:write β€” This scopes allows your app to start new conversations, modify conversations and modify channel details.

Then use the admin.conversations.disconnectShared method to disconnect the Slack Connect channel.

Disconnect all Slack Connect channels from another organization

To sever all ties with another organization, you can disconnect all Slack Connect channels and direct messages (DMs) from that organization.

You'll need the proper write scopes for all relevant message types, alongside the conversations.connect:manage scope.

Then use the team.externalTeams.disconnect method and say goodbye.

Gone, but not forgotten
Disconnecting from an organization ends all communication, but depending on permissions, still allows access to conversation history. Refer to this help center article for the expected behavior of disconnecting conversations.