Slack Bolt Middleware: Global and Listener, Tested
Global middleware runs for every request and listener middleware for one listener. We ran both in Bolt for Python and Bolt for JavaScript on 20 November 2026 and logged what Slack did when next() was skipped: Python answered 404 and Slack sent the event again.
On this page
Bolt middleware is a function that runs before your listener and calls next() to hand the request on. Global middleware (@app.middleware in Bolt for Python, app.use() in Bolt for JavaScript) runs for every request Slack sends your app. Listener middleware is passed to one listener, such as app.message("deploy", middleware=[...]), and runs only when that listener matches. In our test on 20 November 2026, the part that changed behavior was next(). When a global middleware in Bolt for Python returned without calling it, Bolt answered Slack with HTTP 404, and Slack sent the same event again 0.16 seconds and 61 seconds later. Bolt for JavaScript answered 200 in every case.
The test setup
We made a throwaway Slack app in a test workspace with one bot event, message.channels, and ran the same two middleware functions in Bolt for Python 1.30.0 and Bolt for JavaScript 4.7.3, each in a Docker container in HTTP mode. A 30-line Python proxy sat between Slack and Bolt and logged the HTTP status of every reply and the X-Slack-Retry-Num header of every request. A Cloudflare quick tunnel gave the proxy a public Request URL, the setup our ngrok vs Cloudflare comparison covers. Then a regular member and the app's bot posted messages in two channels:
Global and listener middleware in Bolt for Python
The global middleware drops messages from bots. The listener middleware lets the deploy listener run in one channel only:
import os
from slack_bolt import App, BoltResponse
app = App(
token=os.environ["SLACK_BOT_TOKEN"],
signing_secret=os.environ["SLACK_SIGNING_SECRET"],
)
ALLOWED = os.environ["ALLOWED_CHANNEL"]
@app.middleware # global: runs for every request
def drop_bot_messages(body, logger, next):
event = body.get("event", {})
if event.get("bot_id"):
logger.info("global: dropped bot message from %s", event["bot_id"])
return # next() not called
logger.info("global: pass %s in %s", event.get("type"), event.get("channel"))
next()
def only_allowed_channel(event, logger, next): # listener middleware
if event.get("channel") != ALLOWED:
logger.info("listener: skipped channel %s", event.get("channel"))
return
next()
@app.message("deploy", middleware=[only_allowed_channel])
def on_deploy(message, logger):
logger.info("handler: deploy from %s in %s", message["user"], message["channel"])
if __name__ == "__main__":
app.start(port=3000)
A middleware function can ask for the same arguments a listener gets, such as body, event, logger, client and context, plus next. The listener middleware runs after Bolt has matched "deploy" in the text, so it never saw "hello team".
The same middleware in Bolt for JavaScript
const { App, LogLevel } = require("@slack/bolt");
const app = new App({
token: process.env.SLACK_BOT_TOKEN,
signingSecret: process.env.SLACK_SIGNING_SECRET,
logLevel: LogLevel.INFO,
});
const ALLOWED = process.env.ALLOWED_CHANNEL;
// global middleware: runs for every incoming event
app.use(async ({ body, logger, next }) => {
const event = body.event || {};
if (event.bot_id) {
logger.info(`global: dropped bot message from ${event.bot_id}`);
return; // next() not called
}
logger.info(`global: pass ${event.type} in ${event.channel}`);
await next();
});
// listener middleware: runs only for the listener it is passed to
async function onlyAllowedChannel({ event, logger, next }) {
if (event.channel !== ALLOWED) {
logger.info(`listener: skipped channel ${event.channel}`);
return;
}
await next();
}
app.message("deploy", onlyAllowedChannel, async ({ message, logger }) => {
logger.info(`handler: deploy from ${message.user} in ${message.channel}`);
});
(async () => {
await app.start(3001);
console.log("bolt-js listening on 3001");
})();
In JavaScript, next is async, so await next() lets the middleware run code after the listener finishes. The ignoreSelf setting we changed for one test run is explained below.
Never appear "away" on Slack again
Cloud-based. No downloads. Works 24/7 even when your laptop is off.
Your own bot's messages never reach your middleware
Our first bot message, "deploy notice from the lab bot", got a 200 from both apps, and neither middleware logged it. Both Bolt versions have a built-in middleware that drops events sent by the app's own bot user before your code runs: ignoring_self_events_enabled in Python and ignoreSelf in JavaScript, both on by default. So a "drop bot messages" middleware only matters for other apps' bots and workflows. To test our middleware with the one bot we had, we started each app again with that setting off:
app = App(token=..., signing_secret=..., ignoring_self_events_enabled=False)
const app = new App({ token, signingSecret, ignoreSelf: false });
What happens when next() is not called
This is what the proxy recorded for Bolt for Python. A retry number of - is Slack's first delivery:
01:35:00.800 404 retry=- "deploy web to staging"
01:35:00.923 404 retry=1 "deploy web to staging"
01:35:02.663 404 retry=- "hello team"
01:35:02.803 404 retry=1 "hello team"
01:36:01.359 404 retry=2 "deploy web to staging"
01:36:03.034 404 retry=2 "hello team"
01:37:30.534 404 retry=- "build 412 finished (bot message, mode: n"
01:37:30.692 404 retry=1 "build 412 finished (bot message, mode: n"
01:38:31.098 200 retry=2 "build 412 finished (bot message, mode: n"
And what Bolt for Python logged for the same requests:
global: pass message in C0CKHP8ESFK
listener: skipped channel C0CKHP8ESFK
slack_bolt.App WARNING Unhandled request ({'type': 'event_callback', 'event': {'type': 'message'}})
"POST /slack/events HTTP/1.1" 404 -
global: dropped bot message from B0CK9KX55DH
slack_bolt.App WARNING A global middleware (CustomMiddleware(func=drop_bot_messages)) skipped calling either `next()` or `next_()` without providing a response for the request
"POST /slack/events HTTP/1.1" 404 -
Bolt for JavaScript logged the same decisions and answered 200 to all of them, so Slack sent each event once:
[INFO] bolt-app global: pass message in C0CKHP8ESFK
[INFO] bolt-app listener: skipped channel C0CKHP8ESFK
[INFO] bolt-app global: pass message in C0CK9FJM0RH
[INFO] bolt-app handler: deploy from U0CDVBA6TMZ in C0CK9FJM0RH
[INFO] bolt-app global: pass message in C0CK9FJM0RH
[INFO] bolt-app global: dropped bot message from B0CK9KX55DH
All results side by side:
| Message | Bolt for Python | Bolt for JavaScript |
|---|---|---|
| Our own bot posts (default settings) | 200; Bolt drops it before your middleware | 200; Bolt drops it before your middleware |
A bot message, global middleware returns without next() | 404 {"error": "no next() calls in middleware"}, Slack retried | 200, no retry |
A bot message, global middleware returns BoltResponse(status=200) | 200, no retry | (not needed) |
| "deploy" in the wrong channel, listener middleware skips | 404 "Unhandled request", Slack retried | 200, no retry |
| "hello team", no listener matches | 404 "Unhandled request", Slack retried | 200, no retry |
| "deploy" in the allowed channel | 200, handler ran | 200, handler ran |
Slack's third retry of "deploy web to staging" arrived at 01:41:01, six minutes after the first delivery. Every retry carried X-Slack-Retry-Reason: http_error. So a Python app that drops events this way gets each one up to four times. Slack's Events API docs also say Slack turns off event delivery for an app whose replies keep failing.
How to skip an event without a retry in Bolt for Python
Return a response instead of returning nothing. With this line in place of the bare return, the next bot message got a 200 and no retry:
from slack_bolt import BoltResponse
if event.get("bot_id"):
return BoltResponse(status=200, body="")
The listener case is different: the listener middleware worked, but no listener finished, so Bolt treated the whole request as unhandled. The same 404 came back for "hello team", which matched no listener at all. Bolt's own warning suggests the fix, a catch-all listener such as @app.event("message") that does nothing, registered after your other listeners. Bolt for JavaScript answered 200 even when no listener ran, which is why none of these cases reached Slack as an error there.
For tests of middleware without a live workspace, see our Bolt testing guide; errors that a listener raises are covered in Bolt error handling.
FAQ
What is the difference between global and listener middleware in Bolt? Global middleware runs for every request the app receives. Listener middleware runs only for the listener it is passed to, after Bolt has matched that listener.
Does Bolt middleware run for messages my own bot posts?
No, with default settings. Both Bolt for Python and Bolt for JavaScript drop the app's own bot events first. Turn this off with ignoring_self_events_enabled=False or ignoreSelf: false.
Why does Slack send my Bolt for Python app the same event again?
In our test it was a 404 from Bolt: a global middleware that returned without next(), or a message that no listener handled. Slack retried after about 0.2 seconds, 1 minute and 6 minutes.
Stop Jiggling Your Mouse.
Join hundreds of remote workers who never worry about their Slack status. Set it up once, stay green forever.
Related Articles
Slack App Configuration Token: Generate, Rotate and Revoke
An app configuration token lets a script create Slack apps from manifests. We generated one, rotated it five times and tested it again 28 hours later.
Slack App Collaborators: Add, Remove and Transfer Ownership
Collaborators are the people who can edit a Slack app. We added and removed one on 20 November 2026 as a regular member of a test workspace, recorded who can be added and what Slack asks you to do after a removal, and wrote down the hand-over path Slack documents.
Slack mpim: Open a Group DM With the API (Tested)
An mpim is a Slack group DM. We opened one with conversations.open and a bot token on 18 November 2026, posted to it, read conversations.info, and recorded the limit: 9 user IDs get too_many_users.