diff --git a/docs/english/building-an-app.md b/docs/english/building-an-app.md index b1941fee1..ea961a4a6 100644 --- a/docs/english/building-an-app.md +++ b/docs/english/building-an-app.md @@ -2,300 +2,427 @@ sidebar_label: Building an App --- -# Building an App with Bolt for JavaScript +# Building an app with Bolt for JavaScript -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. +This guide will walk you through creating and using a Slack app built with Bolt for JavaScript. -When you’re finished, you’ll have created the [Getting Started app](https://github.com/slackapi/bolt-js-getting-started-app) to run, modify, and make your own. ⚡️ +On this journey, you'll: ---- +- set up your local environment, +- create a new Slack app, +- and enable it to listen for and respond to messages within a Slack workspace. + +When you’re finished, you’ll have created the [Getting Started app](https://github.com/slack-samples/bolt-js-getting-started-app) to run, modify, and make your own. ⚡️ + +:::tip[Less reading, more doing] -## Create an app {#create-an-app} +Follow the [quickstart](/tools/bolt-js/getting-started) guide to run an app as soon as possible. This guide will more thoroughly explore building your first app using Bolt for JavaScript. + +::: -First thing's first: before you start developing with Bolt, you'll want to [create a Slack app](https://api.slack.com/apps/new). +## Prerequisites -:::tip[A place to test and learn] +:::info[A place to belong] -We recommend using a workspace where you won't disrupt real work getting done — [you can create a new one for free](https://slack.com/get-started#create). +You'll need a workspace where development can happen. We recommend using [developer sandboxes](/tools/developer-sandboxes/) to avoid disruptions where real work gets done. ::: -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. +We recommend using the [**Slack CLI**](/tools/slack-cli/) for the smoothest experience, but you can also choose to follow along in the terminal as long as you have Node.js. -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. + + -![Basic Information page](/img/bolt-js/basic-information-page.png "Basic Information page") +Install the latest version of the Slack CLI for your operating system of choice by following the corresponding guide: -Look around, add an app icon and description, and then let's start configuring your app. 🔩 +- [Slack CLI for macOS & Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) +- [Slack CLI for Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows) ---- +Then confirm the Slack CLI is successfully installed by running the following command: -## Tokens and installing apps {#tokens-and-installing-apps} +```sh +$ slack version +``` -Slack apps use [OAuth to manage access to Slack's APIs](/authentication/installing-with-oauth). When an app is installed, you'll receive a token that the app can use to call API methods. +You'll also need to log in if this is your first time using the Slack CLI. -There are three main token types available to a Slack app: user (`xoxp-...`), bot (`xoxb-...`), and app (`xapp-...`) tokens. +```sh +$ slack login +``` -- [User tokens](/authentication/tokens#user) 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](/authentication/tokens#bot) 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](/authentication/tokens#app-level) 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. + + -We're going to use bot and app tokens for this guide. +You can follow along in this guide as long as you have Node installed. We recommend the latest active release: -1. Navigate to the **OAuth & Permissions** on the left sidebar and scroll down to the **Bot Token Scopes** section. Click **Add an OAuth Scope**. +- [Node.js](https://nodejs.org/en/download) -2. For now, we'll just add one scope: [`chat:write`](/reference/scopes/chat.write). This scope grants your app the permission to post messages in channels it's a member of. +Once installed, make sure the right version is being used: -3. 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. +```sh +$ node --version +``` -4. Once you authorize the installation, you'll land on the **OAuth & Permissions** page and see a **Bot User OAuth Access Token**. + + -![OAuth Tokens](/img/bolt-js/bot-token.png "Bot OAuth Token") +## Initializing the project {#initializing-a-project} -:::tip[Not sharing is sometimes caring] +With your toolchain configured, you can now set up a new Bolt project. This is where you'll write the code that handles the logic of your app. -Treat your token like a password and [keep it safe](/authentication/best-practices-for-security). Your app uses it to post and retrieve information from Slack workspaces. +If you don’t already have a project, let’s create a new one! -::: + + ---- +In this guide, we'll be scaffolding this project with the [`bolt-js-blank-template`](https://github.com/slack-samples/bolt-js-blank-template) template. + +```sh +$ slack create first-bolt-app --template slack-samples/bolt-js-blank-template +$ cd first-bolt-app +``` + +After your project is created you will see a `package.json` file with project details and a `.slack` directory for application use. -## Setting up your project {#setting-up-your-project} +A few other files exist too, but we'll visit these later. -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: +Create and move into a new directory before you initialize the project: -```shell -mkdir first-bolt-app -cd first-bolt-app -npm init +```sh +$ 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. +Next we'll install the Bolt for JavaScript package to the project's dependencies: + +```sh +$ npm install @slack/bolt +``` -1. **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](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153). + + -```shell -export SLACK_SIGNING_SECRET= +Outlines of a project are taking shape, so let's move onto creating an app! + +## Creating the app {#creating-an-app} + +Before you can begin developing with Bolt for JavaScript, you'll want to create a Slack app. + + + + +The scaffolded blank template contains a `manifest.json` file with the app details for the app we are creating and installing. + +Run the following command to create a new "local" app and choose a Slack team for development: + +```sh +$ slack install ``` -2. **Copy your bot (xoxb) token from the OAuth & Permissions page** and store it in another environment variable. +Your new app will have some placeholder values and a small set of [scopes](/reference/scopes) to start, but we'll explore more customizations soon. + + + + +Navigate to your list of apps within App Settings and [create a new Slack app](https://api.slack.com/apps/new) from scratch. -```shell -export SLACK_BOT_TOKEN=xoxb- +After you fill out an app name (this can be changed later) and pick a workspace to install it to, press the `Create App` button and you'll land on your app's **Basic Information** page. + +![Basic Information page](/img/bolt-js/basic-information-page.png "Basic Information page") + +Look around, add an app icon and description, and then let's start configuring your app. 🔩 + +#### Installing the app {#installing-the-app} + +Slack apps [use OAuth to manage access](/authentication/installing-with-oauth) to the various Slack 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](/authentication/tokens) available to a Slack app: user (`xoxp`), bot (`xoxb`), and app (`xapp`) tokens: + +- [User tokens](/authentication/tokens#user) 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](/authentication/tokens#bot) 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](/authentication/tokens#app-level) represent your app across organizations, including installations by all individual users on all workspaces in a given organization. App-level tokens are commonly used for creating websocket connections to your app. + +We're going to use bot and app tokens for this guide. + +1. Within App Settings, navigate to **OAuth & Permissions** in the left sidebar. Then scroll down to the **Bot Token Scopes** section. Click **Add an OAuth Scope**. +2. For now, we'll just add one scope: [`chat:write`](/reference/scopes/chat.write). This scope grants your app the permission to post messages in channels it's a member of. +3. Scroll up to the top of the **OAuth & Permissions** page and click **Install to Team**. You'll be led through Slack's OAuth UI, where you should allow your app to be installed to your development workspace. +4. Once you authorize the installation, you'll land on the **OAuth & Permissions** page and see a **Bot User OAuth Access Token**. + +![OAuth Tokens](/img/bolt-js/bot-token.png "Bot OAuth Token") + +You'll need to save the generated **bot token** as an environment variable. Copy your bot token beginning with `xoxb` and insert it into the following command: + +```sh +$ export SLACK_BOT_TOKEN=xoxb- ``` -:::warning[Keep it secret. Keep it safe] +The above example works on Linux and macOS, but [similar commands are available on Windows](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153). -Remember to keep your tokens 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](/authentication/best-practices-for-security). +:::danger[Keep your tokens and signing secret secure] + +At a minimum, you should avoid checking tokens and signing secrets into public version control, and you should access them via environment variables as shown above. Check out the API docs for more [app security best practices](/authentication/best-practices-for-security). ::: -Now, let's create your app. Install the `@slack/bolt` package and save it to your `package.json` dependencies using the following command: + + + +## Preparing to receive events {#preparing-receive-events} + +Let's now start your app to receive events from the [Events API](/apis/events-api). We'll listen and respond to certain events soon! + +There are two paths for connecting your app to receive events: + +- **Socket Mode**: For those just starting, we recommend using [Socket Mode](/apis/events-api/using-socket-mode/). Socket Mode allows your app to use the Events API and interactive features without exposing a public HTTP Request URL. This can be helpful during development, or if you're receiving requests from behind a firewall. +- **Request URL**: Alternatively, you're welcome to set up an app with public HTTP [Request URLs](/apis/events-api/using-http-request-urls). HTTP is more useful for apps being deployed to hosting environments (like [AWS](/tools/bolt-js/deployments/aws-lambda) or [Heroku](/tools/bolt-js/deployments/heroku)) to stably respond within large Slack organizations, or apps intended for distribution via the Slack Marketplace. + +We've provided instructions for both ways in this guide, choose your flavor and let's carry on. + + + + +:::tip[The Slack CLI template does not require Socket Mode configurations] + +The template we used to start with the Slack CLI is configured to use Socket Mode out of the box! [Skip to the _Running the app_ section](#running-the-app). + +::: + +First you'll need to enable events from [app settings](https://api.slack.com/apps): + +1. Click **Event Subscriptions** on the left sidebar. Toggle the switch labeled **Enable Events**. +2. Navigate to **Socket Mode** on the left side menu and toggle **Enable Socket Mode** on. +3. Go to **Basic Information** and scroll down under the App-Level Tokens section and click **Generate Token and Scopes** to generate an app token. Add the `connections:write` scope to this token and save the generated `xapp` token, we'll use that in just a moment. + +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. -```shell -npm install @slack/bolt +Back in your project, store the `xapp` token you created earlier in your environment. + +```sh +$ export SLACK_APP_TOKEN=xapp- ``` -Create a new entrypoint file called `app.js` in this directory and add the following code: +Create a new entrypoint file called `app.js` in your project directory and add the following code: -```javascript -const { App } = require('@slack/bolt'); +```javascript title="app.js" +const { App } = require("@slack/bolt"); -// Initializes your app with your bot token and signing secret +// Initializes your app with your Slack app and bot token const app = new App({ token: process.env.SLACK_BOT_TOKEN, - signingSecret: process.env.SLACK_SIGNING_SECRET, + socketMode: true, + appToken: process.env.SLACK_APP_TOKEN, }); (async () => { // Start your app - await app.start(process.env.PORT || 3000); + await app.start(); - app.logger.info('⚡️ Bolt app is running!'); + app.logger.info("⚡️ Bolt app is running!"); })(); ``` -Save your `app.js` file, then on the command line run the following: + + -```script -node app.js -``` +:::info[For local development, you can use a proxy service like [ngrok](https://ngrok.com/) to create a public URL and tunnel requests to your development environment.] -Your app should let you know that it's up and running. 🎉 +Refer to [ngrok's getting started guide](https://ngrok.com/docs/getting-started/) on how to create this tunnel. ---- +::: -## Setting up events {#setting-up-events} +First you'll need a signing secret to verify that the requests sent to your app are from Slack. -Your app behaves similarly to people on your team — it can post messages, add emoji reactions, and listen and respond to events. +1. Go to the **Basic Information** page on [app settings](https://api.slack.com/apps) and copy your Signing Secret to store in a new environment variable: -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](/apis/events-api/). +```sh +$ export SLACK_SIGNING_SECRET= +``` -For those just starting, we recommend using [Socket Mode](/apis/events-api/using-socket-mode/). Socket Mode allows your app to use the Events API and interactive features without exposing a public HTTP Request URL. This can be helpful during development, or if you're receiving requests from behind a firewall. +2. Create a new entrypoint file called `app.js` in your project directory and add the following code: -That being said, you're welcome to set up an app with a public HTTP Request URL. HTTP is more useful for apps being deployed to hosting environments (like [AWS](/tools/bolt-js/deployments/aws-lambda) or [Heroku](/tools/bolt-js/deployments/heroku)) to stably respond within a large corporate Slack workspaces/organization, or apps intended for distribution via the Slack Marketplace. +```javascript title="app.js" +const { App } = require("@slack/bolt"); -We've provided instructions for both ways in this guide. +// 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, +}); -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +(async () => { + // Start your app + await app.start(process.env.PORT || 3000); - - + app.logger.info("⚡️ Bolt app is running!"); +})(); +``` -1. Head to your app's configuration page (click on the app [from your app settings page](https://api.slack.com/apps)). Navigate to **Socket Mode** on the left side menu and toggle to enable. +3. Next let's start your app to receive events. Run the following command in the terminal: -2. Go to **Basic Information** and scroll down under the App-Level Tokens section and click **Generate Token and Scopes** to generate an app token. Add the `connections:write` scope to this token and save the generated `xapp` token, we'll use that in just a moment. +```sh +$ node app.js +``` -3. Finally, it's time to tell Slack what events we'd like to listen for. Under **Event Subscriptions**, toggle the switch labeled **Enable Events**. +Then enable events from app settings: -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. +4. Click **Event Subscriptions** on the left sidebar. Toggle the switch labeled **Enable Events**. +5. Add your [Request URL](/apis/events-api/#subscribing) and click **Save Changes**. Slack will send HTTP POST requests corresponding to events to this Request URL endpoint. - - +You can now stop the app by pressing `CTRL+C` in the terminal. -1. Go back to your app configuration page (click on the app from your [app settings page](https://api.slack.com/apps)). Click **Event Subscriptions** on the left sidebar. Toggle the switch labeled **Enable Events**. +:::warning[Can you hear me now?] -2. Add your Request URL. Slack will send HTTP POST requests corresponding to events to this [Request URL](/apis/events-api/#subscribing) 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:///slack/events`. 💡 +Bolt uses the `/slack/events` path to listen to all incoming requests (whether shortcuts, events, or interactivity payloads). -:::info[Using proxy services] +When configuring your Request URL within your app configuration, you'll append `/slack/events`: -For local development, you can use a proxy service like [ngrok](https://ngrok.com/) to create a public URL and tunnel requests to your development environment. Refer to [ngrok's getting started guide](https://ngrok.com/docs#getting-started-expose) on how to create this tunnel. +```text +https://example.ngrok.io/slack/events +``` ::: -Scroll down to **Subscribe to Bot Events**. There are four events related to messages: - -- [`message.channels`](/reference/events/message.channels) listens for messages in public channels that your app is added to. -- [`message.groups`](/reference/events/message.groups) listens for messages in 🔒 private channels that your app is added to. -- [`message.im`](/reference/events/message.im) listens for messages in your app's DMs with users. -- [`message.mpim`](/reference/events/message.mpim) listens for messages in multi-person DMs that your app is added to. +With the app constructed, save your `app.js` file. -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. +## Running the app {#running-the-app} - - +Now let's actually run your app! From the command line run the following: -Back in your project, make sure to store the `xapp` token you saved earlier in your environment. + + -```shell -export SLACK_APP_TOKEN=xapp- +```sh +$ slack run ``` -Change your Bolt initialization code and restart the app. + + -```javascript -// Initializes your app in socket mode with your app token and signing secret -const app = new App({ - token: process.env.SLACK_BOT_TOKEN, - signingSecret: process.env.SLACK_SIGNING_SECRET, - socketMode: true, // add this - appToken: process.env.SLACK_APP_TOKEN, // add this -}); +```sh +$ node app.js ``` - + -Carry on! +Your app should let you know that it's up and running. It's not actually listening for anything though. Let's change that. - - +Stop your app by pressing `CTRL+C` in the terminal then read on. ---- +## Subscribing to events {#subscribing-to-events} + +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 added to a message) you'll use the [Events API](/apis/events-api/) to subscribe to event types. + +Open [app settings](https://api.slack.com/apps) for your app and find the **Event Subscriptions** tab, toggle "Enable Events" on, then scroll down to **Subscribe to Bot Events**. There are four events related to messages: -## Listening and responding to a message {#listening-and-responding-to-a-message} +- [`message.channels`](/reference/events/message.channels) listens for messages in public channels that your app is added to +- [`message.groups`](/reference/events/message.groups) listens for messages in 🔒 private channels that your app is added to +- [`message.im`](/reference/events/message.im) listens for messages in your app's DMs with users +- [`message.mpim`](/reference/events/message.mpim) listens for messages in multi-person DMs that your app is added to -Your app is now ready for some logic. Let's start by using the `message()` method to attach a listener for messages. +If you want your bot to listen to messages from every conversation it's 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. -The following example listens and responds to all messages in channels/DMs where your app has been added that contain the word "hello": +You will also have to reinstall the app since new scopes are added for these events. Return to the **Install App** page to reinstall the app to your team. + +## Listening and responding to messages {#listening-and-responding-to-messages} + +Your app is now ready for some logic. Let's start by using the [`message`](/tools/bolt-js/concepts/message-listening) 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". Insert the highlighted lines into `app.js`. - + -```javascript -const { App } = require('@slack/bolt'); +```javascript title="app.js" +const { App } = require("@slack/bolt"); +// Initializes your app with your Slack app and bot token const app = new App({ token: process.env.SLACK_BOT_TOKEN, - signingSecret: process.env.SLACK_SIGNING_SECRET, socketMode: true, appToken: process.env.SLACK_APP_TOKEN, - // Socket Mode doesn't listen on a port, but in case you want your app to respond to OAuth, - // you still need to listen on some port! - port: process.env.PORT || 3000, }); +// highlight-start // Listens to incoming messages that contain "hello" -app.message('hello', async ({ message, say }) => { +app.message("hello", async ({ message, say }) => { // say() sends a message to the channel where the event was triggered await say(`Hey there <@${message.user}>!`); }); +// highlight-end (async () => { // Start your app await app.start(); - app.logger.info('⚡️ Bolt app is running!'); + app.logger.info("⚡️ Bolt app is running!"); })(); ``` - - + + -```javascript -const { App } = require('@slack/bolt'); +```javascript title="app.js" +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, }); +// highlight-start // Listens to incoming messages that contain "hello" -app.message('hello', async ({ message, say }) => { +app.message("hello", async ({ message, say }) => { // say() sends a message to the channel where the event was triggered await say(`Hey there <@${message.user}>!`); }); +// highlight-end (async () => { // Start your app await app.start(process.env.PORT || 3000); - app.logger.info('⚡️ Bolt app is running!'); + app.logger.info("⚡️ Bolt app is running!"); })(); ``` - + -If you restart your app, so long as your bot user has been added to the channel or DM conversation, when you send any message that contains "hello", it will respond. +Then restart your app. So long as your bot user has been added to the conversation, it will respond when you send any message that contains "hello". 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 {#sending-and-responding-to-actions} -To use features like buttons, select menus, datepickers, modals, and shortcuts, you’ll need to enable interactivity. Head over to **Interactivity & Shortcuts** in your app configuration. +To use features like buttons, select menus, datepickers, modals, and shortcuts, you’ll need to enable interactivity. -With Socket Mode on, basic interactivity is enabled for us by default, so no further action here is needed +With Socket Mode on, basic interactivity is enabled for us by default, so no further action here is needed. Similar to events, you'll need to specify a Request URL for Slack to send the action (such as _user clicked a button_). -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! +Head over to **Interactivity & Shortcuts** in app settings. + +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://example.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! @@ -307,26 +434,24 @@ 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: +Below, the `app.js` file from the last section is modified to send a message containing a button rather than just a string. Update the highlighted lines as shown: - + -```javascript -const { App } = require('@slack/bolt'); +```javascript title="app.js" +const { App } = require("@slack/bolt"); +// Initializes your app with your Slack app and bot token const app = new App({ token: process.env.SLACK_BOT_TOKEN, - signingSecret: process.env.SLACK_SIGNING_SECRET, socketMode: true, appToken: process.env.SLACK_APP_TOKEN, - // Socket Mode doesn't listen on a port, but in case you want your app to respond to OAuth, - // you still need to listen on some port! - port: process.env.PORT || 3000, }); +// highlight-start // Listens to incoming messages that contain "hello" -app.message('hello', async ({ message, say }) => { +app.message("hello", async ({ message, say }) => { // say() sends a message to the channel where the event was triggered await say({ blocks: [ @@ -349,28 +474,31 @@ app.message('hello', async ({ message, say }) => { text: `Hey there <@${message.user}>!`, }); }); +// highlight-end (async () => { // Start your app await app.start(); - app.logger.info('⚡️ Bolt app is running!'); + app.logger.info("⚡️ Bolt app is running!"); })(); ``` - - + + -```javascript -const { App } = require('@slack/bolt'); +```javascript title="app.js" +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, }); +// highlight-start // Listens to incoming messages that contain "hello" -app.message('hello', async ({ message, say }) => { +app.message("hello", async ({ message, say }) => { // say() sends a message to the channel where the event was triggered await say({ blocks: [ @@ -393,52 +521,54 @@ app.message('hello', async ({ message, say }) => { text: `Hey there <@${message.user}>!`, }); }); +// highlight-end (async () => { // Start your app await app.start(process.env.PORT || 3000); - app.logger.info('⚡️ Bolt app is running!'); + app.logger.info("⚡️ 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. +The value inside of `say()` is now an object that contains an array of `blocks`. [Blocks](/block-kit) 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. -:::tip[Using Block Kit Builder] +:::tip[Use [Block Kit Builder](https://app.slack.com/block-kit-builder) to prototype your interactive messages.] -The [Block Kit Builder](https://app.slack.com/block-kit-builder) is a simple way to prototype your interactive messages. The builder lets you (or anyone on your team) mock up messages and generates the corresponding JSON that you can paste directly in your app. +Block Kit Builder lets you (or anyone on your team) mock up 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: +Let's add a handler to send a follow-up message when someone clicks the button. Add the following highlighted lines to `app.js`: - + -```js reference +```js reference {41-45} https://github.com/slack-samples/bolt-js-getting-started-app/blob/main/app.js ``` - - + + -```javascript -const { App } = require('@slack/bolt'); +```javascript title="app.js" +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, }); // Listens to incoming messages that contain "hello" -app.message('hello', async ({ message, say }) => { +app.message("hello", async ({ message, say }) => { // say() sends a message to the channel where the event was triggered await say({ blocks: [ @@ -462,37 +592,33 @@ app.message('hello', async ({ message, say }) => { }); }); -app.action('button_click', async ({ body, ack, say }) => { +// highlight-start +app.action("button_click", async ({ body, ack, say }) => { // Acknowledge the action await ack(); await say(`<@${body.user.id}> clicked the button`); }); +// highlight-end (async () => { // Start your app await app.start(process.env.PORT || 3000); - app.logger.info('⚡️ Bolt app is running!'); + app.logger.info("⚡️ 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. - ---- +We used `app.action()` to listen for the `action_id` that we named `button_click`. Restart your app, and then click the button; you'll see a new message from your app that says you clicked the button. ## Next steps {#next-steps} -You just built your first [Bolt for JavaScript app](https://github.com/slack-samples/bolt-js-getting-started-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 concepts pages 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()`](/tools/bolt-js/concepts/event-listening) method. All of the events are listed on the [API docs site](/reference/events). +You just built a [Bolt for JavaScript app](https://github.com/slack-samples/bolt-js-getting-started-app)! 🎉 -- Bolt allows you to [call Web API methods](/tools/bolt-js/concepts/web-api) with the client attached to your app. There are [over 200 methods](/reference/methods) on the API docs site. +Now that you have an app up and running, you can start exploring how to make your Bolt app truly yours. Here are some ideas about what to explore next: -- Learn more about the different token types [on the API docs site](/authentication/tokens). Your app may need different tokens depending on the actions you want it to perform. +- Read through the various concepts pages to learn about the different methods and features accessible to your Bolt app. +- Explore the different events your bot can listen to with the [`event`](/tools/bolt-js/concepts/event-listening) method. [View all of the events within the API docs](/reference/events). +- The Bolt framework allows you to [call Web API methods](/tools/bolt-js/concepts/web-api) with the client attached to your app. [View the over 200 methods within the API docs](/reference/methods). diff --git a/docs/english/concepts/message-listening.md b/docs/english/concepts/message-listening.md index ab24afade..7b4adb156 100644 --- a/docs/english/concepts/message-listening.md +++ b/docs/english/concepts/message-listening.md @@ -1,6 +1,6 @@ # Listening to messages -To listen to messages that [your app has access to receive](https:///messaging/retrieving#permissions), you can use the `message()` method which filters out events that aren’t of type `message` .A `message()` listener is equivalent to `event('message')` +To listen to messages that [your app has access to receive](/messaging/retrieving-messages/#permissions), you can use the `message()` method which filters out events that aren’t of type `message`. A `message()` listener is equivalent to `event('message')`. The `message()` listener accepts an optional `pattern` parameter of type `string` or `RegExp` object which filters out any messages that don’t match the pattern. diff --git a/docs/english/deployments/aws-lambda.md b/docs/english/deployments/aws-lambda.md index f3007e6d3..34b6e9733 100644 --- a/docs/english/deployments/aws-lambda.md +++ b/docs/english/deployments/aws-lambda.md @@ -18,7 +18,7 @@ When you’re finished, you’ll have this ⚡️[Deploying to AWS Lambda app](h If you don't already have an account, you should [sign up for AWS](https://aws.amazon.com/) and follow the on-screen instructions. -:::info +:::info You may be asked for payment information during the sign up. Don't worry, this guide only uses the [free tier](https://aws.amazon.com/lambda/pricing/). @@ -30,7 +30,7 @@ Next, you'll need programmatic access to your AWS account to deploy onto Lambda. We recommend watching this short, step-by-step video to 🍿 [create an IAM user and download the access keys](https://www.youtube.com/watch?v=KngM5bfpttA). -:::tip[Do you already have an IAM user?] +:::tip[Do you already have an IAM user?] Follow the official AWS guide to [create access keys for existing IAM users](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds). @@ -82,10 +82,10 @@ You're now set up with the Serverless tools! Let's move on to preparing your Bol ## Get a Bolt Slack app {#get-a-bolt-slack-app} -If you haven't already built your own Bolt app, you can use our [Getting Started guide](/tools/bolt-js/getting-started) or clone the template app below: +If you haven't already built your own Bolt app, you can use our [Quickstart guide](/tools/bolt-js/getting-started) or clone the template app below: ```shell -git clone https://github.com/slackapi/bolt-js-getting-started-app.git +git clone https://github.com/slack-samples/bolt-js-getting-started-app.git ``` After you have a Bolt app, navigate to its directory: @@ -115,7 +115,7 @@ const app = new App({ Next, we'll customize your Bolt app's [`receiver`](/tools/bolt-js/concepts/receiver) to respond to Lambda function events. -Update the [source code that imports your modules](https://github.com/slackapi/bolt-js-getting-started-app/blob/4c29a21438b40f0cbca71ece0d39b356dfcf88d5/app.js#L1) in `app.js` to require Bolt's AwsLambdaReceiver: +Update the [source code that imports your modules](https://github.com/slack-samples/bolt-js-getting-started-app/blob/4c29a21438b40f0cbca71ece0d39b356dfcf88d5/app.js#L1) in `app.js` to require Bolt's AwsLambdaReceiver: ```javascript const { App, AwsLambdaReceiver } = require('@slack/bolt'); @@ -127,7 +127,7 @@ If implementing authentication with OAuth, you must use the [`ExpressReceiver`]( ::: -Then update the [source code that initializes your Bolt app](https://github.com/slackapi/bolt-js-getting-started-app/blob/4c29a21438b40f0cbca71ece0d39b356dfcf88d5/app.js#L10-L14) to create a custom receiver using AwsLambdaReceiver: +Then update the [source code that initializes your Bolt app](https://github.com/slack-samples/bolt-js-getting-started-app/blob/4c29a21438b40f0cbca71ece0d39b356dfcf88d5/app.js#L10-L14) to create a custom receiver using AwsLambdaReceiver: ```javascript // Initialize your custom receiver @@ -151,7 +151,7 @@ const app = new App({ }); ``` -Finally, at the bottom of your app, update the [source code that starts the HTTP server](https://github.com/slackapi/bolt-js-getting-started-app/blob/main/app.js#L47-L52) to now respond to an AWS Lambda function event: +Finally, at the bottom of your app, update the [source code that starts the HTTP server](https://github.com/slack-samples/bolt-js-getting-started-app/blob/main/app.js#L47-L52) to now respond to an AWS Lambda function event: ```javascript // Handle the Lambda function event @@ -189,11 +189,11 @@ plugins: - serverless-offline ``` -:::info +:::info `SLACK_SIGNING_SECRET` and `SLACK_BOT_TOKEN` must be environment variables on your local machine. -You can [learn how to export Slack environment variables](/tools/bolt-js/getting-started#setting-up-your-project) in our Getting Started guide. +You can [learn how to export Slack environment variables](/tools/bolt-js/getting-started#creating-a-project) in our Quickstart guide. ::: @@ -233,9 +233,9 @@ Next, use ngrok to forward Slack events to your local machine: ngrok http 3000 ``` -:::info +:::info -[Learn how to use ngrok](/tools/bolt-js/getting-started#setting-up-events) to create a public URL and forward requests to your local machine. +[Learn how to use ngrok](/tools/bolt-js/building-an-app#preparing-receive-events) to create a public URL and forward requests to your local machine. ::: @@ -255,7 +255,7 @@ Second, select **Event Subscriptions** from the side and update the **Request UR ### 3. Test your Slack app -Now you can test your Slack app by inviting your app to a channel then saying “hello” (lower-case). Just like in the [Getting Started guide](/tools/bolt-js/getting-started), your app should respond back: +Now you can test your Slack app by inviting your app to a channel then saying “hello” (lower-case). Just like in the [Quickstart guide](/tools/bolt-js/getting-started#running-the-app), your app should respond back: ``` > 👩‍💻 hello @@ -360,4 +360,4 @@ Now that you've built and deployed a basic app, here are some ideas you can expl - Brush up on [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) and the [Serverless Framework](https://www.serverless.com/framework/docs/providers/aws/guide/intro/). - Extend your app with other Bolt capabilities and [Serverless plugins](https://www.serverless.com/framework/docs/providers/aws/guide/plugins/). - Learn about [logging](/tools/bolt-js/concepts/logging) and how to [view log messages with Serverless](https://www.serverless.com/framework/docs/providers/aws/cli-reference/logs/). -- Get ready for primetime with AWS Lambda [testing](https://www.serverless.com/framework/docs/providers/aws/guide/testing/) and [deployment environments](https://www.serverless.com/framework/docs/providers/aws/guide/deploying/). \ No newline at end of file +- Get ready for primetime with AWS Lambda [testing](https://www.serverless.com/framework/docs/providers/aws/guide/testing/) and [deployment environments](https://www.serverless.com/framework/docs/providers/aws/guide/deploying/). diff --git a/docs/english/deployments/heroku.md b/docs/english/deployments/heroku.md index 69e5431a5..a21d8cccf 100644 --- a/docs/english/deployments/heroku.md +++ b/docs/english/deployments/heroku.md @@ -6,7 +6,7 @@ When you’re finished, you’ll have this ⚡️[Deploying to Heroku app](https :::warning - Using Heroku dynos to complete this tutorial counts towards your usage. [Delete your app](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-apps-destroy) as soon as you are done to control costs. +Using Heroku dynos to complete this tutorial counts towards your usage. [Delete your app](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-apps-destroy) as soon as you are done to control costs. ::: @@ -14,10 +14,10 @@ When you’re finished, you’ll have this ⚡️[Deploying to Heroku app](https ## Get a Bolt Slack app {#get-a-bolt-slack-app} -If you haven't already built your own Bolt app, you can use our [Getting Started guide](/tools/bolt-js/getting-started) or clone the template app below: +If you haven't already built your own Bolt app, you can use our [Quickstart guide](/tools/bolt-js/getting-started) or clone the template app below: ```shell -git clone https://github.com/slackapi/bolt-js-getting-started-app.git +git clone https://github.com/slack-samples/bolt-js-getting-started-app.git ``` After you have a Bolt app, navigate to its directory: @@ -36,7 +36,7 @@ Heroku is a flexible platform that requires some configuration to host your app. ### 1. Use a Git repository -:::info +:::info Skip this step if you used `git clone` in the previous section because you already have a Git repository. @@ -69,7 +69,7 @@ git add Procfile git commit -m "Add Procfile" ``` -:::info +:::info Are you following this guide with an existing Bolt app? If so, please review the guide on [preparing a codebase for Heroku](https://devcenter.heroku.com/articles/preparing-a-codebase-for-heroku-deployment#4-listen-on-the-correct-port) to listen on the correct port. @@ -106,7 +106,8 @@ The Heroku CLI connects your local machine with your Heroku account. [Sign up fo ```shell heroku login ``` -:::warning + +:::warning If you're behind a firewall, you may need to [set the proxy environment variables](https://devcenter.heroku.com/articles/using-the-cli#using-an-http-proxy) for the Heroku CLI. @@ -181,9 +182,9 @@ heroku config:set SLACK_SIGNING_SECRET= heroku config:set SLACK_BOT_TOKEN=xoxb- ``` -:::info +:::info -If you don't know where to find your credentials, please read about [exporting your signing secret and token](/tools/bolt-js/getting-started#tokens-and-installing-apps) in the Getting Started guide. +If you don't know where to find your credentials, please read about [exporting your signing secret and token](/tools/bolt-js/building-an-app#preparing-receive-events) in the Building an app guide. ::: @@ -205,7 +206,7 @@ You can now deploy your app with the command: git push heroku main ``` -:::info +:::info Heroku deploys code that's pushed to the [master or main branches](https://devcenter.heroku.com/articles/git-branches). Pushing to other branches will not trigger a deployment. @@ -253,7 +254,7 @@ Second, select **Event Subscriptions** from the side and update the **Request UR Your app is now deployed and Slack is updated, so let's try it out! -Open a Slack channel that your app has joined and say "hello" (lower-case). Just like in the [Getting Started guide](/tools/bolt-js/getting-started#sending-and-responding-to-actions), your app should respond back. If you don't receive a response, check your **Request URL** and try again. +Open a Slack channel that your app has joined and say "hello" (lower-case). Just like in the [Quickstart guide](/tools/bolt-js/getting-started#running-the-app), your app should respond back. If you don't receive a response, check your **Request URL** and try again. --- @@ -296,4 +297,4 @@ Now that you've deployed a basic app, you can start exploring how to customize a - Brush up on [how Heroku works](https://devcenter.heroku.com/articles/how-heroku-works) and understand the [limitations of a Heroku Eco Dyno app](https://devcenter.heroku.com/articles/eco-dyno-hours). - Extend your app with with other Bolt capabilities and and [Heroku's Add-ons](https://elements.heroku.com/addons). - Learn about [logging](/tools/bolt-js/concepts/logging) and how to [view log messages in Heroku](https://devcenter.heroku.com/articles/getting-started-with-nodejs#view-logs). -- Get ready for primetime with [how to scale your Heroku app](https://devcenter.heroku.com/articles/getting-started-with-nodejs#scale-the-app). \ No newline at end of file +- Get ready for primetime with [how to scale your Heroku app](https://devcenter.heroku.com/articles/getting-started-with-nodejs#scale-the-app). diff --git a/docs/english/getting-started.md b/docs/english/getting-started.md index 756ba8515..fbd180694 100644 --- a/docs/english/getting-started.md +++ b/docs/english/getting-started.md @@ -6,9 +6,6 @@ sidebar_label: Quickstart This quickstart guide aims to help you get a Slack app using Bolt for JavaScript up and running as soon as possible! -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - When complete, you'll have a local environment configured with a customized [app](https://github.com/slack-samples/bolt-js-getting-started-app) running that responds to a simple greeting. :::tip[Reference for readers] diff --git a/docs/english/index.md b/docs/english/index.md index ddf29a6cf..31666d7e1 100644 --- a/docs/english/index.md +++ b/docs/english/index.md @@ -1,6 +1,6 @@ # Bolt for JavaScript -Bolt for JavaScript is a JavaScript framework to build Slack apps with the latest Slack platform features. Read the [Getting Started Guide](/tools/bolt-js/getting-started) to set up and run your first Bolt app. +Bolt for JavaScript is a JavaScript framework to build Slack apps with the latest Slack platform features. Read the [Quickstart Guide](/tools/bolt-js/getting-started) to set up and run your first Bolt app. Then, explore the rest of the pages within the Guides section. The documentation there will help you build a Bolt app for whatever use case you may have. @@ -18,4 +18,4 @@ If you otherwise get stuck, we're here to help. The following are the best ways These docs live within the [Bolt-JS](https://github.com/slackapi/bolt-js/) repository and are open source. We welcome contributions from everyone! Please check out our -[Contributor's Guide](https://github.com/slackapi/bolt-js/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way. \ No newline at end of file +[Contributor's Guide](https://github.com/slackapi/bolt-js/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way. diff --git a/docs/english/legacy/hubot-migration.md b/docs/english/legacy/hubot-migration.md index b205b7259..00c5da876 100644 --- a/docs/english/legacy/hubot-migration.md +++ b/docs/english/legacy/hubot-migration.md @@ -47,14 +47,14 @@ The [Events API](/legacy/legacy-bot-users#handling-events) is a bot's equivalent :::info -Before you configure your bot’s events, you’ll need a public URL. If you’ve never created a Bolt for JavaScript app or never used the Events API, it’d be helpful to go through [setting up your local Bolt project](/tools/bolt-js/getting-started) and [setting up events](/tools/bolt-js/getting-started#setting-up-events) in the Getting Started guide. +Before you configure your bot’s events, you’ll need a public URL. If you’ve never created a Bolt for JavaScript app or never used the Events API, it’d be helpful to go through [setting up your local Bolt project](/tools/bolt-js/building-an-app) and [setting up events](/tools/bolt-js/building-an-app#preparing-receive-events) in the Getting Started guide. ::: ### Listening for messages All Hubot apps can listen to messages by default, so we need to configure your bot user to do the same. -After walking through [setting up events](/tools/bolt-js/getting-started#setting-up-events), your Request URL should be verified. Scroll down to **Subscribe to Bot Events**. There are four events related to messages: `message.channels` (listens for messages in public channels), `message.groups` (listens for messages in private channels), `message.im` (listens for messages in the App Home/DM space), and `message.mpim` (listens for messages in multi-person DMs). +After walking through [setting up events](/tools/bolt-js/building-an-app#preparing-receive-events), your Request URL should be verified. Scroll down to **Subscribe to Bot Events**. There are four events related to messages: `message.channels` (listens for messages in public channels), `message.groups` (listens for messages in private channels), `message.im` (listens for messages in the App Home/DM space), and `message.mpim` (listens for messages in multi-person DMs). If you only want your bot to listen to messages in channels, you can listen to `message.channels` and `message.groups`. Or if you want your bot to listen to messages from everywhere it is, choose all four message events. diff --git a/docs/english/reference.md b/docs/english/reference.md index f32fee2b0..01f51fe64 100644 --- a/docs/english/reference.md +++ b/docs/english/reference.md @@ -4,7 +4,7 @@ sidebar_label: Reference # Bolt for JavaScript interface and configuration reference -This guide is intended to detail the Bolt interface–including listeners and their arguments, initialization options, and errors. It may be helpful to first go through the ⚡️[Getting Started guide](/tools/bolt-js/getting-started) to learn the basics of building Bolt for JavaScript apps. +This guide is intended to detail the Bolt interface–including listeners and their arguments, initialization options, and errors. It may be helpful to first go through the ⚡️[Building an app guide](/tools/bolt-js/building-an-app) to learn the basics of building Bolt for JavaScript apps. --- diff --git a/docs/english/tutorials/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md b/docs/english/tutorials/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md index cd1891a4d..78fea7d3d 100644 --- a/docs/english/tutorials/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md +++ b/docs/english/tutorials/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md @@ -68,7 +68,7 @@ All of your app's settings can be configured within these screens. By creating a Navigate to **Event Subscriptions** and expand **Subscribe to bot events** to see that we have subscribed to the `function_executed` event. This is also a requirement for adding workflow steps to our app, as it lets our app know when a step has been triggered, allowing our app to respond to it. -Another configuration setting to note is **Socket Mode**. We have turned this on for our local development, but socket mode is not intended for use in a production environment. When you are satisfied with your app and ready to deploy it to a production environment, you should switch to using public HTTP request URLs. Read more about getting started with HTTP in [Bolt for JavaScript here](/tools/bolt-js/getting-started). +Another configuration setting to note is **Socket Mode**. We have turned this on for our local development, but socket mode is not intended for use in a production environment. When you are satisfied with your app and ready to deploy it to a production environment, you should switch to using public HTTP request URLs. Read more about getting started with HTTP in [Bolt for JavaScript here](/tools/bolt-js/building-an-app). Clicking on **Workflow Steps** in the left nav will show you that one workflow step has been added! This reflects the `function` defined in our manifest: functions are workflow steps. We will get to this step's implementation later. diff --git a/docs/japanese/getting-started.md b/docs/japanese/getting-started.md index e0fb231cf..ef095d977 100644 --- a/docs/japanese/getting-started.md +++ b/docs/japanese/getting-started.md @@ -131,9 +131,6 @@ node app.js Slack ワークスペースで発生するイベント（メッセージが投稿されたときや、メッセージに対するリアクションがつけられたときなど）をリッスンするには、[Events API を使って特定の種類のイベントをサブスクライブします](/apis/events-api/)。 -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -