Go to Slack

Building apps in Enterprise Grid

The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read next: Enterprise Migration

New to building on Slack? We're happy you're here. The first step is to create an app — it'll only take a moment. Get started.

Slack Enterprise Grid allows large organizations to collaborate across many workspaces. While many apps, integrations, and bots will work as expected on Enterprise, there are enough new behaviors, conditions, nuances, and opportunity to warrant reviewing your app for full compatibility.

An Enterprise organization

What is Enterprise Grid?

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

The biggest delta for your app, integration, bot, or mind 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.

Why prepare my app for Enterprise Grid?

First things first: if you're used to calling a team's usage of Slack itself a "team" or a "Slack team", we now refer to them as workspaces. Workspaces are where work happens both in and outside of Enterprise Grid.

If your app or integration is never installed on an enterprise organization's workspace, you won't encounter any of the particularities detailed in this document.

However, if you have the good fortune to be installed by one or more Enterprise Grid workspaces, or a workspace you're already installed on becomes part of an enterprise organization's workspace:

🙃 Your app might not know what to do with messages and users originating from shared channels. It's novel.

🗿 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.

Enterprise Grid glossary

Though for the most part Enterprise Grid Slack workspaces are business as usual, there are enough new concepts introduced to warrant brief review:

  • 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 - A Enterprise Grid user. They have the same identity and profile across all workspaces within an organization.
  • Enterprise user ID - A user ID beginning with W that represents a user across one or more workspaces within an Enterprise.
  • Legacy user ID - Also known as a "team user ID", these are the User IDs you've come to know and love in Slack and are unique only to a workspace. They begin with U.
  • 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.

Surface area

Working with Enterprise Grid means that no matter what your app does or which APIs it uses, it's more likely to encounter an enterprise-related quirk.

Bot users are more likely than other integration points to require additional work for exemplary performance on Enterprise Grid workspaces.

We recommend reviewing your app's current assumptions, operations, and configuration. Maybe even if you aren't planning to work with Enterprise Grid.

Read on if:

  • you are building Slack apps for your own Enterprise Grid workspace
  • you're building Slack apps for other Enterprise Grid workspaces to collaborate with
  • you're readying Enterprise Grid support for tools, libraries, or frameworks

Really, if you're using any aspect of the platform at all and want to support Enterprise Grid — this guide is for you.

Supporting Enterprise Grid in your apps

Here's one way of looking at the kind of work involved in supporting Enterprise Grid workspaces.

"If there's a steady paycheck in it, I'll believe anything you say."

API Support strategies
All Slack apps
  • Support global user IDs
  • Support users from other workspaces within the same Enterprise Grid using your application features
RTM
  • Support events & messages containing global user IDs
  • Support users from other workspaces in shared channels
  • Support duplicate message deliveries in shared channels when installed on multiple workspaces
  • Connect using rtm.connect instead of rtm.start
Events API
  • Support events & messages containing global user IDs
  • Support users from other workspaces in shared channels
Web API
  • Support user ID fields containing global user IDs
  • Support users from other workspaces in shared channels
  • Use users.info to retrieve additional information on cross-workspace user IDs not found in users.list
Incoming webhooks
  • When using webhooks exclusively, no special Enterprise Grid considerations should be necessary.
Slash commands
  • Turn on entity resolution for mentioned users, allowing you to identify them by ID
  • Support user ID fields containing global user IDs
  • Slash commands are only invoked by users belonging to the workspace it is installed in
Interactive components
  • Handle action invocations by users from other workspaces
  • Support user ID fields containing global user IDs

Understanding 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 with the same cozy ease they use communicating 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, even 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.

External shared channels are channels that connect two separate teams (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.

A note on Enterprise Grid and your apps

Enterprise Grid functions a bit differently than you may be used to, especially where your app is involved. API responses may differ in Enterprise Grid workspaces, and your app will need logic to deal with things like semi-duplicate messages when it's installed on multiple workspaces within the same Enterprise Grid.

To walk through all the steps of supporting Enterprise Grid in your apps, check out this guide.

When workspaces migrate to Enterprise Grid

In most cases, an Enterprise Grid is formed by combining multiple independent Slack workspaces together. During this period of time where data is migrated and made compatible with Grid's organization structures, Web API calls, RTM API connections, Events API, and other platform interactions may be unavailable, both for users and your applications.

On the Web API, you may encounter the team_added_to_org error during this time.

Migration time varies depending team-to-team and organization-to-organization. Practice an exponential backoff strategy when encountering errors to help manage these periods by attempting connections at incrementally increasing rates: 1 second to 3 seconds to 10 seconds to 30 seconds to 1 minute, and so on.

To best plan for migrations, subscribe to grid-related app events as part of the Events API. Using these events, your app can pause and resume activity as appropriate.

If your app has disabled the translation layer, use migration.exchange to receive global user IDs for any of your stored local user IDs.

User object changes

You'll find user objects on Enterprise Grid workspaces now have an enterprise_user attribute, containing a hash of additional context about the user in the larger Enterprise Grid organization.

You'll find:

  • id - this user's ID, which might start with U or W
  • enterprise_id - the unique ID for this particular Enterprise Grid organization
  • enterprise_name - the name of this umbrella organization
  • is_admin - a boolean value indicating whether this user administers this Enterprise
  • is_owner - a boolean value indicating whether this user is the owner of this Enterprise
  • teams - an array of team (workspace) IDs within the containing enterprise organization that this user belongs to

User IDs

Within an Enterprise Grid, all users have an underlying cross-workspace ID beginning with the letter W. If a workspace existed before the workspace became part of an Enterprise Grid, users created before that transition also have a more local team-specific ID beginning with U.

We'll automatically convert references to a user's Enterprise ID to their legacy team-specific ID. This allows your app to remain backwards compatible for users you've identified on a workspace before the days of Enterprise Grid.

You'll still encounter users with IDs beginning with W: these users were created after a workspace became part of an Enterprise and have no legacy ID.

Building single-workspace apps

It's easy and secure to build Slack apps for your workspaces only. As with all Slack apps, installation and ownership of apps is on a workspace-basis. Single-workspace apps, as their name implies, are locked to a single workspace and cannot be installed across an Enterprise Grid.

Find out more in our single-workspace apps documentation.

Requesting a sandbox

Building properly for shared channels or enterprise grid requires experiencing the unique constraints and opportunities yourself.

If you don't already have access to a grid of workspaces, please complete the form below to request a sandbox. We'll get back to you as soon as possible.

Request a sandbox

To learn more about sandboxes and how to get started testing, click here.

Related reading

  • Announcement about user IDs - Back in August 2016, we announced that user IDs may sometimes begin with the letter W and that it vaguely had something to do with our upcoming enterprise product. W is here to stay.