Intro to Socket Mode

Socket Mode allows your app to use the Events API and interactive components of the platform—without exposing a public HTTP Request URL.

Instead of sending payloads to a public endpoint, Slack will use a WebSocket URL to communicate with your app.

Socket Mode helps developers working behind a corporate firewall, or who have other security concerns that don't allow exposing a static HTTP endpoint.

Even if you're just getting started and building something for your team, using Socket Mode with our Bolt frameworks for Javascript, Python, or Java is the quickest way to access the full set of Slack platform features.

This guide walks you through what to expect from Socket Mode, how to setup your app to use Socket Mode, and how to use Bolt or the Slack SDKs to jumpstart your Socket Mode app with a minimum of fuss.

Overview

Socket Mode allows your app to communicate with Slack via a WebSocket URL. WebSockets use a bidirectional stateful protocol with low latency to communicate between two parties—in this case, Slack and your app.

Unlike a public HTTP endpoint, the WebSocket URL you listen to is not static. It's created at runtime by calling the apps.connections.open method, and it refreshes regularly.

Because the URL isn't static and is created at runtime, it allows for greater security in some cases, and it allows you to develop behind a firewall.

In Socket Mode, your app still uses the very same Events API and interactive components of the Slack platform. The only difference is the communication protocol.

You can still switch between a direct HTTP endpoint and Socket Mode at any time in the app config.

App setup

App setup for Socket Mode has only a few steps: creating an app, turning on Socket Mode, and generating an app-level token.

Creating an app

If you don't have one already, you'll need to create a new Slack app:

Create a Slack app

Fill out your App Name and select the Development Workspace where you'll play around and build your app.

One thing to note: Socket Mode apps currently can't be listed in the Slack App Directory. If you'd like to distribute your Socket Mode app to your entire Enterprise Grid organization, you can make your app deployable org-wide.

Other aspects of app setup are well-covered in our getting started guides, so head over there for more details if needed.

Toggling Socket Mode

In your app config, navigate to the Socket Mode section. Toggle the Enable Socket Mode button to turn on receiving payloads via WebSockets.

Socket Mode can be toggled on or off whenever you'd like. When you toggle Socket Mode on, you'll only receive events and interactive payloads over your WebSocket connections—not over HTTP.

Note: if your app is actively receiving events when you toggle Socket Mode on, you may lose events until you establish a connection to your WebSocket URL.

At this point, you can subscribe to some events in the Event Subscriptions section of your app config. A favorite is the old standby app_mention event.

When using Socket Mode, a Request URL is unneeded when using the Events API. Your app's connection to the websocket replaces the need for Slack to dispatch to a Request URL.

Creating an app with manifests

You can create an app through a manifest and turn on Socket Mode by configuring a few options. Below is a YAML example which includes adding a bot user with the app_mentions:read scope and subscribing to the app_mention event subscription:

_metadata:
  major_version: 1
display_information:
  name: Demo App
features:
  bot_user:
    display_name: Demo App
    always_online: false
oauth_config:
  scopes:
    bot:
      - app_mentions:read
settings:
  event_subscriptions:
    bot_events:
      - app_mention
  org_deploy_enabled: false
  socket_mode_enabled: true
  is_hosted: false
  token_rotation_enabled: false

Generating an app-level token

When you toggle Socket Mode on, if you haven't yet created an app-level token yet, the app config will guide you through obtaining one.

Here's a primer in case you need to create an app-level token manually, or regenerate one:

Under Basic Information, scroll to the App-level tokens section and click the button to generate an app-level token.

Your app-level token allows your app, either directly or with an SDK, to generate a WebSocket URL for communication with Slack via the apps.connections.open method.

You're finished with setting up your app for Socket Mode. The rest can be handled effortlessly by using the Slack SDKs. Or, you can implement the Socket Mode protocol yourself by reading our deep dive.

Socket Mode with Bolt or SDKs

In case you needed another reason to make your life more pleasant and productive with our frameworks and SDKs, Socket Mode is automatically supported by each of them.

Simply set your app-level token as an environment variable:

export SLACK_APP_TOKEN='xapp-***'

Now you can lean on Bolt or the SDKs for Javascript, Java, or Python to take care of the rest.

Here's some code to get your app running in Socket Mode using Bolt:

package hello;

import com.slack.api.bolt.App;
import com.slack.api.bolt.AppConfig;
import com.slack.api.bolt.socket_mode.SocketModeApp;
import com.slack.api.model.event.AppMentionEvent;

// Required dependencies:
// implementation("com.slack.api:bolt-socket-mode:(latest version)")
// implementation("org.glassfish.tyrus.bundles:tyrus-standalone-client:1.17")
public class MyApp {

  public static void main(String[] args) throws Exception {
    String botToken = System.getenv("SLACK_BOT_TOKEN");
    App app = new App(AppConfig.builder().singleTeamBotToken(botToken).build());
    String appToken = System.getenv("SLACK_APP_TOKEN");
    SocketModeApp socketModeApp = new SocketModeApp(appToken, app);
    socketModeApp.start();
  }
}

Code to initialize Bolt app
// Require the Node Slack SDK package (github.com/slackapi/node-slack-sdk)
const { WebClient, LogLevel } = require("@slack/web-api");

// WebClient instantiates a client that can call API methods
// When using Bolt, you can use either `app.client` or the `client` passed to listeners.
const client = new WebClient("xoxb-your-token", {
  // LogLevel can be imported and used to make debugging simpler
  logLevel: LogLevel.DEBUG
});
const { App } = require('@slack/bolt');

const app = new App({
  token: process.env.BOT_TOKEN,
  appToken: process.env.SLACK_APP_TOKEN,
  socketMode: true,
});

(async () => {
  await app.start();
  console.log('⚡️ Bolt app started');
})();

import os

from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler

# Install the Slack app and get xoxb- token in advance
app = App(token=os.environ["SLACK_BOT_TOKEN"])

if __name__ == "__main__":
    SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start()

If Bolt or an SDK suits your goals, then you're ready to to continue developing your app as normal!

Each Bolt package has its own documentation to help you get started with Socket Mode, so peruse the docs for Javascript, Java, and Python as you see fit.

Implementing Socket Mode

If you prefer to implement the Socket Mode protocol yourself, check out our further implementation guide next.