To listen to messages that your app has access to receive, you can use the message() method which filters out events that aren’t of type message.

message() accepts an optional pattern parameter of type string or RegExp object which filters out any messages that don’t match the pattern.

Within your listener function, say() is available whenever there is an associated conversation (for example, a conversation where the event or action which triggered the listener occurred). say() accepts a string to post simple messages and JSON payloads to send more complex messages. The message payload you pass in will be sent to the associated conversation.

In the case that you’d like to send a message outside of a listener or you want to do something more advanced (like handle specific errors), you can call chat.postMessage using the client attached to your Bolt instance.

You can listen to any Events API event using the event() method after subscribing to it in your app configuration. This allows your app to take action when something happens in Slack, like a user reacting to a message or joining a channel.

The event() method requires an eventType of type string.

You can call any Web API method using the WebClient provided to your app’s listeners as client. This uses either the token that initialized your app or the token that is returned from the authorize function for the incoming event. The built-in OAuth support handles the second case by default.

Your Bolt app also has a top-level app.client which you can manually pass the token parameter. If the incoming request is not authorized or you’re calling a method from outside of a listener, use the top-level app.client.

Calling one of the WebClient’s methods will return a Promise containing the response from Slack, regardless of whether you use the top-level or listener’s client.

Since the introduction of org wide app installations, some web-api methods now require team_id to indicate which workspace to act on. Bolt for JavaScript will attempt to infer the team_id based on incoming payloads and pass it along to client. This is handy for existing applications looking to add support for org wide installations and not spend time updating all of these web-api calls.

Your app can listen to user actions like button clicks, and menu selects, using the action method.

Actions can be filtered on an action_id of type string or RegExp object. action_ids act as unique identifiers for interactive components on the Slack platform.

You’ll notice in all action() examples, ack() is used. It is required to call the ack() function within an action listener to acknowledge that the request was received from Slack. This is discussed in the acknowledging requests section.

Note: Since v2, message shortcuts (previously message actions) now use the shortcut() method instead of the action() method. View the migration guide for V2 to learn about the changes.

Learn more about the block_actions payload, here. To access the full payload of a view from within a listener, reference the body argument within your callback function.

There are two main ways to respond to actions. The first (and most common) way is to use the say function. The say function sends a message back to the conversation where the incoming request took place.

The second way to respond to actions is using respond(), which is a simple utility to use the response_url associated with an action.

Actions, commands, and options requests must always be acknowledged using the ack() function. This lets Slack know that the request was received and updates the Slack user interface accordingly. Depending on the type of request, your acknowledgement may be different. For example, when acknowledging a modal submission you will call ack() with validation errors if the submission contains errors, or with no parameters if the submission is valid.

We recommend calling ack() right away before sending a new message or fetching information from your database since you only have 3 seconds to respond.

The shortcut() method supports both global shortcuts and message shortcuts.

Shortcuts are invokable entry points to apps. Global shortcuts are available from within search in Slack. Message shortcuts are available in the context menus of messages. Your app can use the shortcut() method to listen to incoming shortcut requests. The method requires a callback_id parameter of type string or RegExp.

⚠️ Note that if you use shortcut() multiple times with overlapping RegExp matches, all matching listeners will run. Design your regular expressions to avoid this possibility.

Shortcuts must be acknowledged with ack() to inform Slack that your app has received the request.

Shortcuts include a trigger_id which an app can use to open a modal that confirms the action the user is taking.

When configuring shortcuts within your app configuration, you’ll continue to append /slack/events to your request URL.

⚠️ Note that global shortcuts do not include a channel ID. If your app needs access to a channel ID, you may use a conversations_select element within a modal. Message shortcuts do include channel ID.

Your app can use the command() method to listen to incoming slash command requests. The method requires a commandName of type string or RegExp.

⚠️ Note that if you use command() multiple times with overlapping RegExp matches, all matching listeners will run. Design your regular expressions to avoid this possibility.

Commands must be acknowledged with ack() to inform Slack your app has received the request.

There are two ways to respond to slash commands. The first way is to use say(), which accepts a string or JSON payload. The second is respond() which is a utility for the response_url. These are explained in more depth in the responding to actions section.

When configuring commands within your app configuration, you’ll continue to append /slack/events to your request URL.

