Getting Started with Bolt (Socket Mode)

Bolt for Java is a framework on the JVM that offers an abstraction layer to build Slack apps quickly using modern platform features.

This guide explains how to start your first-ever Bolt app.

If you're not yet familiar with Slack app development in general, we recommend reading the Slack API docs.

Project Setup

Let's start building a Slack app using Bolt! This guide includes instructions on how to set up a Bolt project with Maven and Gradle, so use whichever section you'd like.

Maven

After you create your Maven project, you need to add the bolt dependency to your pom.xml file. The bolt dependency is a framework-agnostic module. To enable Socket Mode, the bolt-socket-mode library and its provided-scope dependencies are also required for your app.

<dependency>
  <groupId>com.slack.api</groupId>
  <artifactId>bolt</artifactId>
  <version>1.43.1</version>
</dependency>
<dependency>
  <groupId>com.slack.api</groupId>
  <artifactId>bolt-socket-mode</artifactId>
  <version>1.43.1</version>
</dependency>
<dependency>
  <groupId>javax.websocket</groupId>
  <artifactId>javax.websocket-api</artifactId>
  <version>1.1</version>
</dependency>
<dependency>
  <groupId>org.glassfish.tyrus.bundles</groupId>
  <artifactId>tyrus-standalone-client</artifactId>
  <version>1.20</version>
</dependency>
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-simple</artifactId>
  <version>1.7.36</version>
</dependency>

By default, the tyrus-standalone-client dependency is used as the implementation to manage socket connections in the bolt-socket-mode artifact. If instead you would prefer to use the Java-WebSocket implementation, swap its artifact in instead of tyrus-standalone-client, and then set SocketModeClient.Backend.JavaWebSocket when initializing the client instance:

<dependency>
  <groupId>org.java-websocket</groupId>
  <artifactId>Java-WebSocket</artifactId>
  <version>1.5.1</version>
</dependency>

You will also need to ensure you set the compiler source and target to at least 1.8:

<properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>

Gradle

After you create your Gradle project, add the bolt dependencies to build.gradle.

dependencies {
  implementation("com.slack.api:bolt-socket-mode:1.43.1")
  implementation("javax.websocket:javax.websocket-api:1.1")
  implementation("org.glassfish.tyrus.bundles:tyrus-standalone-client:1.20")
  implementation("org.slf4j:slf4j-simple:1.7.36")
}

Run Your Bolt App in 3 Minutes

Use `bolt-socket-mode`

bolt-socket-mode is a handy way to start your Socket Mode app. It allows developers to build a Slack app backend service by writing only a main method initializes App and establishes a WebSocket connection to the Socket Mode servers.

`build.gradle`

The following build settings should be working as-is. Put it in the root directory of your project.

plugins {
  id("application")
}
repositories {
  mavenCentral()
}
dependencies {
  implementation("com.slack.api:bolt-socket-mode:1.43.1")
  implementation("javax.websocket:javax.websocket-api:1.1")
  implementation("org.glassfish.tyrus.bundles:tyrus-standalone-client:1.20")
  implementation("org.slf4j:slf4j-simple:1.7.36")
}
application {
  mainClassName = "hello.MyApp"
}
run {
  // gradle run -DslackLogLevel=debug
  systemProperty "org.slf4j.simpleLogger.log.com.slack.api", System.getProperty("slackLogLevel")
}

`src/main/java/hello/MyApp.java`

Coding with this framework is much simpler than you think.

Only single source code is required to run your first-ever Bolt app. All you need to do is define the main method that starts SocketModeApp.

package hello;

import com.slack.api.bolt.App;
import com.slack.api.bolt.socket_mode.SocketModeApp;

public class MyApp {
  public static void main(String[] args) throws Exception {
    // App expects an env variable: SLACK_BOT_TOKEN
    App app = new App();

    app.command("/hello", (req, ctx) -> {
      return ctx.ack(":wave: Hello!");
    });

    // SocketModeApp expects an env variable: SLACK_APP_TOKEN
    new SocketModeApp(app).start();
  }
}

