Slack Socket Mode in Python: A Bolt App and the Token Errors

Socket Mode lets a Slack app receive events over a WebSocket that your code opens, so you do not need a public HTTPS URL. In Python it takes two tokens: an app-level token that starts with xapp- and has the connections:write scope, which opens the socket, and the usual xoxb- bot token, which calls the Web API. We built a test app in our own Slack workspace on 1 October 2026, ran the script below, and then broke it on purpose to collect the errors.

Get the xapp- token

• At api.slack.com/apps, open your app and go to Socket Mode. Turn on Enable Socket Mode.
• Go to Basic Information, scroll to App-Level Tokens and click Generate Token and Scopes.
• Name the token, click Add Scope, pick connections:write, and click Generate.
• Under Event Subscriptions, subscribe to the bot events you need. For the script below that is message.channels, plus the channels:history scope.
• Install the app and copy the Bot User OAuth Token (xoxb-) from OAuth & Permissions.


The app-level token belongs to the app, not to a workspace install. It is not on the OAuth page with the other tokens, which is why people search for where it is. Each app can hold up to 10 of them. The other prefixes are explained in Slack bot token.

A Bolt for Python app that answers over Socket Mode

import os, logging
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler

logging.basicConfig(level=logging.INFO)
app = App(token=os.environ["SLACK_BOT_TOKEN"])

@app.message("hello")
def say_hello(message, say):
    say(f"Hi <@{message['user']}>, this reply came over Socket Mode.")

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

pip install slack_bolt
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...
python app.py

The console log from our run (Python 3.14, slack_bolt from PyPI that day):

INFO:slack_bolt.App:A new session has been established (session id: 0ba27433-249d-4468-b25d-cacfa5a55aac)
INFO:slack_bolt.App:⚡️ Bolt app is running!
INFO:slack_bolt.App:Starting to receive messages from a new connection (session id: 0ba27433-249d-4468-b25d-cacfa5a55aac)

We typed hello in a test channel the bot was in. The reply came 0.54 seconds later, measured from the two message timestamps:



The bot also logged a 404 unhandled request warning for the channel_join message when it joined the channel. That warning is harmless. It means no listener matched that event.

Errors from the wrong token

We changed one thing at a time and ran the same script.

What we changed	Where it failed	Error
xoxb- bot token as SLACK_APP_TOKEN	At start, in apps.connections.open	not_allowed_token_type
xoxp- user token as SLACK_APP_TOKEN	At start	not_allowed_token_type
xapp- token with only authorizations:read	At start	missing_scope, needed connections:write
xapp- token as SLACK_BOT_TOKEN	Only when it tried to reply	not_allowed_token_type from chat.postMessage

The scope error, as Bolt printed it before the traceback:

ERROR:slack_bolt.App:Failed to retrieve WSS URL: The request to the Slack API failed. (url: https://slack.com/api/apps.connections.open)
The server responded with: {'ok': False, 'error': 'missing_scope', 'needed': 'connections:write', 'provided': 'authorizations:read'}

The last row is the one that wastes time. With the two tokens swapped into each other's place, the app still logged "Bolt app is running!" and received our message. auth.test accepts an xapp- token and answers {"ok": true, "app_name": "w1 test 1001", "app_id": "A0C5NDV7U0K"}, so nothing fails at startup. The error came only when say() called chat.postMessage. If the app connects but never answers, check which token is in which variable first. A missing scope on the bot token gives a different error, covered in missing_scope.

Why Socket Mode seems not to work

Two more things we measured:

Also check the usual causes: the bot must be in the channel to get message.channels events, and each event type must be ticked under Event Subscriptions. Socket Mode only replaces the request URL.

Socket Mode vs HTTP request URLs

Socket Mode fits internal tools and local development. The same app can also send buttons and slash command replies that only one person sees; we tested those in Slack ephemeral messages.

FAQ

Do I still need a signing secret with Socket Mode? No. Slack sends events over the socket your app opened with its own token, so there is no incoming HTTP request to verify. Our script never used the signing secret.

Does the xapp- token stop working when the app is uninstalled? Not while the app exists. After we uninstalled our test app, apps.connections.open with the same xapp- token still returned a WebSocket URL. After we deleted the app, auth.test with it returned invalid_auth.