Modals are focused surfaces that allow you to collect user data and display dynamic information. You can open a modal by passing a valid trigger_id and a view payload to the built-in client’s views.open method.

Your app receives trigger_ids in payloads sent to your Request URL triggered user invocation like a slash command, button press, or interaction with a select menu.

Read more about modal composition in the API documentation.

Modals contain a stack of views. When you call views.open, you add the root view to the modal. After the initial call, you can dynamically update a view by calling views.update, or stack a new view on top of the root view by calling views.push.

views.update
To update a view, you can use the built-in client to call views.update with the view_id that was generated when you opened the view, and a new view including the updated blocks array. If you’re updating the view when a user interacts with an element inside of an existing view, the view_id will be available in the body of the request.

views.push
To push a new view onto the view stack, you can use the built-in client to call views.push with a valid trigger_id a new view payload. The arguments for views.push is the same as opening modals. After you open a modal, you may only push two additional views onto the view stack.

Learn more about updating and pushing views in our API documentation.

You may listen for user interactions with views using the view method.

Slack will send a view_submission request when a user submits a view. To receive the values submitted in view input blocks, you can access the state object. state contains a values object that uses the block_id and unique action_id to store the input values. If the notify_on_close field of a view has been set to true, Slack will also send a view_closed request if a user clicks the close button. See the section on Handling views on close for more detail. To listen to either a view_submission request or view_closed request, you can use the built-in view() method.

view() requires a callback_id of type string or RegExp or a constraint object with properties type and callback_id.

Update views on submission

To update a view in response to a view_submission request, you may pass a response_action of type update with a newly composed view to display in your acknowledgement.

// Update the view on submission 
app.view('modal-callback-id', async ({ ack, body }) => {
  await ack({
    response_action: 'update',
    view: buildNewModalView(body),
  });
});

Similarly, there are options for displaying errors in response to view submissions.

Read more about view submissions in our API documentation.

Handling views on close

💡 When listening for view_closed requests, you must pass an object containing type: 'view_closed' and the view callback_id. See below for an example of this:

See the API documentation for more information about view_closed.

// Handle a view_closed request
app.view({ callback_id: 'view_b', type: 'view_closed' }, async ({ ack, body, view, client }) => {
  // Acknowledge the view_closed request
  await ack();
  // react on close request
});

Home tabs are customizable surfaces accessible via the sidebar and search that allow apps to display views on a per-user basis. After enabling App Home within your app configuration, home tabs can be published and updated by passing a user_id and view payload to the views.publish method.

You can subscribe to the app_home_opened event to listen for when users open your App Home.

The options() method listens for incoming option request payloads from Slack. Similar to action(), an action_id or constraints object is required.

While it’s recommended to use action_id for external_select menus, dialogs do not yet support Block Kit so you’ll have to use the constraints object to filter on a callback_id.

To respond to options requests, you’ll need to ack() with valid options. Both external select response examples and dialog response examples can be found on our API site.

To prepare your Slack app for distribution, you will need to enable Bolt OAuth and store installation information securely. Bolt supports OAuth and will handle the rest of the work; this includes setting up OAuth routes, state verification, and passing your app an installation object which you must store.

To enable OAuth, you must provide:

• clientId, clientSecret, stateSecret and scopes (required)
• An installationStore option with handlers that store and fetch installations to your database (optional, strongly recommended in production)

Development and Testing

We’ve provided a default implementation of the installationStore FileInstallationStore which you can use during app development and testing.

const { App } = require('@slack/bolt');
const { FileInstallationStore } = require('@slack/oauth');
const app = new App({
  signingSecret: process.env.SLACK_SIGNING_SECRET,
  clientId: process.env.SLACK_CLIENT_ID,
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  stateSecret: 'my-state-secret',
  scopes: ['channels:history', 'chat:write', 'commands'],
  installationStore: new FileInstallationStore(),
});

This is not recommended for use in production - you should implement your own production store. Please see the example code to the right and our other examples.

Installing your App

• Initiating an installation: Bolt for JavaScript provides an Install Path /slack/install out-of-the-box. This endpoint returns a simple page with an Add to Slack button which initiates a direct install of your app (with a valid state parameter). An app hosted at www.example.com would serve the install page at www.example.com/slack/install.
  • 💡 You can skip rendering the provided default webpage and navigate users directly to Slack authorize URL by settinginstallerOptions.directInstall: true in the App constructor (example).

