/bolt-starter

A Bolt ⚡️ app template with useful settings for easier development

Primary LanguageJavaScriptMIT LicenseMIT

Getting started with Bolt ⚡️

This is a simple Slack's Bolt⚡️ app template. This README covers the following ways to start building your awesome Slack apps.

  • CodeSandbox: Step 1 -> Step 2A
  • Glitch: Step 1 -> Step 2B
  • On your local machine (Linux/macOS/Windows): Step 1 -> Step 2C

(Step 1) Slack App Initial Setup

Create a Slack App

Start with creating a new Slack app from https://api.slack.com/apps

Configure Bot Scopes

Access Features > OAuth & Permissions from the left sidebar and set the followings.

https://api.slack.com/apps/{APP_ID}/oauth

  • app_mentioned:read
  • chat:write
  • commands

Install the app to your workspace

Access Settings > Install App from the left sidebar. You'll configure more later but let's install the app anyway to get a bot token (xoxb-***).

https://api.slack.com/apps/{APP_ID}/install-on-team

(Step 2A) CodeSandbox Setup

Sign in with your GitHub account

https://codesandbox.io/

As of December 2019, CodeSandbox allows logging in with only GitHub accounts. You need to login with your own GitHub account.

Create a new sandbox

It's pretty simple. Create a new sandbox by importing this repostiory. The steps are:

  • Click Create Sandbox
  • Go to Import tab
  • Put https://github.com/seratch/bolt-starter in the textbox
  • Click Open Sandbox

Then, fork the template project to create your own sandbox:

In your own sandbox project, configure secrets as below:

  • SLACK_SIGNING_SECRET: Use the value you can find at Basic Information > App Credentials > Signing Secret
  • SLACK_BOT_TOKEN: Use the Bot User OAuth Access Token (starting with xoxb-) you can find at Settings > Install App

That's all! If your changes are not reflected to the running sandbox, click Restart Sandbox button.

Set Request URLs (Slack App)

You must see https://{random}.sse.codesandbox.io/ URL in the right pane on CodeSandbox.

You can go with https://{random}.sse.codesandbox.io/slack/events for all of the Slack App Request URLs.

You need to configure the following three settings with the URL.

  • Interactive Components: Turn on first, set the Request URL, and then click "Save Changes" button
  • Slash Commands: Add /open-modal command with the above URL for Reequest URL
  • Event Subscriptions: Turn on first, set the Request URL, add app_mention in Bot Events, and then click "Save Changes" button

Re-install Slack App to your workspace

https://api.slack.com/apps/{APP_ID}/install-on-team

(Step 2B) Glitch Setup

https://glitch.com/

Create a Glitch project

The steps are similar to CodeSandbox.

After creating a project, duplicate _env file and name it as .env. The file named .env will be automatically marked as a secret file.

After modifying .env file, make sure if the app is running without any problems by checking the logs.

Set Request URLs (Slack App)

You must see https://{some-fancy-name}.glitch.me/ URL in the Live App settings on Glitch.

You can go with https://{some-fancy-name}.glitch.me/slack/events for all of the Slack App Request URLs.

  • https://api.slack.com/apps/{APP_ID}/event-subscriptions
  • https://api.slack.com/apps/{APP_ID}/slash-commands
  • https://api.slack.com/apps/{APP_ID}/interactive-messages

Re-install Slack App to your workspace

https://api.slack.com/apps/{APP_ID}/install-on-team

(Step 2C) Your Local Machine Setup

ngrok Setup

https://ngrok.com/

ngrok http 3000

If you have a paid license, you can configure a fixed subdomain.

ngrok http 3000 --subdomain your-awesome-subdomain

Node Version Manager (nvm) Setup

Linux / macOS

Windows

  • Install nvm-windows from here
  • mvn list available to check the available versions
  • nvm install {latest LTS} (installing latest LTS version)

If you go with WSL, follow the same steps in Linux / macOS.

Start with this template

Or it's also possible to download this project template:

git clone git@github.com:seratch/bolt-starter.git or https://github.com/seratch/bolt-starter/archive/master.zip

Run the app

cd bolt-starter
cp _env .env
# edit .env
npm i
npm run local

Set Request URLs (Slack App)

Set https://{your-awesome-subdomain}.ngrok.io/slack/events to all of the followings:

  • https://api.slack.com/apps/{APP_ID}/slash-commands
  • https://api.slack.com/apps/{APP_ID}/event-subscriptions
  • https://api.slack.com/apps/{APP_ID}/interactive-messages

Slash Commands

Access Features > Slash Commands from the left sidebar. Create a slash command named /open-modal.

https://api.slack.com/apps/{APP_ID}/slash-commands

  • Command: /open-modal
  • request URL: https://{your-awesome-subdomain}.ngrok.io/slack/events
  • Short Description: whatever you like
  • Click "Save" for sure

Configure Event Subscriptions

Access Features > Event Subscriptions from the left sidebar. Add an event subscription for app_mention events and click "Save Changes" button for sure..

https://api.slack.com/apps/{APP_ID}/event-subscriptions

  • app_mention

Configure Interactivity

Access Features > Interactivity & Shortcuts from the left sidebar. Set the Request URL for Interactity and click "Save Changes" button for sure.

https://api.slack.com/apps/{APP_ID}/interactive-messages

Global Shortcuts

Access Features > Interactivity & Shortcuts > Shortcuts from the left sidebar. Create a new global shortcut with Callback ID open-modal.

  • Name: whatever you like
  • Short Description: whatever you like
  • Callback ID: open-modal
  • Click "Create"

Re-install the app to your workspace

https://api.slack.com/apps/{APP_ID}/install-on-team

License

The MIT License