Building an app with Bolt

The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read next:Designing a great app experience
Open beta for new Slack apps

This sneaky preview gives you access to new features in Slack apps. Since we're still finalizing these apps, a few features may not yet have arrived. We expect the final version of new Slack apps to be available within a few months.

Bolt

The estimated time it takes to complete this guide is 15 minutes.

Bolt is a foundational JavaScript framework that makes it easier to build Slack apps with the platform's latest features. This guide walks you through building your first app with Bolt.

Along the way, you'll create a new Slack app, set up a simple development environment, and build an app that listens and responds to events from your Slack workspace.


Getting started

The first section of this guide covers creating a basic Slack app tailored to work with Bolt. While we glance over some configuration, our more general app setup guide goes into greater detail.

Creating a Slack app

To get started, you'll need to create a new Slack app:

Create an open beta Slack app

Fill out your App Name and select the Development Workspace where you'll play around and build your app. Don't fuss too much over either field—no matter what workspace you select, you'll still be able to distribute your app to other workspaces if you choose.

Requesting scopes

Scopes give your app permission to do things (for example, post messages) in your development workspace. You can select the scopes to add to your app by navigating over to the OAuth & Permissions sidebar or selecting your app below:

Scroll down to the Bot Token Scopes section and click Add an OAuth Scope.

For now, we'll add two scopes:

  • Add the chat:write scope to grant your app the permission to post messages in channels it's a member of.
  • Add the users:read scope to grant your app the permission to read information about users on your workspace. Bolt calls the users.info method to retrieve more information about your Bot User.

Installing your app

Install your own app by selecting the Install App button at the top of the OAuth & Permissions page, or from the sidebar.

After clicking through one more green Install App To Workspace button, you'll be sent through the Slack OAuth UI.

OAuth UI in app installation process

After installation, you'll land back in the OAuth & Permissions page and find a Bot User OAuth Access Token.

Access tokens are imbued with power. They represent the permissions delegated to your app by the installing user. Remember to keep your access token secret and safe, to avoid violating the trust of the installing user.

At a minimum, avoid checking your access token into public version control. Access it via an environment variable. We've also got plenty more best practices for app security.

Opt-in to the app home beta

BETA

This guide uses app home, a feature in open beta that offers a persistent space where your app can display dynamic interfaces for users. While you can still submit apps using app home to the App Directory, the feature is in beta.

To enable app home, click on the App Home sidebar or select your app from the dropdown below:

Setting up your Bolt app

With the app configured and installed, it’s time to set up a new Bolt project with your app's credentials.

Remix the Bolt app template

To make development simple, this guide uses Glitch , a tool that makes it easy to build basic apps. While Glitch is great for development, your server will not stay running when your app is idle. When your app is production-ready, we recommend hosting it somewhere else.

To get started, remix (or clone) our Bolt app template:

Remix the Bolt app template

In the app.js file, you'll see the import of the Bolt package (@slack/bolt), the instantation of your app, and start-up of the app's server which listens to incoming events from Slack.

Glitch UI after you remix the app

We'll add more code later, but first we want to add your app's crendentials to begin listening to Slack events.

Adding your app credentials

To start the app, you'll need to copy over the credentials for your app. Copy the Bot User OAuth Access Token under the OAuth & Permissions sidebar (talked about in the installation section).

In your Glitch project, navigate to the .env file located on the left-hand sidebar. Paste your Bot User OAuth Access Token directly after SLACK_ACCESS_TOKEN=.

You'll notice underneath the access token, there's space for a signing secret. Your app's signing secret verifies that incoming requests are coming from Slack. Navigate to the Basic Information page from your app management page. Under App Credentials, copy the value for Signing Secret.

In your Glitch project, navigate back to the .env file. Paste your signing secret directly after SLACK_SIGNING_SECRET=.

If you click the Tools button at the bottom of the file navigator, then Logs, you should see that your Bolt app is running!

Subscribing to events

Your app can listen to all sorts of events happening around your workspace β€” messages being posted, reactjis being emoted, users joining the team, and more. To listen for events, your app uses the Events API.

Let's subscribe to the app_home_opened event. Select the Event Subscriptions sidebar. You'll be presented with an input box to enter a Request URL, which is where Slack sends the events your app is subscribed to. We'll use the URL of your Glitch app from above. To retrieve the URL of your app click Share > Live App within your project, and the URL will have your project's name prepended to the Glitch URL.

For example: https://bolt-app-template.glitch.me

By default Bolt listens for all events at the /slack/events route, so for the Request URL you can enter your project's URL appended with /slack/events.

For example: https://bolt-app-template.glitch.me/slack/events

After you've saved your Request URL, click on Subscribe to events on behalf of users, then Add Workspace Event and search for app_home_opened. Then Save Changes using the the green button on the bottom right, and your app will start receiving app_home_opened events as users navigate to your app from the Slack sidebar or search bar.

Responding to events

To respond to events with Bolt, you can write a listener. Listeners have access to the event body, the entire request payload, and an additional context object that holds helpful information like the bot token you used to instantiate your app.

Let's set up a basic listener using the app_home_opened event that publishes a view to your Home tab, which is a persistent space where your app can display a dynamic interface for users.

Paste this listener code into your existing Bolt app:

app.event('app_home_opened', async ({ event, context }) => {
  try {
    /* view.publish is the method that your app uses to push a view to the Home tab */
    const result = await app.client.views.publish({

      /* retrieves your xoxb token from context */
      token: context.botToken,

      /* the user that opened your app's app home */
      user_id: event.user,

      /* the view payload that appears in the app home*/
      view: {
        type: 'home',
        callback_id: 'home_view',

        /* body of the view */
        blocks: [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "*Welcome to your _App's Home_* :tada:"
            }
          },
          {
            "type": "divider"
          },
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "This button won't do much for now but you can set up a listener for it using the `actions()` method and passing its unique `action_id`. See an example in the `examples` folder within your Bolt app."
            }
          },
          {
            "type": "actions",
            "elements": [
              {
                "type": "button",
                "text": {
                  "type": "plain_text",
                  "text": "Click me!"
                }
              }
            ]
          }
        ]
      }
    });
  }
  catch (error) {
    console.error(error);
  }
});

View this example

Next steps

Now try out your app by navigating to its app home by clicking on your app from the sidebar. When you open the Home, you should see your view appear. Congrats on building your first Bolt app πŸŽ†πŸ™Œ

With the basics under your belt, you can start exploring the rest of Bolt and the entire Slack platform. Here's a few paths you may consider wandering:

  • Check out the examples folder within your Glitch project. There are a few files with different examples of simple apps that show you different features of the platform.

  • Improve your app's design with the Block Kit Builder. This is a prototyping tool that allows you to design Slack apps quickly, then paste the code into your Bolt app (we also have public Figma files if you'd rather use them to design your app).

  • Read the Bolt documentation to learn about advanced functionality and find example code snippets that show you what else is possible.

  • Explore other surfaces where your app can exist, like messages and pop-up modals.

And just a reminder: when you're ready to take your app from development to deployed, you'll want to host it on another platform.

Need help or have questions?

Email our developer support team