How to support Slack Enterprise Grid

So, you’ve built a Slack app or you’re thinking of building one? Fantastic! You might be wondering about how best to support our Enterprise-grade product, Slack Enterprise Grid. This is your guide on what to expect from our APIs when your app is installed on an instance of Enterprise Grid, or migrated to one.

Generally, Slack Enterprise Grid workspaces tend to be much larger and generate more events than a regular Slack workspace. As a result, Slack will send back larger responses to long list methods like conversations.members or conversations.list. Before you get started, please be sure you’ve implemented the correct pagination standards according to the methods your app uses to accommodate for this.

When your app is freshly installed on an existing Enterprise Grid instance…

You’ll start receiving a few new fields in some of our API responses. Below are explanations of what they are, and some best practices to follow when it comes to tracking these new details.

Enterprise Grid relevant API metadata

• Track users using their Grid user ID, this comes in the standard ID field but is prefixed with a W. To receive W IDs, ensure your app’s translation layer is turned off.
• Store enterprise_id with as much of the Slack data you’re consuming as possible.
• You’ll receive enterprise_id from several methods like auth.test, channels.info,team.info. Map workspaces to their enterprise_id to understand which workspaces relate to each other.
• Poll auth.test regularly for all workspaces you service, especially as workspaces migrate to Enterprise Grid.

Supporting Shared Channels and DMs

In Events API payloads, rely on source_team and authed_teams to understand where the activity is coming from, and which token(s) your app can use to respond.

When in a Shared Channel or DM, your app will receive duplicate message events via RTM.

For example, if your bot is installed on 3 workspaces on a Grid and is invited to a shared channel with members from all 3 workspaces, you’ll receive each message three times, once for each workspace. Your bot should only respond to one of the message deliveries.

You can take one of two approaches to de-duplicating these events:

1. De-duplicate these messages by comparing their message ts (timestamps) and recognizing duplicates.
2. Make one of the workspaces in the shared channel responsible for handling all messages coming from that shared channel. To do this, you’ll need to listen to the member_joined_channel event when your bot is added to a shared channel. The metadata included in this event will tell you which workspaces are part of the shared channel.

Handling foreign users

Your app may be installed on one or two workspaces inside a Grid instance that have a shared channel. It is wise to handle the case where your app comes across a foreign user ID or “stranger”. Look this user up using users.info method to understand what workspace they belong to.

If the user doesn’t belong to the workspace your app is installed on, they’ll still be able to interact with the app and even DM it. For interactive elements (buttons, menus, message actions), respond as you would a “native” user.

If the user is trying to interact with the App in a DM or with an app_mention, please respond to the “stranger” user and let them know that your app can’t work with them because it’s not installed in their workspace.

It’s also a good idea to mention the workspace your app is installed on, and tell the user how and why they have access to your DM. *Please note* don’t mention the channel name if it’s a private channel).

Supporting migration events

Although your app may not be supporting Enterprise Grid migration events for this installation, it will need to recognize them in the future. Please see below for more information on how to support migrations to Slack Enterprise Grid.

In the case your app is already installed on a workspace that migrates to Enterprise Grid and brings you along with it…

All of the above applies, plus a bit about what to do in the event of a migration.

Handling migrations to Enterprise Grid

In most cases, an Enterprise Grid is formed by combining multiple independent Slack workspaces together.

When a regular Slack workspace migrates to Enterprise Grid, your app will receive a grid_migration_started event. It’ll also receive a grid_migration_finished event when the migration is complete.

You must add handling for these events to your app as 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. Pause all app activity for the workspace during a migration.

Once the migration is complete, take a look around the new environment and store how things are mapped now, especially the IDs mentioned above.

Migration time varies depending team-to-team and organization-to-organization. Practice an exponential back-off 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.

Slack before and after the migration

Differences in user ID: Before the migration, your app reads Slack user IDs prefixed with U, this is the user’s local user ID.

After the migration completes, and you receive the grid_migration_finished event, your user’s U-prefixed local user ID will turn into a W-prefixed Enterprise Grid user ID but only if your app has disabled the translation layer.

If your app’s translation layer is already disabled, your app will automatically start receiving W-prefixed user ID’s once the migration is complete. In this case, please map the old IDs to the new IDs using migration.exchange.

About enterprise_id

Before the migration your app tracks users and conversations in workspaces via team_id.

After the migration your app will start to receive enterprise_id from several methods like auth.test, channels.info, team.info. Map workspaces with a team_id to their enterprise_id to understand which workspaces relate to each other.

That’s it!Seems straightforward enough, right? To apply for a test instance of Slack Enterprise Grid, please fill out this form. If you have any further questions drop us a note at feedback@slack.com or on Twitter @SlackAPI.