Hello World Slack app using Bolt

Beginner

In this tutorial you will learn how to create a Hello World Slack app using the Bolt framework. The app will send a ‘Hello world’ message when a user clicks into the app’s Home Tab.

To get started, you'll need to create a Slack app. You have a couple of options.

  1. Create your app from scratch, begin with Step #1. You will create your Slack app, request scopes, enable Socket mode and install your app.

  2. We set up an app manifest with the necessary permissions you'll need for this track. You'll create an app following the prompts after the button below. When you're done creating and installing your app, follow the banner back to this tutorial and start at Step #2.

Pick your contender and continue to create greatness.

Features you’ll use

Scopes you'll request

Events you'll listen for

Create a pre-configured app

Quickly create an app with the correct configuration of scopes and features for this tutorial by clicking below.

Step 1Create and Install your app

  • Create an app

    You won't get far without a Slack app to accompany you on this journey. Start here by creating an app.

  • Use Bolt to build your app

    Bolt is a framework that lets you build Slack apps in a flash—available in JavaScript, Python, and Java.

    Bolt handles much of the foundational setup so you can focus on your app's functionality. Out of the box, Bolt includes:

    • A basic web server to run your app on
    • Authentication and installation handling for all the ins and outs of OAuth
    • Simplified interfaces for all Slack APIs and app features
    • Automatic token validation, retry, and rate-limiting logic

    Bolt also has built-in type support, so you can get more work done right from your code editor.

    Follow our guides on getting started with Bolt for JavaScript, Bolt for Python, or Bolt for Java. Or dig deeper by exploring our resources and sample code.

  • Requesting scopes for your app

    Scopes give your app permission to do things (for example, post messages) in Slack. They're an essential component of any functional Slack app.

    Each scope that you add to your app will be presented in a permission request dialog during app installation. When you're building an app in a development workspace that you control, you'll be able to experience both sides of this system.

    Each app can use lots of different scopes, with the exact list depending on the type of access token the app will use. We favour using bot tokens for most apps, so we'll explain how to request scopes for that token type.

    To choose the scopes to add to your app:

    1. Head over to app settings page for your app.
    2. Navigate to the OAuth & Permissions page.
    3. Scroll down to the Bot Token Scopes section.
    4. Click Add an OAuth Scope.
    5. Add the scopes listed above.

    Once added, the scope list will be saved automatically. Your app will now request these scopes during installation.

    If you add scopes to your app settings after installation, reinstall your app to request and grant permission for the added scopes.

    To read more about scopes and permissions, check out our app authentication docs.

  • Install your app

    Your app can request any scope you want—but final say always resides with the user installing your app. A user can choose to refuse any and all installs that seem to request permissions beyond what they're comfortable granting.

    When you're installing your app to your own development workspace, you can experience this process for yourself.

    To install your app to your development workspace:

    1. Head over to app settings page for your app.
    2. Navigate to the Install App page.
    3. Click Install to Workspace.

    You'll be redirected to the OAuth permission request dialog:

    Oauth UI for users

    As a user, you're choosing to trust the app. Is it trustworthy? Well, you're building it—hopefully, it's not too bad. After installation, you'll be redirected back to your app settings. You'll see the newly generated access token on the Install App page you're redirected to.

    Access tokens are imbued with power. Your app is able to use this new access token to do practically everything that a Slack app can do.

    Remember to keep your access token secret and safe, to avoid violating the security of your app, and to maintain the trust of your app's users.

    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.

  • Enabling Socket Mode for your app

    Socket Mode allows your app to use the Events API and interactive featureswithout exposing a public HTTP Request URL.

    Instead of sending payloads to a public endpoint, Slack will use a WebSocket URL to communicate with your app. WebSockets use a bidirectional stateful protocol with low latency to communicate between two parties—in this case, Slack and your app.

    Unlike a public HTTP endpoint, the WebSocket URL you listen to is not static. The URL is created at runtime by calling the apps.connections.open method, and it refreshes regularly.

    Socket Mode helps developers working behind a corporate firewall, or who have other security concerns that don't allow exposing a static HTTP endpoint.

    You can still switch between a direct HTTP endpoint and Socket Mode at any time in the app settings.

    We recommend using our Bolt frameworks or SDKs for Java, Javascript, or Python to handle the details of Socket Mode. The process is streamlined, and you get access to all the other pleasant features of our SDKs.

    Within your app's configuration, journey to the left navigation and toggle on Socket Mode. This will prompt you to create an app level token. Give your token a name and ensure that it can access the connections.write scope.

