For the most part, APIs at Slack work the same with all apps—whether with an app that's deployed to an entire Enterprise organization or a single-workspace app.
There are three things to keep in mind:
team_id
when called by an org-wide app. That's because your org-wide app has access to many workspaces, and you now need to specify which workspace a method should act on.authorizations
that they apply to, with a special is_enterprise_install
boolean field to indicate that the event is being sent to an org-wide installation.Read on for more detail on each of the above changes to calling APIs with your org-wide app.
team_id
Since your app's token now can represent installations in many workspaces, some API methods will require a team_id
to indicate which workspace to act on. You may have certain installations of your app that are on a single workspace, while other installations are deployed across entire organizations. In this case, a shortcut is to always pass team_id
to these methods. Even if your token is a single-workspace installation, the extra parameter will be accepted.
The team_id
is only relevant when using an org-level token. This field will be ignored if the API call is sent using a workspace-level token.
Here's the full list of methods that require team_id
when used by an org-wide app:
The updated Events API includes authorizations
inside the event payload on most events.
authorizations
tells you which installation the event applies to. You can find more detail on the updated Events API here.
Here's a sample payload:
{
"token": "XXYYZZ",
"is_ext_shared_channel": false,
"team_id": "TXXXXXXXX",
"api_app_id": "AXXXXXXXXX",
"event": {...},
"type": "event_callback",
"event_id": "EvXXXXXXXX",
"event_time": 1234567890,
"authorizations": [
{
"enterprise_id": "E324567",
"team_id": "T423567",
"user_id": "W43567",
"is_bot": false,
"is_enterprise_install": true
}
]
}
One note: authorizations
is truncated at a single installation, so if your app is installed multiple ways and you're not sure which installs have the ability to see the event, call the apps.event.authorizations.list
method to get a full list of installations.
You'll also see a relatively new field inside authorizations
: that's is_enterprise_install
, a boolean that tells you whether the event is being sent to an org-wide installation of your app.
With new power comes new abilities: apps deployed across entire orgs have access to a few new events and methods.
Two events indicate to you when your org-wide app has gained or lost access to a new workspace within your org. Those are the team_access_granted
and team_access_revoked
methods.
Subscribe to these events as with any other part of the Events API. That way, you'll always have an up-to-date list of workspaces to monitor and act in.
In addition, there's a handy new method to obtain a full list of workspaces your org-wide app has been approved for: the auth.teams.list
method. Call it with your token (from installing your app on an Enterprise org) to see all the workspaces within that org you've got access to.