Building your first app with Bolt

Navigating the process of building a Slack app can be a bit complex, especially when you're coding from scratch! You can easily get lost in the API docs to figure out why your code failed and what argument you missed — or even to execute a small task such as which method to use to send a plain text message.

In this step-by-step tutorial, we'll build a small Slack app that sends a welcome message when a user open the bot's App Home.

The source code you'll need is on Glitch, which is a web-based IDE, where you can remix (similar to GitHub's fork) the original code, and run it on a browser without deploying.

• Source code: https://glitch.com/edit/#!/slack-bolt-hello-world
• Remix: https://glitch.com/edit/#!/remix/slack-bolt-hello-world

To continue, click the Remix link above. In a minute, you'll have your own project that you can play with. Notice that your remixed project has a new name consisting of random words such as elegant-fox or majestic-hip-waitress.

Creating an app using the Events API

Setting up an app

In another browser tab or window, go to Slack App Management to create an app — or, click the button below:

Create a Slack app

In the box, give your new app a name and choose a workspace where you want to install the app. We recommend using a workspace that won't disrupt you from getting real work done — you can create a new one for free. Click Create App.

Within the Settings > Basic Information screen, scroll down to App Credentials and find your Signing secret by clicking Show to reveal it, then copy the string. You'll store it in an .env file at the next step.

Navigate to your Glitch project. Open your .env file, where you store all of your secrets, and paste your Signing secret. This is only visible to you, and when you share the Glitch project with somebody else, they won't see the values in the file.

Navigate to the Features > OAuth & Permissions section and scroll down to Bot Token Scopes to specify the OAuth scopes. Select chat:write to allow the bot to post in channels in which it's added. If you so desire, you can also select chat:write.public to allow the bot to post in all public channels.

Install the app to your workspace to obtain your OAuth token. Navigate to Install App and click Install App to Workspace. Follow the prompts to complete the installation.

Once you finish installing, you should see the following screen showing two tokens. For this tutorial, you only need the bot token, which begins with xoxb- (1).

Now you need to store the bot token in your .env file in your Glitch project.

Setting up an event

You'll need to subscribe to events so that when a Slack event happens (such as a user opening the App Home), your app server will receive an event payload.

Navigate to Event Subscriptions and turn the toggle switch on to enable events (1).

Enter your Request URL (2). When you're coding with Bolt, your Request URL should look like https://your-server/slack/events. In this tutorial we're using Glitch, so your server URL should be project-name.glitch.me. This means the Request URL will look like, https://thin-coin.glitch.me/slack/events.

You need to replace thin-coin with the project name Glitch assigned you! Copy and pasting this URL will not work.

When your request URL is correct, you should see a green checkmark.

Scroll down to Subscribe to bot events. Click the Add Bot User Event button to add app_home_opened event (3). Click Save Changes (4).

Coding with Bolt

Since you've remixed the completed Glitch project, your app should be up and running already. But wait, there's more! Let's get into that code before you try the app on Slack.

Go back to your Glitch project, and select package.json. This is where the app is defined; notice the Bolt package is already included as a dependency, so you don't need to install the package. Glitch runs the npm command for you in the background.

If you're creating a brand new Bolt project from scratch outside of Glitch, you will need to run the npm command to install it. The first step is to create a blank project and install Bolt:

$ npm i @slack/bolt

In your index.js file, require the Bolt package, and initialize an app with your credentials:

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

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

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

Once you run your node code (this is automatic on Glitch), your app server is up and running.

Handling events with Bolt

To listen to any Events API events from Slack, use the Bolt event() method. This allows your app to take action when something happens in Slack. In this scenario, it's triggered when a user opens the App Home.

The event() method requires an eventType of type string, and in this case it is app_home_opened.

app.event('app_home_opened', ({ event, say }) => {  
    say(`Hello world, <@${event.user}>!`);
});

With this snippet, the app sends the message “Hello world” followed by the sender's username using the say() method.

In the Glitch sample code, it uses a pseudo-database to see if the user opens the App Home for the first time, and sends the “Hello world” message only on the first time it is opened. Try to send “Hi again!” after the second time. Alternatively, call another API method, for example conversations.history, to see if there are any previous messages in the chat history.

Let's try your app! Open your workspace and click on your bot's App Home. Once you open the Messages tab, you should receive the “Hello world” message!

Congratulations, your first Bolt app is completed! You've learned how to initialize Bolt and how to use events, so when you build a full-fledged app in the near future, you can use the App Home sample to create an onboarding process for the app.

Onward

To learn how to implement the Home tab, check out How to create the App Home view and use a modal!

🇯🇵 Read this tutorial in Japanese (日本語): Hello World, Bolt! ⚡️ Bolt フレームワークを使って Slack Bot を作ろう

---