Getting started with Bolt for JavaScript and HTTP
This guide is meant to walk you through getting up and running with a Slack app using Bolt for JavaScript. Along the way, we’ll create a new Slack app, set up your local environment, and develop an app that listens and responds to messages from a Slack workspace.
When you’re finished, you’ll have this ⚡️Getting Started app to run, modify, and make your own.
Create an app
First thing's first: before you start developing with Bolt, you'll want to create a Slack app.
We recommend using a workspace where you won't disrupt real work getting done — you can create a new one for free.
After you fill out an app name (you can change it later) and pick a workspace to install it to, hit the Create App
button and you'll land on your app's Basic Information page.
This page contains an overview of your app in addition to important credentials you'll need later, like the Signing Secret
under the App Credentials header.
Look around, add an app icon and description, and then let's start configuring your app. 🔩
Tokens and installing apps
Slack apps use OAuth to manage access to Slack's APIs. When an app is installed, you'll receive a token that the app can use to call API methods.
There are three main token types available to a Slack app: user (xoxp
), bot (xoxb
), and app (xapp
) tokens.
- User tokens allow you to call API methods on behalf of users after they install or authenticate the app. There may be several user tokens for a single workspace.
- Bot tokens are associated with bot users, and are only granted once in a workspace where someone installs the app. The bot token your app uses will be the same no matter which user performed the installation. Bot tokens are the token type that most apps use.
- App-level tokens represent your app across organizations, including installations by all individual users on all workspaces in a given organization and are commonly used for creating websocket connections to your app.
For brevity, we're going to use bot tokens for this guide.
-
Navigate to the OAuth & Permissions on the left sidebar and scroll down to the Bot Token Scopes section. Click Add an OAuth Scope.
-
For now, we'll just add one scope:
chat:write
. This grants your app the permission to post messages in channels it's a member of. -
Scroll up to the top of the OAuth & Permissions page and click Install App to Workspace. You'll be led through Slack's OAuth UI, where you should allow your app to be installed to your development workspace.
-
Once you authorize the installation, you'll land on the OAuth & Permissions page and see a Bot User OAuth Access Token.
Treat your token like a password and keep it safe. Your app uses it to post and retrieve information from Slack workspaces.
Setting up your project
With the initial configuration handled, it's time to set up a new Bolt project. This is where you'll write the code that handles the logic for your app.
If you don’t already have a project, let’s create a new one. Create an empty directory and initialize a new project:
mkdir first-bolt-app
cd first-bolt-app
npm init
You’ll be prompted with a series of questions to describe your new project (you can accept the defaults by hitting Enter on each prompt if you aren’t picky). After you’re done, you’ll have a new package.json
file in your directory.
Before we install the Bolt for JavaScript package to your new project, let's save the bot token and Signing Secret that were generated when you configured your app.
- Copy your Signing Secret from the Basic Information page and then store it in a new environment variable. The following example works on Linux and macOS; but similar commands are available on Windows.
export SLACK_SIGNING_SECRET=<your-signing-secret>
- Copy your bot (xoxb) token from the OAuth & Permissions page and store it in another environment variable.
export SLACK_BOT_TOKEN=xoxb-<your-bot-token>
Remember to keep your token and signing secret secure. At a minimum, you should avoid checking them into public version control, and access them via environment variables as we've done above. Checkout the API documentation for more on best practices for app security.
Now, let's create your app. Install the @slack/bolt
package and save it to your package.json
dependencies using the following command:
npm install @slack/bolt
Create a new entrypoint file called app.js
in this directory and add the following code:
const { App } = require('@slack/bolt');
// Initializes your app with your bot token and signing secret
const app = new App({
token: process.env.SLACK_BOT_TOKEN,
signingSecret: process.env.SLACK_SIGNING_SECRET
});
(async () => {
// Start your app
await app.start(process.env.PORT || 3000);
console.log('⚡️ Bolt app is running!');
})();
Save your app.js
file, then on the command line run the following:
node app.js
Your app should let you know that it's up and running. 🎉
Setting up events with HTTP
Your app behaves similarly to people on your team — it can post messages, add emoji reactions, and listen and respond to events.
To listen for events happening in a Slack workspace (like when a message is posted or when a reaction is posted to a message) you'll use the Events API to subscribe to event types.
Let's enable events for your app:
-
Go back to your app configuration page (click on the app from your app management page). Click Event Subscriptions on the left sidebar. Toggle the switch labeled Enable Events.
-
Add your Request URL. Slack will send HTTP POST requests corresponding to events to this Request URL endpoint. Bolt uses the
/slack/events
path to listen to all incoming requests (whether shortcuts, events, or interactivity payloads). When configuring your Request URL within your app configuration, you'll append/slack/events
, e.g.https://<your-domain>/slack/events
. 💡
For local development, you can use a proxy service like ngrok to create a public URL and tunnel requests to your development environment. Refer to ngrok's getting started guide on how to create this tunnel.
Finally, it's time to tell Slack what events we'd like to listen for. Under Event Subscriptions, toggle the switch labeled Enable Events.
When an event occurs, Slack will send your app information about the event, like the user that triggered it and the channel it occurred in. Your app will process the details and can respond accordingly.
Scroll down to Subscribe to Bot Events. There are four events related to messages:
message.channels
listens for messages in public channels that your app is added tomessage.groups
listens for messages in 🔒 private channels that your app is added tomessage.im
listens for messages in your app's DMs with usersmessage.mpim
listens for messages in multi-person DMs that your app is added to
If you want your bot to listen to messages from everywhere it is added to, choose all four message events. After you’ve selected the events you want your bot to listen to, click the green Save Changes button.
Listening and responding to a message
Your app is now ready for some logic. Let's start by using the message()
method to attach a listener for messages.
The following example listens and responds to all messages in channels/DMs where your app has been added that contain the word "hello":
const { App } = require('@slack/bolt');
const app = new App({
token: process.env.SLACK_BOT_TOKEN,
signingSecret: process.env.SLACK_SIGNING_SECRET,
});
// Listens to incoming messages that contain "hello"
app.message('hello', async ({ message, say }) => {
// say() sends a message to the channel where the event was triggered
await say(`Hey there <@${message.user}>!`);
});
(async () => {
// Start your app
await app.start(process.env.PORT || 3000);
console.log('⚡️ Bolt app is running!');
})();
If you restart your app, so long as your bot user has been added to the channel/DM, when you send any message that contains "hello", it will respond.
This is a basic example, but it gives you a place to start customizing your app based on your own goals. Let's try something a little more interactive by sending a button rather than plain text.
Sending and responding to actions
To use features like buttons, select menus, datepickers, modals, and shortcuts, you’ll need to enable interactivity. Similar to events, you'll need to specify a Request URL for Slack to send the action (such as user clicked a button). Head over to Interactivity & Shortcuts in your app configuration.
By default, Bolt uses the same endpoint for interactive components that it uses for events, so use the same request URL as above (in the example, it was https://8e8ec2d7.ngrok.io/slack/events
). Press the Save Changes button in the lower right hand corner, and that's it. Your app is set up to handle interactivity!
When interactivity is enabled, interactions with shortcuts, modals, or interactive components (such as buttons, select menus, and datepickers) will be sent to your app as events.
Now, let’s go back to your app’s code and add logic to handle those events:
- First, we'll send a message that contains an interactive component (in this case a button).
- Next, we'll listen for the action of a user clicking the button before responding
Below, the code from the last section is modified to send a message containing a button rather than just a string:
const { App } = require('@slack/bolt');
const app = new App({
token: process.env.SLACK_BOT_TOKEN,
signingSecret: process.env.SLACK_SIGNING_SECRET
});
// Listens to incoming messages that contain "hello"
app.message('hello', async ({ message, say }) => {
// say() sends a message to the channel where the event was triggered
await say({
blocks: [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": `Hey there <@${message.user}>!`
},
"accessory": {
"type": "button",
"text": {
"type": "plain_text",
"text": "Click Me"
},
"action_id": "button_click"
}
}
],
text: `Hey there <@${message.user}>!`
});
});
(async () => {
// Start your app
await app.start(process.env.PORT || 3000);
console.log('⚡️ Bolt app is running!');
})();
The value inside of say()
is now an object that contains an array of blocks
. Blocks are the building components of a Slack message and can range from text to images to datepickers. In this case, your app will respond with a section block that includes a button as an accessory. Since we're using blocks
, the text
is a fallback for notifications and accessibility.
You'll notice in the button accessory
object, there is an action_id
. This will act as a unique identifier for the button so your app can specify what action it wants to respond to.
The Block Kit Builder is a simple way to prototype your interactive messages. The builder lets you (or anyone on your team) mockup messages and generates the corresponding JSON that you can paste directly in your app.
Now, if you restart your app and say "hello" in a channel your app is in, you'll see a message with a button. But if you click the button, nothing happens (yet!).
Let's add a handler to send a followup message when someone clicks the button:
const { App } = require('@slack/bolt');
const app = new App({
token: process.env.SLACK_BOT_TOKEN,
signingSecret: process.env.SLACK_SIGNING_SECRET
});
// Listens to incoming messages that contain "hello"
app.message('hello', async ({ message, say }) => {
// say() sends a message to the channel where the event was triggered
await say({
blocks: [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": `Hey there <@${message.user}>!`
},
"accessory": {
"type": "button",
"text": {
"type": "plain_text",
"text": "Click Me"
},
"action_id": "button_click"
}
}
],
text: `Hey there <@${message.user}>!`
});
});
app.action('button_click', async ({ body, ack, say }) => {
// Acknowledge the action
await ack();
await say(`<@${body.user.id}> clicked the button`);
});
(async () => {
// Start your app
await app.start(process.env.PORT || 3000);
console.log('⚡️ Bolt app is running!');
})();
You can see that we used app.action()
to listen for the action_id
that we named button_click
. If you restart your app and click the button, you'll see a new message from your app that says you clicked the button.
Next steps
You just built your first Bolt for JavaScript app! 🎉
Now that you have a basic app up and running, you can start exploring how to make your Bolt app stand out. Here are some ideas about what to explore next:
-
Read through the Basic concepts to learn about the different methods and features your Bolt app has access to.
-
Explore the different events your bot can listen to with the
events()
method. All of the events are listed on the API site. -
Bolt allows you to call Web API methods with the client attached to your app. There are over 200 methods on our API site.
-
Learn more about the different token types on our API site. Your app may need different tokens depending on the actions you want it to perform. If you are using Socket Mode instead of HTTP, an additional (
xapp
) token withconnections:write
scopes is required.