The Slack developer docs are moving! We've been working hard at building out a new docs experience at docs.slack.dev — now in beta! You can start using the new docs today, but we'll keep the content on both sites up to date during the transition.

Building apps in Enterprise Grid

Enterprise Grid is a network of two or more Slack workspace instances. Each Slack workspace has its own ID, directory of members, channels, conversations, files, and zeitgeist. For the most part, each workspace behaves and functions as you're used to.

The biggest change for your app to handle is that some channels and conversations can be shared between multiple workspaces within the same Enterprise organization.

As with typical Slack workspaces, workspaces on an Enterprise Grid have their very own application installations.

Enterprise Grid glossary

This guide may be your first introduction to the following terms:

Enterprise organization - An entity introduced with Enterprise Grid to house multiple Slack workspaces. When a customer is using Enterprise Grid, all users and their direct messages are stored at the organization level.
Enterprise organization user - An Enterprise Grid user. They have the same identity and profile across all workspaces within an organization.
Enterprise user ID - A user ID beginning with U or W representing a user across all workspaces within an Enterprise Grid.
Legacy user ID - Also known as a "team user ID", these are the User IDs you've come to know and love in Slack if you've only developed for non-grid workspaces before. They begin with U. Also known as a local user ID.
Shared channel - A channel shared between two or more workspaces within an organization.
Translation layer - A translating service that transparently converts new organization-based user IDs to legacy team user IDs, allowing apps to migrate data.
Workspace - Where a team works. The terms workspace and team are often used interchangeably. When you see the object name such as team_id, it means the ID for a workspace.

Shared channels

A shared channel is a bridge between teams needing to work together. Instead of endless email threads or sidecar Slack workspaces, teams can use shared channels to connect, chat, share files, and use apps in the same way they communicate with their more immediate colleagues.

Life before shared channels

Maybe you're just learning about shared channels or maybe it's years from when this documentation was written. Hello, time traveler. In either case, let's rewind to life before shared channels to understand how they can make your working life simpler and more productive:

Before shared channels. With cats and dogs.

Before, when messaging was more limited, what our feline friends were saying and doing on the project that impacted these playful pups was a mystery. When the two teams tried to communicate it was disconnected, disparate, and duplicative.

This is now solved with shared channels. Now the project channel #projectM exists in each team's workspace (Catnip Inc. and Woof Inc., respectively).

After shared channels. With cats and dogs.

To learn even more about how shared channels work, check out our resources on Apps for shared channels.

Types of shared channels

There are two types of shared channels, each with different uses:

Slack Connect channels allow up to 20 organizations to come together in a single channel (e.g. Catnip, Inc. and Woof Inc. from the examples above).
Multi-workspace shared channels are shared between multiple workspaces within the same organization's Slack instance. For example, the #treats channel is shared in Woof Inc's, Marketing, Engineering, and Social workspaces. It exists in all three places, within Woof Inc.'s single Enterprise Grid instance.

Preparing distributed apps for Enterprise Grid

There are a few ways an app can be installed within an Enterprise Grid organization.

An app can be installed on a workspace within an organization. This type of installation is only available for a Slack app that does not contain a custom function intended for use in Workflow Builder (the only option for this case would be organization-wide installation). Similarly, workflow automations cannot be installed in this way.
An app can be org-ready and granted access for some or all of the workspaces in that organization. This is the only installation option compatible with custom functions intended for use in Workflow Builder.
An app can be installed at an organization level. This is a specific type of app, usually an admin or data loss prevention (DLP) app.

If your app is installed by one or more Enterprise Grid workspaces, or a workspace you're already installed on becomes part of an enterprise organization's workspace (number 1 above):

Your app might not know what to do with messages and users originating from enterprise shared channels.
Your app may have trouble dealing with object IDs beginning with atypical characters, like user IDs starting with W.
Your bot could blindly reply multiple times to messages, not recognizing a unique message delivery scenario introduced by shared channels.
Workspaces on Enterprise Grid are often large and some API responses, like channel memberships, can grow immense. Your app might need to change how it digests information.

You never know when a workspace on Enterprise Grid will install your app. Without making a few tweaks, your new users may notice these (and other) quirks in your app's behavior. These issues can be rectified by preparing your app for Enterprise Grid.

Next steps

➡️ Looking to develop apps for an enterprise grid workspace?

➡️ Looking to distribute your app across an Enterprise Grid or are you distributing a Slack app with custom functions for use in Workflow Builder?

✨ Read more on Organization-ready apps.