Migration Guide for web‐api v7

This migration guide helps you transition an application written using the v6.x series of the @slack/web-api package to the v7.x series. This guide focuses specifically on the breaking changes to help get your existing app up and running as quickly as possible.

@slack/web-api v7 Changes

This release focusses on the type safety of Slack HTTP API method arguments provided by @slack/web-api. If you use this package in a TypeScript project, many of the HTTP API methods now have stricter argument typing, which hopefully helps guide developers towards proper argument usage for Slack's HTTP API methods.

If you use this package in a JavaScript project, no such guidance is provided and the breaking changes listed below do not apply to you.

This release broadly is composed of three significant changes to the web-api codebase:

1. 🚨 Breaking changes to API method arguments for TypeScript users (not for JavaScript users),
2. 📝 Adding a ton of new hand-written JSDocs to provide useful method-specific context and descriptions directly in your IDE, and
3. 🧑‍🔬 Type tests for method arguments, formalizing some of the co-dependencies and constraints unique to specific API methods

Let's dive into these three sets of changes and begin with the 🚨 Breaking Changes 🚨 to make sure we set you all up for success and an easy migration to v7.

🚨 Breaking Changes (TypeScript users only) 🚨

🚨 All Web API methods no longer allow arbitrary arguments 🚨

Previously, the arguments provided to specific methods extended from a WebAPICallOptions TypeScript interface. This interface made all API arguments effectively type un-safe: you could place whatever properties you wanted on arguments, and the TypeScript compiler would be fine with it.

In v7, in an attempt to improve type safety, we have removed this argument. As a result, if you were using unknown or publicly undocumented API arguments, you will now see a TypeScript compiler error. If you really want to send unsupported arguments to our APIs, you will have to tell TypeScript "no, trust me, I really want to do this" using the // @ts-expect-error directive.

If you find an issue with any of our method arguments, please let us know by filing an issue in this project!

🚨 Many Web API methods have new, sometimes quite-specific, type constraints

Another change that only affects TypeScript projects. A full and detailed list of changes is at the end of this document, with migration steps where applicable.

📝 Adding JSDoc to methods and method arguments 📝

This one benefits both TypeScript and JavaScript users! Both API methods and API arguments are exhaustively documented with JSDoc. It includes the API method descriptions, mimicking the hand-written docs we have on https://api.slack.com/methods, as well as documenting each API argument and linking to relevant contextual documentation where applicable.

🧑‍🔬 Type tests for method arguments 🧑‍🔬

All of the above-mentioned new TypeScript API argument constraints are exhaustively tested under test/types/methods. When in doubt, read these tests to understand exactly what combination of arguments are expected to raise a TypeScript error, and which ones are not.

🚨 TypeScript API Argument Changes

Many of the API argument changes follow a similar pattern. Previously, API arguments would be modeled as a 'bag of optional arguments.' While this was a decent approach to at least surface what arguments were available, they did not model certain arguments well. In particular, API arguments that had either/or-style constraints (e.g. chat.postMessage accepts either channel and blocks or channel and attachments - but never all three) could not be modeled with this approach. This could lead developers to a situation where, at runtime, they would get error responses from Slack APIs when using a combination of arguments that were unsupported.

Moving forward, all of our APIs were exhaustively tested and the arguments to them modeled in such a way that would prevent TypeScript developers from using the APIs with an unsupported combination of arguments - ideally preventing ever encountering these avoidable runtime errors.

Without further ado, let's dive in the changes for each API:

admin.analytics.getFile

Previously, most arguments to this API were optional. Now, the specific combinations of type, date and metadata_only are more strictly typed to ensure only valid combinations are possible.

admin.apps.activities.list

• component_type is no longer any string, but rather it must be one of: events_api, workflows, functions, tables
• min_log_level is no longer any string, but rather it must be one of: trace, debug, info, warn, error, fatal
• sort_direction is no longer any string, but rather it must be one of: asc, desc
• source is no longer any string, but rather it must be one of: slack, developer

admin.apps.*

You can no longer provide both request_id and app_id - these APIs will only accept one of these arguments. Similarly for enterprise_id and team_id - only one can be provided, and one of them is required as well.

admin.auth.*

• entity_type is no longer any string and is now an enum that only accepts the only valid value: USER
• policy_name is no longer any string and is now an enum that only accepts the only valid value: email_password

admin.barriers.*

The restricted_subjects array is no longer a string[] but enforces an array with the exact values ['im', 'mpim', 'call'] - which these APIs demands (see e.g. admin.barriers.create usage info).

admin.conversations.*

• The channel_ids parameter now must be passed at least one channel ID - no more empty arrays allowed!
• Similarly, team_ids must be passed at least one team ID. Empty arrays: no good.
• This might sound familiar, but user_ids must be passed at least one user ID. Keeping it consistent around here, folks.
• The org_wide and team_id parameters influence one another: if org_wide is true, team_id must not be provided. Conversely, if team_id is provided, org_wide should be omitted, or, if you really want to include it, it must be false. Previously, both properties were simply optional.

admin.conversations.search

The search_channel_types argument is now an enumeration of specific values, rather than just any old string you want.

admin.functions.*

• function_ids now requires at least one array element.
• visibility is no longer any string and instead an enumeration: everyone, app_collaborators, named_entities, no_one.

admin.roles.*

• entity_ids now requires at least one array element.
• user_ids must be passed at least one user ID.
• sort_dir will accept either asc or desc. Previously any string was, unfortunately, A-OK.

admin.teams.*

• team_discoverability and discoverability are now enumerations consisting of: open, closed, invite_only, unlisted, rather than any string.
• channel_ids must be passed at least one channel ID.