Supporting and developing apps in Enterprise Grid

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

Read on if you are:

  • developing Slack apps for your own Enterprise Grid workspace
  • developing Slack apps for other Enterprise Grid workspaces to collaborate with
  • readying Enterprise Grid support for tools, libraries, or frameworks

The best thing you can do is use the method to update all records you have for an existing workspace with those from an Enterprise Grid. Then you won't need to worry about a "translation layer" or maintaining two IDs for a single user.

Identifying Enterprise Grid workspaces

Workspaces don't always start out part of an Enterprise. Thanks to mergers, acquisitions, and the inherent nature of life, a workspace may become part of an Enterprise Grid.

One single user may have an identity in Workspace A, and another in Workspace B. With Enterprise Grid, you can reconcile those identities and make that user a cross-referenced entity identifiable across multiple workspaces.

Look for enterprise IDs

If your app is in a workspace that's part of an Enterprise Grid organization, you will observe a constant and unique enterprise_id attribute through API methods and events. Below are notable methods:

If you store data, you'll want to warehouse the enterprise_id value. Just as you'd never store information about a user or their data without tying it to a workspace first, it's best to associate Enterprise Grid workspace data with its enterprise_id.

If your app is installed on multiple workspaces within an Enterprise Grid organization, you may want to utilize that position effectively by grouping data by enterprise_id value and using the new enterprise_ID values as your primary source of truth.

Support Strategies for Enterprise Grid

Some platform features require additional support in Enterprise Grid workspaces.

Slack apps require you to:

  • Support global user IDs.
  • Support users from other workspaces within the same Enterprise Grid using your application features.

The Events API requires you to:

The Web API requires you to:

Slash commands require you to:

  • Toggle on Escape channels, users, and links sent to your app for all Slash commands within the Slash Commands app management page. This will allow you to identify channels and users by ID. See the Slash commands guide for more info.
  • Support user ID fields containing global user IDs
  • Be aware that Slash commands can only be invoked by users belonging to the workspace it is installed in.

Legacy integrations

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

Legacy custom integrations have few programmatic signals to interpret and off-the-shelf code may not know how to handle certain situations like shared channels.

Legacy message buttons require you to support user ID fields containing global user IDs and to support action invocations by users from other workspaces.

Legacy RTM API usage will require additional effort to prevent duplicative messages and other undesired behaviors. See Using the RTM API on Enterprise Grid for more detail.

Handling unknown users gracefully

If your app or integration is used as part of a shared channel, it will encounter users it is not aware of.

The users.list method won't return users from other workspaces in its payload.

To find users from another workspace on an Enterprise Grid, use the method and query by their "foreign" user ID.

Many apps need only a user's ID and don't need additional information to operate.

Messages, interactions, & slash command invocations involving unknown users

Not only will you encounter user IDs belonging to other workspaces, but also the artifacts of their existence and workspace cross-pollination:

Messages will be authored by these users, and if they fall within your app's functionality, you should respond as you normally would. Messages may also mention users on other workspaces.

If your messages contain interactive elements, you may receive invoked actions from these users, and should handle them just as you would a "native" workspace user.

If you provide a slash command, you'll want to handle mentions of members from other workspace's. We strongly recommend turning on entity resolution so you can resolve mentioned users.

The Events API

If you're using the Events API, you do not have to worry about duplicate messages from shared channels. We'll only send one event regardless of how many workspaces within the organization your app is installed on.

Look for the authed_teams node that arrives as part of the "wrapper" around delivered events. It contains a collection of team IDs within an organization that this delivery is on behalf of.

Here's an example payload of a shared channel's message being delivered on behalf of multiple workspaces:

    "token": "ecto1EZslimer",
    "team_id": "T111AAA111",
    "api_app_id": "A123ABC456",
    "event": {
        "type": "message",
        "user": "W123ABC456",
        "text": "It's time to slacktivate!",
        "team": "T111AAA111",
        "source_team": "T111AAA111",
        "user_team": "T111AAA111",
        "user_profile": {
            "avatar_hash": "g56821b98743",
            "image_72": "https://...png",
            "first_name": "Jesse",
            "real_name": "Jesse Slacksalot",
            "name": "jesse.slacksalot"
        "ts": "1485371714.000002",
        "channel": "C123ABC456",
        "event_ts": "1485371714.000002"
    "type": "event_callback",
    "authed_users": [
    "authed_teams": [

In this example, the application is installed on two workspaces on an Enterprise Grid and is party to a conversation in a shared channel.

The message originates from team T111AAA111 and is delivered as a single event for both teams, including T222BBB222.

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, 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. When encountering errors, practice an exponential backoff strategy 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 Enterprise 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 the method to receive global user IDs for any of your stored local user IDs.

User object changes

User objects on Enterprise Grid workspaces now have an enterprise_user attribute, containing fields with additional context about the user in the larger Enterprise Grid organization:

enterprise_user fields Description
id The 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 Grid.
is_owner A boolean value indicating whether this user is the owner of this enterprise organization.
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 a single, global ID beginning with either the letter U or W. The specific prefix does not indicate anything in particular.

Slack will automatically convert users' pre-Enterprise-migration ID references to their singular Enterprise ID. This allows your app to remain backwards compatible for users identified on a workspace before the days of Enterprise Grid.

Users created after a workspace became part of an Enterprise have no pre-Enterprise-migration ID.

Toggling the translation layer

Slack Apps can turn on a translation layer in their app settings that will display "local" historical user IDs beginning with U for users that existing prior to an Enterprise Grid migration for a workspace the app was already installed on. It also lets you use these classic user IDs within a migrated workspace. It's meant to be used for a short while.

We strongly recommend you turn this translation layer off after using and going all-in with global user IDs, regardless of which letter they start with.

Disable the translation layer by navigating to application management for your app and finding the User ID Translation panel.

If you need to update local user IDs you've stored in a database or in other ways, first use the method with the relevant user or bot tokens to receive global user IDs in bulk.

Building internal integrations

As with all Slack apps, installation and ownership of apps is on a workspace-basis. Apps that are locked to a single workspace cannot be installed across an Enterprise Grid.

App directory considerations

If your app is part of the directory, you'll want to let us know that you've prepared for Enterprise Grid workspaces. We'll do some additional testing and give you feedback on anything that could be improved.

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 an Enterprise 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