Support for Agents & Assistants is now available!
Bolt now offers a simple and intuitive way to create an Agent/Assistant using the new Assistant class. Simply include the required callbacks and add the assistant to your App instance. Get up and running even quicker with a working, out-of-the-box example that utilizes OpenAI here.
We have prepared a migration guide to help BoltJS consumers migrate their Bolt v3 apps to v4.
While a few breaking changes were introduced, we don't expect a majority of bolt v3 users to require changing their apps to upgrade to v4. More complex apps may need a few tweaks. TL;DR is: if your bolt v3 app is built with TypeScript, or uses the ExpressReceiver or the AwsLambdaReceiver, or your app used previously-deprecated types or functions, best to read the migration guide.
In bolt we have a set of Slack*MiddlewareArgs types: for events, shortcuts, commands, and so on. They 'wrap' the underlying event payloads with additional middleware-relevant bits like a next() method, a context object for devs to augment, and so on.
Many of these types, for example the SlackEventMiddlewareArgs type, previously used a conditional to sometimes define particular additional helper utilities on the middleware arguments. For example, the say utility, or tacking on a convenience message property for message-event-related payloads. This was problematic in practice in TypeScript situations, not just internally (this change fixes https://github.com/slackapi/bolt-js/issues/2135) within the bolt codebase but for developers as well: when the payload was not of a type that required the extra utility, these properties would be required to exist on the middleware arguments but have a value of undefined. Those of us trying to build generic middleware utilities would have to deal with TS compilation errors and needing to liberally type-cast to avoid these conditional mismatches with undefined.
Instead, these MiddlewareArgs types now conditionally create a type intersection when appropriate in order to provide this conditional-utility-extension mechanism. In practice that looks something like:
type SomeMiddlewareArgs<EventType extends string = string> = {
// some type in here
} & (EventType extends 'message'
// If this is a message event, add a `message` property
? { message: EventFromType<EventType> }
: unknown
)With the above, now when a message payload is wrapped up into middleware arguments, it will contain an appropriate message property, whereas a non-message payload will be intersected with unknown - effectively a type "noop." No more e.g. say: undefined or message: undefined to deal with!
express to v4->v5; ExpressReceiver users will be exposed to express v4 -> v5 breaking changes - fixes #2242@slack/socket-mode v2; SocketModeReceiver users who have attached custom event listeners to the public socketModeClient directly should read the v1 -> v2 migration guide in case the major upgrade could affect them - fixes #2225@slack/web-api v7; all users should read the web-api v6->v7 migration guide to see what the scope of breaking changes the client within listeners is affected byKnownKeys@slack/types now exist under a named export types.SocketModeFunctions class that had a single static method on it and instead directly exposed the defaultProcessEventErrorHandler method from it.ignoreSelf and directMention now no longer must be invoked as a method in order to return middleware; instead they are middleware to be used directly. this lines up the API for these built-in middlewares to match the other builtins.AwsEvent interface now models event payloads a bit differently; we now properly model AWS API Gateway v1 and v2 payloads separately - fixes #2272OptionsRequest interfaceauthed_users and authed_teams from event payload enveloperender-html-for-install-path moduleverify and VerifyOptions from the verify-request modulesrc/receivers/http-utils.ts module@slack/web-api dependency under the webApi named exportAwsLambdaReceiver where apps with no registered handlers that processed an incoming event would still log out an error related to not acknowledging the request in time - fixes #2284raw-body to v3@slack/oauth to v3promise.allsettled since that is natively supported in node since v14@types/tsscmp to dev dependencies since that is not exposed to developers@slack/bolt@v4.0.0 by @filmaj in https://github.com/slackapi/bolt-js/pull/2294Full Changelog: https://github.com/slackapi/bolt-js/compare/@slack/bolt@3.22.0...@slack/bolt@4.0.0
Fetched April 3, 2026