If you go with JDK 10+, thanks to Local Variable Type Inference, your code could be much more concise. To take advantage of it, install OpenJDK 11 and set the compatible Java versions in build.gradle as below. Also, configure the same on your IDE.

java {
  sourceCompatibility = JavaVersion.VERSION_11
  targetCompatibility = JavaVersion.VERSION_11
}

Now, you don't need to repeat the same type in a single line.

var app = new App();
app.command("/hello", (req, ctx) -> {
  return ctx.ack(":wave: Hello!");
});
new SocketModeApp(app).start();

Start the App with Two Env Variables

The default constructor expects the following two env variables exist when starting the app.

Env Variable Description

SLACK_BOT_TOKEN The valid bot token value starting with xoxb- in your development workspace. To issue a bot token, you need to install your Slack App that has a bot user to your development workspace. Visit the Slack App configuration page, choose the app you're working on, and go to Settings > Install App on the left pane (Add app_mentions:read bot scope if you see the message saying "Please add at least one feature or permission scope to install your app.").

If you run an app that is installable for multiple workspaces, no need to specify this. Consult App Distribution (OAuth) for further information instead.

SLACK_APP_TOKEN The valid app-level token value starting with xapp- for your Slack app. To issue an app-level token, Visit the Slack App configuration page, choose the app you're working on, and go to Settings > Basic Information > App-Level Tokens, and then create a new one with connections:write scope.

Env Variable	Description
`SLACK_BOT_TOKEN`	The valid bot token value starting with `xoxb-` in your development workspace. To issue a bot token, you need to install your Slack App that has a bot user to your development workspace. Visit the Slack App configuration page, choose the app you're working on, and go to Settings > Install App on the left pane (Add `app_mentions:read` bot scope if you see the message saying "Please add at least one feature or permission scope to install your app."). If you run an app that is installable for multiple workspaces, no need to specify this. Consult App Distribution (OAuth) for further information instead.
`SLACK_APP_TOKEN`	The valid app-level token value starting with `xapp-` for your Slack app. To issue an app-level token, Visit the Slack App configuration page, choose the app you're working on, and go to Settings > Basic Information > App-Level Tokens, and then create a new one with `connections:write` scope.

If you prefer configuring an App in a different way, write some code to initialize AppConfig on your own.

Set the two environment variables and run:

Gradle users: gradle run (for more detailed logging: gradle run -DslackLogLevel=debug),
Maven users: mvn compile exec:java -Dexec.mainClass="hello.MyApp" (for more detailed logging you can also provide the -Dorg.slf4j.simpleLogger.defaultLogLevel=debug flag)

The command runs your main method.

# Visit https://api.slack.com/apps to know these
export SLACK_BOT_TOKEN=xoxb-...your-own-valid-one
export SLACK_APP_TOKEN=xapp-...your-own-valid-one

# run the main function
# gradle users should run:
gradle run
# maven users should run:
mvn compile exec:java -Dexec.mainClass="hello.MyApp"

If you get stuck this setup, go through the following checklist:

✅ JDK 8 or higher installed (if not, run brew install openjdk@11 for macOS / visit OpenJDK website for others)
✅ Gradle installed (if not, run brew install gradle for macOS / visit their website for others)
✅ build.gradle has bolt-socket-mode and tyrus-standalone-client in the dependencies and valid application plugin settings
✅ src/main/java/hello/MyApp.java with a class having its main method
✅ Create a Slack App, add commands bot scope, add an app-level token with connections:write scope, and install the app to your development workspace
✅ Copy Bot User OAuth Access Token and App-Level Token from your Slack App admin pages and set them to env variables

Enable `/hello` Command

Your app is up now! However, the slash command /hello in the code is still unavailable. To enable it, follow the steps below:

