All jobs

Add Health Checks to a Socket Mode Slack Bolt App

Yes. An agent adds liveness and readiness routes to your Socket Mode Bolt app that report the WebSocket's real state, tested without a workspace, as a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the app connects to Slack before adding a probe, because a Socket Mode app has no inbound HTTP and a health check copied from a web service would probe nothing. In the app from slack-samples/bolt-js-getting-started-app, package.json depends on @slack/bolt ^5.1.0 alone, with "type": "module" and a single start script, and package-lock.json resolves @slack/socket-mode and @slack/web-api beneath it. app.js constructs new App({ token, socketMode: true, appToken }), registers a message('hello') listener and a button_click action, and calls app.start(process.env.PORT || 3000). manifest.json has socket_mode_enabled true and no request URL. AGENTS.md asks for no code comments, with reasons in the pull request. The one workflow, dependencies.yml, auto-merges Dependabot's minor and patch updates.

Bolt's Socket Mode receiver can serve HTTP after all: when customRoutes is given, it creates a Node http server on installerOptions.port, which defaults to 3000, and listens on it from start(). The port argument passed to app.start is not what that server uses, which the pull request says plainly because the existing call suggests otherwise. The agent builds the receiver explicitly as new SocketModeReceiver({ appToken, customRoutes, installerOptions: { port } }) and passes it to App through receiver, which is the only way to reach the receiver's client, the SocketModeClient that emits connecting, connected, authenticated, reconnecting, disconnecting and disconnected. A small connectionState module subscribes to those events, keeps the latest name and the time it changed, and exposes a function the routes read.

The routes are two. GET /healthz answers 200 with { status: 'ok' } whenever the process is up, so a Slack outage never makes an orchestrator restart a process that will reconnect by itself. GET /readyz answers 200 with { status: 'ok', socket: 'connected', since } when the latest state is connected or authenticated, and 503 with the current state when it is anything else, including the window after start() before the first hello from Slack. Both set Cache-Control: no-store. Readiness means something for a Socket Mode app because a process whose WebSocket has been reconnecting for minutes is not receiving events, and that is the state a dashboard should show. The port comes from HEALTH_PORT with 3000 as the fallback, and the README gains a line per variable.

The agent proves this without a Slack workspace. test/health.test.js, run by a new test script using node --test, constructs the receiver with placeholder tokens, drives the connectionState module by emitting the client's events in sequence, starts only the HTTP server through the receiver's own httpServer on an ephemeral port, and asserts /readyz is 503 before any event, 200 after connected, 503 after reconnecting and 200 again after authenticated, while /healthz is 200 throughout. It runs npm install, npm test and node --check app.js, then starts the app once with placeholder tokens to show the HTTP server bound and /readyz answering 503 with connecting while the app fails to authenticate, and opens the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add health checks to this Socket Mode Bolt for JavaScript app. Read package.json, package-lock.json, app.js, manifest.json, README.md and AGENTS.md first. Build the receiver explicitly with new SocketModeReceiver and pass it to App through receiver, keeping the message and action listeners as they are. Add a connectionState module that subscribes to the receiver's client events connecting, connected, authenticated, reconnecting, disconnecting and disconnected and keeps the latest state and when it changed. Add customRoutes with GET /healthz, which answers 200 with status ok and no I/O, and GET /readyz, which answers 200 with the socket state and the time since it changed when the state is connected or authenticated, and 503 with the current state otherwise; set Cache-Control no-store on both. Serve them on installerOptions.port read from HEALTH_PORT with 3000 as the fallback, and explain in the pull request that the argument to app.start is not the port this server uses. Add a test script using node --test and test/health.test.js that builds the receiver with placeholder tokens, emits the client events in sequence, starts only the receiver's HTTP server on an ephemeral port, and asserts /readyz is 503 before any event, 200 after connected, 503 after reconnecting and 200 after authenticated, with /healthz 200 throughout. Follow AGENTS.md: no code comments. Document HEALTH_PORT in README.md. Run npm install, npm test and node --check app.js, start the app with placeholder tokens to show the HTTP server bound and /readyz answering 503 while authentication fails, and open a pull request that pastes the responses.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes app.js, package.json and README.md, and adds connectionState.js and test/health.test.js. The description pastes the node --test summary with the four readiness transitions, the responses from /healthz and /readyz against the app started with placeholder tokens, showing 503 and the connecting state while Slack refuses the token, and says in one paragraph why installerOptions.port and not the app.start argument decides the port.

The run's record holds the install, the test run, the syntax check and the short run with placeholder tokens. The listeners for the hello message and the button are untouched, and manifest.json does not change because the app stays in Socket Mode.

Before merging, a reviewer decides whether the Dockerfile or deployment should expose the health port, which orchestrator probe maps to which route, and whether a long reconnecting state should also alert somewhere beyond the readiness answer.

Run it on every new Slack app

A team that runs several Socket Mode apps starts one run per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request. Each run reads that app's own receiver setup, so an app already using HTTP mode gets its routes added to the existing receiver instead of a second server.

Afterwards, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request changes how the App or receiver is constructed, run the health test and comment with whether the readiness route still tracks the socket state" keeps a refactor from quietly disconnecting the probe from the client it watches. The trigger adds the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Socket Mode app can be alive, bound to a port and useless, because its WebSocket has been reconnecting for an hour, and a health check that returns 200 for a running process hides exactly that. The agent reads the receiver and client source to find the events that describe the connection, wires the readiness answer to them, and drives every transition in a test in its own sandbox, so the reviewer sees the 503 during reconnecting rather than trusting a route that always says ok.

The sandbox keeps the test run and the responses with the run, and the pull request cites them. For a team with many Slack apps, each gets its own run and its own pull request with the same two paths, so one probe configuration serves all of them.

Frequently asked questions

Why does a Socket Mode app need an HTTP port at all?

Slack never calls it, but an orchestrator does. Socket Mode replaces inbound event delivery with an outbound WebSocket; liveness and readiness probes are a separate concern, and Bolt's receiver serves customRoutes on its own small HTTP server for exactly this. Nothing about the Slack side of the app changes and the manifest stays as it was.

Why is the port not the one passed to app.start?

Because with Socket Mode the receiver's start() opens the WebSocket and, when custom routes exist, listens on installerOptions.port, which defaults to 3000; the argument given to app.start is forwarded but not used for that server. The agent sets installerOptions.port from HEALTH_PORT and says so in the pull request, so the existing process.env.PORT || 3000 line stops being misleading.

What does readiness report before the first connection?

503 with the state connecting, which is the honest answer during the window between start() and Slack's hello message, and again whenever the client reports reconnecting or disconnected. Liveness stays 200 through all of it, so the process is left alone to reconnect.

How does the test run without a workspace?

The receiver is built with placeholder tokens and never asked to open the WebSocket; the test starts only its HTTP server and emits the client's state events itself. That exercises the state module and both routes end to end on a real socket, while the only Slack call that would fail is never made.

More Slack Bolt jobs

The same job on other stacks

Keep reading