Slack Setup

Requirements

Before going further, we assume that you already have:

• a Slack Account
• a Slack Workspace

Create a Slack App

Create a Slack App if you haven't.

Click the Create New App button.

Fill the App Name and Development Slack Workspace and then click the Create App button.

We recommand creating a new workspace for experiment.

Install Slack App to Workspace

You can find the Install App to Workspace button in Slack Developer Console → \${YourApp} → OAuth & Permissions

The Install App to Workspace button is disabled. To enable the button, you need to setup at least one of the permissions the Slack app need.

You can set those permissions in Slack Developer Console → \${YourApp} → OAuth & Permissions → Scopes → Bot Token Scopes

Click the Add an OAuth Scope button in the Bot Token Scopes section to create a chat:write OAuth Scope, which allows Slack app to send messages as a bot user.

The Install App to Workspace button is enabled now.

Click the Install App to Workspace button.

This is the page for the Slack workspace authorizes to the Slack app.

Click the Allow button.

Now, you installed the Slack app in your Slack workspace. This is also the place where you can get the access token Bottender need.

Enabling Slack Channels

To enable Slack channels, you can start either from new or existing Bottender apps.

New Bottender Apps

Create Bottender App is the best way to start building a new app in Bottender.

To create a project, run:

npx create-bottender-app my-app

Make sure to select the slack option:

After you go through the steps, bottender.config.js and .env are generated automatically for further channel settings.

Existing Bottender Apps

First, you must have a bottender.config.js file includes the following settings:

module.exports = {
  channels: {
    slack: {
      enabled: true,
      path: '/webhooks/slack',
      accessToken: process.env.SLACK_ACCESS_TOKEN,
      signingSecret: process.env.SLACK_SIGNING_SECRET,
      // verificationToken: process.env.SLACK_VERIFICATION_TOKEN, // deprecated, use signingSecret
    },
  },
};

Make sure to set the channels.slack.enabled field to true.

By default, the Bottender server listens to the Slack requests on the /webhooks/slack path. However, you can overwrite the path by assigning the preferred webhook path in the channels.slack.path field.

We highly recommend setting your sensitive config using process.env, so you could avoid any credentials get exposed.

Environment Configuration

Bottender utilizes the dotenv package to load your environment variables when developing your app.

To make a Slack bot work, you must prepare the following environment variables, which you may put into your .env file later:

• Slack Access Token
• Slack Signing Secret (or Slack Verification Token)

Slack Access Token

You can find Slack access token in Slack Developer Console → \${YourApp} → OAuth & Permissions → Bot User OAuth Access Token

After you get your Slack Access Token, paste the value into the SLACK_ACCESS_TOKEN field in your .env file:

# .env

SLACK_ACCESS_TOKEN=<YOUR SLACK ACCESS TOKEN>

Slack Signing Secret

You can find Slack signing secret in Slack Developer Console → \${YourApp} → Basic Information → App Credentials → Signing Secret.

After you get your Slack Signing Secret, paste the value into the SLACK_SIGNING_SECRET field in your .env file:

# .env

SLACK_SIGNING_SECRET=<YOUR SLACK SIGNING SECRET>

Slack Verification Token (Deprecated)

We recommend using signing secret instead of verification token, but we also support verification token.

You can find Slack verification token in Slack Developer Console → \${YourApp} → Basic Information → App Credentials → Verification Token.

After you get your Slack Verification Token, paste the value into the SLACK_VERIFICATION_TOKEN field in your .env file:

# .env

# SLACK_VERIFICATION_TOKEN=<YOUR SLACK VERIFICATION TOKEN> # deprecated, use `SLACK_SIGNING_SECRET` instead

Webhook

After finishing the above settings, you can start your server with Slack webhook event listening using the following commands:

# in production mode
npm start

# or in development mode
npm run dev

When you run bottender in development mode, Bottender automatically run up a ngrok client, and then you can get the information of webhook URL from the console like this:

App has started
slack webhook URL: https://42bbf602.ngrok.io/webhooks/slack
server is running on 5000 port...

Then, you have to copy your Slack webhook URL to Slack Developer Console → \${YourApp} → Event Subscriptions, where you can pick which bot events to subscribe.

Turn on the switch.

Fill the Request URL field with your Slack webhook URL.

You can see the word Verified after setting the webhook URL.

Now, open the Subscribe to bot events block to subscribe some events.

Add the following events to receive the corresponding webhook requests:

• message.im: A message was posted in a direct message channel.
• message.groups: A message was posted to a private channel.
• message.channels: A message was posted to a public channel.
• message.mpim: A message was posted in a multiparty direct message channel.

For more information about Slack Events, please refer to Slack's official doc, API Event Types

Click the Save Changes button.

Reinstall your app.

Now, you can see the slack app require more permissions.

Click the Allow button. Now you can chat with the slack bot in direct message channel or in any channel the slack bot in.

The next thing you can do is teaching your bot to echo.

Note: If your bot doesn't respond after webhook settings, please take a closer look at bot events you subscribed to. Slack doesn't pick any bot events subscription by default. The first bot event you may subscribe to is message.im, which is the event whenever a user posts a direct message to your bot.