Visit Slack App configuration pages
Choose your app
Go to Settings > Socket Mode on the left pane
- Turn on Enable Socket Mode
Go to Features > Slash Commands on the left pane
- Click Create New Command button
- Input the command information on the dialog:
  - Command: /hello
  - Short Description: whatever you like
- Click Save Button

Now you can hit the /hello command in your development workspace. If your app is successfully running, the app should respond to the command by replying 👋 Hello!.

Getting Started in Kotlin

For code simplicity, Kotlin language would be a great option for writing Bolt apps. In this section, you'll learn how to set up a Kotlin project for Bolt apps.

`build.gradle`

Most of the build settings are necessary for enabling Kotlin language. Adding bolt-socket-mode && tyrus-standalone-client to the dependencies is the only one that is specific to Bolt.

plugins {
  id("org.jetbrains.kotlin.jvm") version "1.7.21"
  id("application")
}
repositories {
  mavenCentral()
}
dependencies {
  implementation(platform("org.jetbrains.kotlin:kotlin-bom"))
  implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
  implementation("com.slack.api:bolt-socket-mode:1.43.1")
  implementation("javax.websocket:javax.websocket-api:1.1")
  implementation("org.glassfish.tyrus.bundles:tyrus-standalone-client:1.20")
  implementation("org.slf4j:slf4j-simple:1.7.36") // or logback-classic
}
application {
  mainClassName = "MyAppKt" // add "Kt" suffix for main function source file
}

If you're already familiar with Kotlin and prefer the Gradle Kotlin DSL, of course, there is nothing stopping you.

`src/main/kotlin/MyApp.kt`

Here is a minimum source file that just starts a Bolt app on your local machine.

import com.slack.api.bolt.App
import com.slack.api.bolt.socket_mode.SocketModeApp

fun main() {
  val app = App()

  // Write some code here

  SocketModeApp(app).start()
}

Make Sure If It Works

OK, you should be done. Just in case, here is the checklist:

✅ JDK 8 or higher installed (if not, run brew install openjdk@11 for macOS / visit OpenJDK website for others)
✅ Gradle installed (if not, run brew install gradle for macOS / visit their website for others)
✅ build.gradle with valid Kotlin language settings and bolt-socket-mode and tyrus-standalone-client in the dependencies
✅ src/main/kotlin/MyApp.kt with a main method
✅ Create a Slack App, add commands bot scope, add an app-level token with connections:write scope, and install the app to your development workspace
✅ Copy Bot User OAuth Access Token and App-Level Token from your Slack App admin pages and set them to env variables

If all are ✅, bootstrapping your first-ever Kotlin-flavored Bolt app will succeed.

# Visit https://api.slack.com/apps to know these
export SLACK_BOT_TOKEN=xoxb-...your-own-valid-one
export SLACK_APP_TOKEN=xapp-...your-own-valid-one

# run the main function
gradle run

From here, all you need to do is write code and restart the app. Enjoy Bolt app development in Kotlin! 👋

tip

We strongly recommend using IntelliJ IDEA here even if you don't prefer using IDEs. The IDE is the smoothest way to try Kotlin application development.

Next Steps

Read the Bolt Basics page for further information.

Project Setup​

Maven​

Gradle​

Run Your Bolt App in 3 Minutes​

Use bolt-socket-mode​

build.gradle​

src/main/java/hello/MyApp.java​

Start the App with Two Env Variables​

Enable /hello Command​

Getting Started in Kotlin​

build.gradle​

src/main/kotlin/MyApp.kt​

Make Sure If It Works​

Next Steps​

Project Setup

Maven

Gradle

Run Your Bolt App in 3 Minutes

Use `bolt-socket-mode`

`build.gradle`

`src/main/java/hello/MyApp.java`

Start the App with Two Env Variables

Enable `/hello` Command

Getting Started in Kotlin

`build.gradle`

`src/main/kotlin/MyApp.kt`

Make Sure If It Works

Next Steps