• Add to Slack: The Add to Slack button initiates the OAuth process with Slack. After users have clicked Allow to grant your app permissions, Slack will call your app’s Redirect URI (provided out-of-the-box), and prompt users to Open Slack. See the Redirect URI section below for customization options.

• Open Slack: After users Open Slack, and here after as your app processes events from Slack, your provided installationStore’s fetchInstallation and storeInstallation handlers will execute. See the Installation Object section below for more detail on arguments passed to those handlers.

• If you need additional authorizations (user tokens) from users inside a team when your app is already installed, or have a reason to dynamically generate an install URL, manually instantiate an ExpressReceiver, assign the instance to a variable named receiver, and then call receiver.installer.generateInstallUrl(). Read more about generateInstallUrl() in the OAuth docs.

• 💡 Bolt for JavaScript does not support OAuth for custom receivers. If you’re implementing a custom receiver, you can use our Slack OAuth library, which is what Bolt for JavaScript uses under the hood.

Redirect URI

Bolt for JavaScript provides a Redirect URI Path /slack/oauth_redirect. Slack uses the Redirect URI to redirect users after they complete an app’s installation flow.

💡 You will need to add the full Redirect URI including your app domain in your Slack app configuration settings under OAuth and Permissions, e.g. https://example.com/slack/oauth_redirect.

To supply your own custom Redirect URI, you can set redirectUri in the App options and installerOptions.redirectUriPath. You must supply both, and the path must be consistent with the full URI.

const app = new App({
  signingSecret: process.env.SLACK_SIGNING_SECRET,
  clientId: process.env.SLACK_CLIENT_ID,
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  stateSecret: 'my-state-secret',
  scopes: ['chat:write'],
  redirectUri: 'https://example.com/slack/redirect', // here
  installerOptions: {
    redirectUriPath: '/slack/redirect', // and here!
  },
});

Installation object

Bolt will pass your installationStore’s storeInstallation handler an installation. This can be a source of confusion for developers who aren’t sure what shape of object to expect. The installation object should resemble:

{
  team: { id: 'T012345678', name: 'example-team-name' },
  enterprise: undefined,
  user: { token: undefined, scopes: undefined, id: 'U01234567' },
  tokenType: 'bot',
  isEnterpriseInstall: false,
  appId: 'A01234567',
  authVersion: 'v2',
  bot: {
    scopes: [
      'chat:write',
    ],
    token: 'xoxb-244493-28*********-********************',
    userId: 'U012345678',
    id: 'B01234567'
  }
}

Bolt will pass your fetchInstallation and deleteInstallation handlers an installQuery object:

{
  userId: 'U012345678',
  isEnterpriseInstall: false,
  teamId: 'T012345678',
  enterpriseId: undefined,
  conversationId: 'D02345678'
}

Org-wide installation

To add support for org-wide installations, you will need Bolt for JavaScript version 3.0.0 or later. Make sure you have enabled org-wide installation in your app configuration settings under Org Level Apps.

Installing an org-wide app from admin pages requires additional configuration to work with Bolt. In that scenario, the recommended state parameter is not supplied. Bolt will try to verify state and stop the installation from progressing.

You may disable state verification in Bolt by setting the stateVerification option to false. See the example setup below:

const app = new App({
  signingSecret: process.env.SLACK_SIGNING_SECRET,
  clientId: process.env.SLACK_CLIENT_ID,
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  scopes: ['chat:write'],
  installerOptions: {
    stateVerification: false,
  },
});

To learn more about the OAuth installation flow with Slack, read the API documentation.

Socket Mode allows your app to connect and receive data from Slack via a WebSocket connection. To handle the connection, Bolt for JavaScript includes a SocketModeReceiver (in @slack/bolt@3.0.0 and higher). Before using Socket Mode, be sure to enable it within your app configuration.

To use the SocketModeReceiver, just pass in socketMode:true and appToken:YOUR_APP_TOKEN when initializing App. You can get your App Level Token in your app configuration under the Basic Information section.

Note: Since v2, error handling has improved! View the migration guide for V2 to learn about the changes.

If an error occurs in a listener, it’s recommended you handle it directly with a try/catch. However, there still may be cases where errors slip through the cracks. By default, these errors will be logged to the console. To handle them yourself, you can attach a global error handler to your app with the app.error(fn) method.