Step complete!

Step 2Using Glitch to host your app

  • Using Glitch to host

    You can host your Slack app in a few different ways for both development and production.

    For app development we recommend either Glitch or ngrok. Both of these methods allow for streamlined testing of your Slack app in development. This track uses Glitch, a tool that simplifies building and hosting apps. While a free Glitch account is great for development, your server won’t stay running while your app is idle. This means you need to keep Glitch open in your browser while you develop and test your app.

    Click here to remix(clone) the Bolt Hello World project.

    When your app is production-ready, you may want to host it elsewhere or upgrade your Glitch account.

    Once you've remixed the Glitch project you should have a Slack app with the following;

    • .env: This is used to store your app's secret tokens. These allow Slack to recognize your app when listening for events.
    • app.js: This is where the logic and instantiation for your app lives.
    • package.json: This file specifies the version of Bolt and other app requirements.

    Now, lets add in your environment variables to the .env file.

    1. Signing Secret

      • Head to your Slack app settings page on the API site.
      • Click OAuth & Permissions from the sidebar.
      • Click Copy to copy your Bot User OAuth Access Token over to your .env file.
    2. Slack Bot Token

      • Click Basic Information from the sidebar.
      • Scroll down to the App Credentials section.
      • Copy your Signing Secret over to your .env file.
    3. Slack App Token

      • Scroll down to App Level Tokens, click into your app level token.
      • Copy your xapp-- token over to your .env file.
Step complete!

Step 3Coding with Bolt

  • Setup app event

    We want your app to listen for an event and respond with a "Hello World" message. You will use clicking into the App Home as the trigger event.

    An event in Slack can be anything. A click of a button. A DM. Or even the creation of a channel. Check out the different types of events your Slack app can listen for.

    Your app will listen for app_home_opened which signifies a user clicking into your app's Home tab.

    Let's set up a couple more line items within your app's configuration page.

    1. Head back to your Slack app settings page on the Slack API site.

      • Click App Home from the sidebar.
      • Toggle on Home Tab
    2. Next you will click on Event Subscriptions from the sidebar.

      • Your events should be enabled, if they aren't toggle it on.
      • Click into Subscribe to bot events and add in app_home_opened.

    Now we have enabled your app to listen for the app_home_opened event!

    Read more about the countless events your app can listen for.

    Next we will jump back into your Glitch code to add logic on how to utilize this functionality.

  • Add app event listener

    Your Slack app is almost to the finish line!🏁

    Now you will add in an event listener for your app to act upon the app_home_opened event.

    Slack apps typically receive and respond to one to many requests from Slack. For each type of incoming request from Slack, there is a corresponding listener function to handle and respond.

    Here is a subset of the listeners Bolt apps can pass a function to.

    Listener Description
    app.event(eventType, fn) Listens for Events API events. The eventType is a string used to identify the specific event.
    app.message([pattern ,], fn) Convenience listener to handle events of type message. The pattern can be any substring or RegExp expression.
    app.action(actionId, fn) Listens for interactive events from a Block element such as a user interaction with a button. The actionId identifier is a string that matches a block element’s action_id.
    app.shortcut(callbackId, fn) Listens for global and message shortcut invocations. The callbackId is a string or RegExp pattern that matches a shortcut’s callback_id, which is specified in the app configuration.
    ````

    Your app will use the app.event(eventType, fn) listener function. Lets add this listener to your app.js, below your app instantiation. The eventType will be app_home_opened and fn will be say() in order for your app to say a message.

    Add in this app event listener function to your app.js.

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

    Glitch will autosave your changes and your app should automatically restart. You can now click into your app's Home tab and receive a Hello World message!

Step complete!

Step 4Finishing up

  • Growing your Slack app

    You've just completed your first Slack app using Bolt for Javascript and Socket Mode.🎉 The journey's just beginning.

    • 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.

    There numerous ways for your Bolt Slack app to grow such as interactivity or Block Kit. You can also continue to explore with other tracks.

Step complete!