Bolt for JavaScript

A JavaScript framework to build Slack apps in a flash with the latest platform features. Read the getting started guide to set-up and run your first Bolt app.

Read the documentation to explore the basic and advanced concepts of Bolt for JavaScript.

Setup

npm install @slack/bolt

Initialization

Create an app by calling the constructor, which is a top-level export.

const { App } = require('@slack/bolt');

const app = new App({
  signingSecret: process.env.SLACK_SIGNING_SECRET,
  token: process.env.SLACK_BOT_TOKEN,
});

/* Add functionality here */

(async () => {
  // Start the app
  await app.start(process.env.PORT || 3000);

  console.log('⚡️ Bolt app is running!');
})();

Listening for events

The Slack Request URL for a Bolt app must have the path set to /slack/events.
For example: https://my-slack-app.example.com/slack/events.
Otherwise, all incoming requests from Slack won't be handled.

Apps typically react to a collection of incoming events, which can correspond Events API events, actions, shortcuts, slash commands or options requests. For each type of request, there's a method to build a listener function.

// Listen for an event from the Events API
app.event(eventType, fn);

// Convenience method to listen to only `message` events using a string or RegExp
app.message([pattern ,] fn);

// Listen for an action from a Block Kit element (buttons, select menus, date pickers, etc)
app.action(actionId, fn);

// Listen for dialog submissions
app.action({ callback_id: callbackId }, fn);

// Listen for a global or message shortcuts
app.shortcut(callbackId, fn);

// Listen for slash commands
app.command(commandName, fn);

// Listen for view_submission modal events
app.view(callbackId, fn);

// Listen for options requests (from select menus with an external data source)
app.options(actionId, fn);

Making things happen

Most of the app's functionality will be inside listener functions (the fn parameters above). These functions are called with a set of arguments.

The arguments are grouped into properties of one object, so that it's easier to pick just the ones your listener needs (using object destructuring). Here is an example where the app sends a simple response, so there's no need for most of these arguments:

// Reverse all messages the app can hear
app.message(async ({ message, say }) => {
  // Filter out message events with subtypes (see https://api.slack.com/events/message)
  if (message.subtype === undefined || message.subtype === 'bot_message') {
    const reversedText = [...message.text].reverse().join("");
    await say(reversedText);
  }
});

Calling the Web API

In addition to the client property passed to listeners, each app has a top-level client that can be used to call methods. Unlike the client passed to listeners, the top-level client must be passed a token. Read the documentation for more details.

Acknowledging events

Some types of events need to be acknowledged in order to ensure a consistent user experience inside the Slack client (web, mobile, and desktop apps). This includes all action, shortcut, view, command, and options requests. Listeners for these events need to call the ack() function, which is passed in as an argument.

In general, the Slack platform expects an acknowledgement within 3 seconds, so listeners should call this function as soon as possible.

Depending on the type of incoming event a listener is meant for, ack() should be called with a parameter:

• Block actions, global shortcuts, and message shortcuts: Call ack() with no parameters.

• View submissions: Call ack() with no parameters or with a response action.

• Options requests: Call ack() with an object containing the options for the user to see.

• Legacy message button clicks, menu selections, and slash commands: Either call ack() with no parameters, a string to to update the message with a simple message, or an object to replace it with a complex message. Replacing the message to remove the interactive elements is a best practice for any action that should only be performed once.

• Events API events do not need an ack() function since they are automatically acknowledged by your app.

Getting Help

The documentation has more information on basic and advanced concepts for Bolt for JavaScript.

If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue:

• Issue Tracker for questions, bug reports, feature requests, and general discussion related to Bolt for JavaScript. Try searching for an existing issue before creating a new one.
• Email our developer support team: [email protected]

Contributing

We welcome contributions from everyone! Please check out our Contributor's Guide for how to contribute in a helpful and collaborative way.