You can also define more focussed and specific error handlers for a variety of error paths directly on the HTTPReceiver:

• dispatchErrorHandler: triggered if an incoming request is to an unexpected path.
• processEventErrorHandler: triggered when processing a request (i.e. middleware, authorization) throws an exception.
• unhandledRequestHandler: triggered when a request from Slack goes unacknowledged.
• unhandledRequestTimeoutMillis: the amount of time in milliseconds to wait for request acknowledgement from the application before triggering the unhandledRequestHandler. Default is 3001.

NOTE: It is imperative that any custom Error Handlers defined in your app respond to the underlying Slack request that led to the error, using response.writeHead() to set the HTTP status code of the response and response.end() to dispatch the response back to Slack. See the example for details.

Authorization is the process of deciding which Slack credentials (such as a bot token) should be available while processing a specific incoming request.

Custom apps installed on a single workspace can simply use the token option at the time of App initialization. However, when your app needs to handle several tokens, such as cases where it will be installed on multiple workspaces or needs access to more than one user token, the authorize option should be used instead. If you’re using the built-in OAuth support authorization is handled by default, so you do not need to pass in an authorize option.

The authorize option can be set to a function that takes an event source as its input, and should return a Promise for an object containing the authorized credentials. The source contains information about who and where the request is coming from by using properties like teamId (always available), userId, conversationId, and enterpriseId.

The authorized credentials should also have a few specific properties: botToken, userToken, botId (required for an app to ignore messages from itself), and botUserId. You can also include any other properties you’d like to make available on the context object.

You should always provide either one or both of the botToken and userToken properties. At least one of them is necessary to make helpers like say() work. If they are both given, then botToken will take precedence.

Supported in Bolt for JavaScript as of v3.5.0, token rotation provides an extra layer of security for your access tokens and is defined by the OAuth V2 RFC.

Instead of an access token representing an existing installation of your Slack app indefinitely, with token rotation enabled, access tokens expire. A refresh token acts as a long-lived way to refresh your access tokens.

Bolt for JavaScript supports and will handle token rotation automatically so long as the built-in OAuth functionality is used.

For more information about token rotation, please see the documentation.

Bolt for JavaScript includes support for a store, which sets and retrieves state related to a conversation. Conversation stores have two methods:

• set() modifies conversation state. set() requires a conversationId of type string, value of any type, and an optional expiresAt of type number. set() returns a Promise.
• get() fetches conversation state from the store. get() requires a conversationId of type string and returns a Promise with the conversation’s state.

conversationContext() is a built-in global middleware that allows conversations to be updated by other middleware. When receiving an event, middleware functions can use context.updateConversation() to set state and context.conversation to retrieve it.

The built-in conversation store simply stores conversation state in memory. While this is sufficient for some situations, if there is more than one instance of your app running, the state will not be shared among the processes so you’ll want to implement a conversation store that fetches conversation state from a database.

Global middleware is run for all incoming requests before any listener middleware. You can add any number of global middleware to your app by utilizing app.use(fn). The middleware function fn is called with the same arguments as listeners and an additional next function.

Both global and listener middleware must call await next() to pass control of the execution chain to the next middleware, or call throw to pass an error back up the previously-executed middleware chain.

As an example, let’s say your app should only respond to users identified with a corresponding internal authentication service (an SSO provider or LDAP, for example). You may define a global middleware that looks up a user record in the authentication service and errors if the user is not found.

Note: Since v2, global middleware was updated to support async functions! View the migration guide for V2 to learn about the changes.

Listener middleware is used for logic across many listener functions (but usually not all of them). They are added as arguments before the listener function in one of the built-in methods. You can add any number of listener middleware before the listener function.

There’s a collection of built-in listener middleware that you can use like subtype() for filtering on a message subtype and directMention() which filters out any message that doesn’t directly @-mention your bot at the start of a message.

But of course, you can write your own middleware for more custom functionality. While writing your own middleware, your function must call await next() to pass control to the next middleware, or throw to pass an error back up the previously-executed middleware chain.

As an example, let’s say your listener should only deal with messages from humans. You can write a listener middleware that excludes any bot messages.

Note: Since v2, listener middleware was updated to support async functions! View the migration guide for V2 to learn about the changes.

