This repository is the workshop material for Apidays live Singapore. If you're not an attendee of the workshop, don't worry! You can try this sample project just by reading this.

This project template is available at git.io/apidays-slack (https://github.com/seratch/apidays-workshop-2020). Use the shortened URL for sharing this material with others!

In this workshop, we're going to build a helpdesk workflow app from scratch. Building the app helps us learn how to start Slack App development and utilize the latest Slack Platform features.

Here is the quick demo of the complete version of the helpdesk workflow:

When an end-user clicks a shortcut from the text composer (or the search bar), a modal window pops up.

When the user selects a category from the select menu, the modal immediately transforms itself to show input fields for the chosen category. Also, "Back" button in the modal allows the user to go back to the initial step.

The app applies custom input validation rules for the title and due-date inputs.

When the app receives a valid data submission from the user, the app sends notifications to the helpdesk team's channel, the DM with the submitter, and the DM with the approver (only for mobile device requests). In addition, the app updates Home tab for the submitter with the up-to-date list of the person's submissions.

We'll meet the above requirements by leveraging many of the latest Slack Platform features. We'll learn effective ways to take advantage of Block Kit, Global Shortcuts, and Modals.

• Block Kit: Block Kit is the Slack's UI framework for building an rich user interface. From a Slack app developer perspective, it is just a kind of JSON data structure to comply with. Slack properly renders your specifically structured JSON for both desktop and mobile.
• Global Shortcuts: A Global Shortcut is a quick and easy way to start a workflow from anywhere in Slack. Users can access global shortcuts from either the menu in text composer or search bar. Try a built-in one to learn how it works.
• Modals: A modal is a popover window built with Block Kit components. You use this for collecting user inputs or displaying information in an organized way. A modal can have multiple steps in its flow.

We're going to use Bolt for JavaScript, a Slack app framework optimized for taking full advantage of the Platform features. With Bolt, you won't be bothered by Slack-specific non-functional requirements:

• Verify requests from Slack for security (Your API endpoint is exposed to the internet. That means not only Slack, but any random clients may try to send requests to your endpoint. So, it's highly recommended to distinguish Slack's requests from others.)
• Parse a variety of payloads (For historical reasons, the data structure of payloads varies among features.)
• Dispatch requests to their right code path (similarly to well-designed full-stack Web app frameworks)
• Avoid infinite loop errors by reacting to events triggered by the app itself (particularly when using Events API)
• Pick up the right access token for an incoming request

As Bolt takes care of these things, your Slack app development becomes even more productive.

Access git.io/apidays-slack!

git clone [email protected]:seratch/apidays-workshop-2020.git
cd apidays-workshop-2020/
node --version # need to be v10.13 or higher
npm i # install dependencies
code . # Open the project with Visual Studio Code

Visit https://api.slack.com/apps to create a new Slack App configuration.

Signing in to the Slack workspace you're going to use for development in the browser is required.

Go to the OAuth & Permissions page and add the following Bot Token Scopes to the app.

• commands for creating a Global Shortcut
• chat:write for chat.postMessage API calls
• chat:write.public for chat.postMessage API calls in public channels where the bot user is not yet invited
• im:write for conversations.open API calls

The Slack App's name automatically determines the default bot user name. If you prefer a different name over the name automatically set, go to App Home page and change it. As a bot user name is user-facing, making it nice is crucial for better user experiences.

As long as you use this app only in its development workspace, you don't need to implement the standard OAuth flow for acquiring OAuth access tokens. You can go with the simplified way offered by the Slack Platform. Go to the Install App page and just click the install button and complete the OAuth flow. You'll use the Bot User OAuth Access Token when booting your Bolt app.

If you're interested in distributing your app to multiple workspaces, refer to the Bolt JS's guide.

All the steps to follow for booting your Bolt app are:

• Create .env file at the root directory of this project
• Make sure if you're using Node.js 10.13 or higher (node --version)
• Run npm install to fetch all required dependencies
• Run npm run local to start the local app
• Install ngrok if you don't have yet - https://ngrok.com/
• Open another terminal and run ngrok http 3000 to establish a public endpoint

SLACK_BOT_TOKEN=xoxb-111-111-xxx
SLACK_SIGNING_SECRET=xxx

The procedure is actually quite simple. Run the following commands.

node --version # should be v10.13.0 or higher
npm install
npm run local # This starts an app at http://localhost:3000/slack/events

If you don't have ngrok, download it.

# Check if the local app is running
curl -I -XPOST http://localhost:3000/slack/events # You should get HTTP/1.1 401 Unauthorized

# on another terminal
./ngrok http 3000

# if you're a paid user
./ngrok http 3000 --subdomain {whatever-you-want}

# You can verify if it's working by the following on yet another terminal:
curl -I -XPOST https://{your random subdomain here}.ngrok.io/slack/events # You should get HTTP/1.1 401 Unauthorized

• Visit the Slack App configuration page (https://api.slack.comc/apps) and choose your app
• Go to the Interactivity & Shortcuts page
• Turn on the Interactivity feature
• Set https://{your random subdomain here}.ngrok.io/slack/events as the Request URL
• Create a new Shortcut (Global -> Callback ID: new-helpdesk-request)
• Click the Save Changes button at the bottom

Check the ./src/solution.js to know the complete version of the app.

• Add a Global Shortcut listener for callback_id: new-helpdesk-request
• Add an Action listener for action_id: helpdesk-request-modal-category-selection
• Add an Action listener for action_id: helpdesk-request-modal-reset
• Add a View Submission listener for callback_id: helpdesk-request-modal

Block Kit Builder is a preview tool in the browser to see how your blocks look like in Slack. I recommend checking the validity and the appearance of your blocks using this tool before embedding them into your app.

• Step 1 modal in Block Kit Builder
• Step 2 modal in Block Kit Builder

• Create a Slack app configuration at https://api.slack.com/apps
  • Signing in with your Slack workspace account is required
• Configure the Slack app with sufficient permissions
  • Go to the "OAuth & Permissions" page and add bot token scopes
  • Turn the features you use on (Interactivity, Events Subscriptions, Home tab, and so on)
• Install the app onto its Development Slack Workspace
  • Grab the "Bot User OAuth Access Token" starting with "xoxb-"
• Create a Bolt app
  • Set env variables - SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET
  • Start the app (app.start())
  • By default, Bolt apps receive requests coming to POST http://localhost:3000/slack/events
• Have a public endpoint to receive requests from Slack
  • You may use ngrok or similar for it (ngrok http 3000)
• Add listeners for incoming requests
  • Check ngrok access logs (http://localhost:4040)
  • Check the error messages in stdout
  • Read the Bolt for JS documents
• Have fun with Slack app development

The MIT License