Docs: Create a Slack Bot

Useful Resources

Start from scratch (not recommended)

I don't personally recommend building your app from 0 mostly if it's your first time doing an Slack bot. I would do it anyways, or at least read it, just to understand the process.

1. Create Slack app

Go to https://slack.com/, create an account and create a workspace. You can see an example at https://youtu.be/AajBk59nOgw, from 1:30 to 2:30. Then, go to https://api.slack.com/ and enter to **Your apps** page. Select **Create New App**, a modal will show up and then select **From scratch**. Enter a name for the app, select the workspace and click **Create App**.

2. Request scopes

Scopes give your app permission to perform actions, such as posting messages in your workspace. Add the chat:write bot token scope.

3. Install and authorize the app

Install into workspace. Go to the channel you want the app to have access (there are scopes to have access to all channels) and write this command. This way the bot will be a member of that channel:

/invite @YouBot

Start from a template

First go to slack.com, create an account and create a workspace. You can see an example at Techno Tim "How to Build a Slack Bot" video, from 1:30 to 2:30.

Create Slack app, require scopes and install it

Go to your apps and create a new one From manifest.

Copy and paste the manifest from the bolt-ts-starter-template. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app.

Review the configuration (change bot's name, username, display name, description, profile image, color...). Allow direct messages with the bot. In the App Home tab, enable "Messages Tab" and "Allow users to send Slash commands and messages from the messages tab", in the bottom of the page at the Show Tabs section.

With the template manifest, three scopes will be already configured: channels:history, chat:write and commands. For now we don't need any other one. Maybe later we'll add more.

With this manifest the app will be set to Socket Mode. Socket Mode allows your app to use the Events API and interactive features without exposing a public HTTP Request URL. This can be helpful during development, or if you're receiving requests from behind a firewall.

Go to the OAuth & Permissions tab and click "Install to Workspace" and "Allow" on the screen that follows. Then you will have a Bot User OAuth Token. This has to keep totally private, nobody else must have access to it.

Now you should see the bot in your workspace and you should be able to send private messages to it.

Let's make the bot a member of a channel. Go to the channel you want the app to have access (there are scopes to have access to all channels) and write this command:

/invite @YourBot

Start the bot

Create a new GitHub repository from the bolt-ts-starter-template.

Clone the repository in your PC, rename the env.sample file to .env and add the required information inside. You can see a more detailed explanation in the bolt-ts-starter-template readme. To get the SLACK_APP_TOKEN you will need to go to Basic Information and scroll down under the App-Level Tokens section and click Generate Token and Scopes to generate an app token. Add the connections:write scope to this token and generate it.

Delete the package-lock.json file and update your package.json to use yarn instead of npm. You can also remove the dotenv dependency because node >= 20.6.0 supports .env files natively (but I highly recommend you use node >= 20.7.0 because process.loadEnvFile() was introduced).

{
  "scripts": {
-    "start": "npm build && node ./dist/app.js",
-    "lint": "npx @biomejs/biome check *.ts listeners",
-    "lint:fix": "npx @biomejs/biome check --write *.ts listeners",
-    "test": "npm build && npm lint"
+    "start": "yarn build && node ./dist/app.js",
+    "lint": "biome check *.ts listeners",
+    "lint:fix": "biome check --write *.ts listeners",
+    "test": "yarn build && yarn lint"
  }
}

You can delete the app-oauth.ts file.

Now install the dependencies by running yarn. Maybe you will need to install types for express

yarn add -D @types/express

Instead of importing dotenv and using dotenv.config() in your app.ts file, just replace that for process.loadEnvFile(). By default that will load a .env file but you can pass the env path as an argument.

This template is using Biomejs as a formatter and linter. It's a replace for ESLint and Prettier. You should install the Biome VSCode extension.

I recommend you to create a ./.vscode/settings.json file with this content:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

Now run yarn start to check everything is working fine.

You will see a lot of text in your terminal because the logs level are set to debug, so you see everything. As long as you see [INFO] bolt-app ⚡️ Bolt app is running! ⚡, you should be fine.

Now if you go to Slack and run (just send it as a normal message) the sample command /sample-command the bot should reply to you. That means that you have successfully created a functional Slack bot.

Subscribe to events

To listen for events happening in a Slack workspace (like when a message is posted or when a reaction is posted to a message) you'll use the Events API to subscribe to event types.

Make sure to have the Slack app in Socket Mode and the events enabled. I've mentioned this earlier, so maybe you already have it, but check it just in case:

Head to your app's configuration page (click on the app from your app settings page). Navigate to Socket Mode on the left side menu and toggle to enable.
Go to Basic Information and scroll down under the App-Level Tokens section and click Generate Token and Scopes to generate an app token (only if you haven't done it yet). Add the connections:write scope to this token. The generated token will be the SLACK_APP_TOKEN that you need for in your .env file.
Finally, it's time to tell Slack what events we'd like to listen for. Under Event Subscriptions, toggle the switch labeled Enable Events.

When an event occurs, Slack will send your app information about the event, like the user that triggered it and the channel it occurred in. Your app will process the details and can respond accordingly.

Scroll down to Subscribe to Bot Events. There are four events related to messages:

message.channels listens for messages in public channels that your app is added to
message.groups listens for messages in 🔒 private channels that your app is added to
message.im listens for messages in your app's DMs with users
message.mpim listens for messages in multi-person DMs that your app is added to

I've subscribed to all four events.

If you update the events your bot is subscribed to, you'll need to reinstall the app in your workspace.

Now restart your bot process (if it was running) and now if you send hi, hello or hey your bot should reply with ${greeting}, how are you? where ${greeting} will be replaced with the greeting you used. That is because of the messages listener we have (created by the template).

You can see more details about how to listen and respond to a message Bolt-js Getting Stared guide.

picuu/create-slack-app.md