All listeners have access to a context object, which can be used to enrich requests with additional information. For example, perhaps you want to add user information from a third party system or add temporary state for the next middleware in the chain.

context is just an object, so you can add to it by setting it to a modified version of itself.

Bolt offers a way to defer full initialization via the deferInitialization option and to call the equivalent App#init() in your code, putting more control over asynchronous execution required for initialization into your hands as the developer.

Note: If you call start() before init(), Bolt will raise an exception.

By default, Bolt for JavaScript will log information from your app to the console. You can customize how much logging occurs by passing a logLevel in the constructor. The available log levels in order of most to least logs are DEBUG, INFO, WARN, and ERROR.

A receiver is responsible for handling and parsing any incoming requests from Slack then sending it to the app, so that the app can add context and pass the request to your listeners. Receivers must conform to the Receiver interface:

init() is called after Bolt for JavaScript app is created. This method gives the receiver a reference to an App to store so that it can call:

• await app.processEvent(event) whenever your app receives a request from Slack. It will throw if there is an unhandled error.

To use a custom receiver, you can pass it into the constructor when initializing your Bolt for JavaScript app. Here is what a basic custom receiver might look like.

For a more in-depth look at a receiver, read the source code for the built-in ExpressReceiver

As of v3.7.0, custom HTTP routes can be easily added by passing in an array of routes as customRoutes when initializing App.

Each CustomRoute object must contain three properties: path, method, and handler. method, which corresponds to the HTTP verb, can be either a string or an array of strings.

To determine what port the custom HTTP route will be available on locally, you can specify an installerOptions.port property in the App constructor. Otherwise, it will default to port 3000.

⚠️ Workflow Steps from Apps are a legacy feature, not to be confused with workflows that are part of the next-gen beta. They are not interchangeable features. We encourage those who are currently publishing Workflow Steps from apps to join the beta - you can learn more about getting started with it here.

Workflow Steps from apps allow your app to create and process custom workflow steps that users can add using Workflow Builder.

A workflow step is made up of three distinct user events:

• Adding or editing the step in a Workflow
• Saving or updating the step’s configuration
• The end user’s execution of the step

All three events must be handled for a workflow step to function.

Read more about workflow steps from apps in the API documentation.

To create a workflow step, Bolt provides the WorkflowStep class.

When instantiating a new WorkflowStep, pass in the step’s callback_id and a configuration object.

The configuration object contains three properties: edit, save, and execute. Each of these properties must be a single callback or an array of callbacks. All callbacks have access to a step object that contains information about the workflow step event.

After instantiating a WorkflowStep, you can pass it into app.step(). Behind the scenes, your app will listen and respond to the workflow step’s events using the callbacks provided in the configuration object.

When a builder adds (or later edits) your step in their workflow, your app will receive a workflow_step_edit event. The edit callback in your WorkflowStep configuration will be run when this event is received.

Whether a builder is adding or editing a step, you need to send them a workflow step configuration modal. This modal is where step-specific settings are chosen, and it has more restrictions than typical modals—most notably, it cannot include title​, submit​, or close​ properties. By default, the configuration modal’s callback_id will be the same as the workflow step.

Within the edit callback, the configure() utility can be used to easily open your step’s configuration modal by passing in an object with your view’s blocks. To disable saving the configuration before certain conditions are met, pass in submit_disabled with a value of true.

To learn more about opening configuration modals, read the documentation.

After the configuration modal is opened, your app will listen for the view_submission event. The save callback in your WorkflowStep configuration will be run when this event is received.

Within the save callback, the update() method can be used to save the builder’s step configuration by passing in the following arguments:

• inputs is an object representing the data your app expects to receive from the user upon workflow step execution.
• outputs is an array of objects containing data that your app will provide upon the workflow step’s completion. Outputs can then be used in subsequent steps of the workflow.
• step_name overrides the default Step name
• step_image_url overrides the default Step image

To learn more about how to structure these parameters, read the documentation.

When your workflow step is executed by an end user, your app will receive a workflow_step_execute event. The execute callback in your WorkflowStep configuration will be run when this event is received.

Using the inputs from the save callback, this is where you can make third-party API calls, save information to a database, update the user’s Home tab, or decide the outputs that will be available to subsequent workflow steps by mapping values to the outputs object.

Within the execute callback, your app must either call complete() to indicate that the step’s execution was successful, or fail() to indicate that the step’s execution failed.