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.