Beginner

Intro to Socket Mode

If you don't wish to expose a public, static HTTP endpoint to communicate with Slack, Socket Mode can help.

Socket Mode allows your app to use the Events API and interactive components of the platformwithout 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.

Apps using Socket Mode are not currently allowed in the public Slack App Directory.

Socket Mode is only available for apps using new, granular permissions. If you created your app on or after December of 2019, good news: your app already uses the new permissions. Otherwise, you may have to migrate your classic Slack app to use granular permissions before turning on Socket Mode.

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.

You'll note that a Request URL is no longer needed for using the Events API. That's because, in Socket Mode, your app initiates connection to a WebSocket URL that replaces the public HTTP Request URL.

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:

Capturing events using Socket Mode
Java
JavaScript
Python
Java
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();
  }
}
JavaScript
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 insantiates 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'); })();
Python
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.

Was this page helpful?