# Add a Custom Workflow Builder Step to a Slack Bolt App

Yes. An agent adds a custom step your Slack Bolt app serves to Workflow Builder: the manifest entry, an app.function handler, tests, and a PR with install steps.

[Run this on Rush](https://cloud.getrush.ai/run/add-custom-workflow-step/slack-bolt/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the app first. In an app like slack-samples/bolt-js-getting-started-app, `app.js` is the whole program: an `App` in Socket Mode with `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`, one `app.message('hello', ...)` listener that posts a section block with a button, one `app.action('button_click', ...)` that acknowledges and replies, and an async start on `PORT` or 3000. `manifest.json` declares a bot user, the scopes `channels:history`, `chat:write` and `im:history`, bot events `message.channels` and `message.im`, interactivity on, Socket Mode on and `org_deploy_enabled` true. `package.json` is `type: module` with `@slack/bolt` at `^5.1.0` (5.1.0 in the lock file) and a single `start` script; there is no test runner. `AGENTS.md` asks for no code comments and for the reason behind a change to go in the pull request description, and `.github/workflows/dependencies.yml` auto-merges Dependabot's patch and minor updates.

A custom step is a function the app serves to Workflow Builder. The agent adds `send_greeting` to a new `functions` section in `manifest.json`, with a `title`, a `description`, an `input_parameters` block of `user_id` (type `slack#/types/user_id`, required) and `message` (type `string`), and an `output_parameters` block with the posted message's timestamp, and subscribes the bot to the `function_executed` event, which is how Slack delivers a step run to the app. In code, `app.function('send_greeting', async ({ inputs, complete, fail, client }) => ...)` reads `inputs.user_id` and `inputs.message`, posts the message with `client.chat.postMessage`, which the existing `chat:write` scope covers, and calls `complete` with the outputs; the `catch` branch calls `fail` with the error message so the workflow shows why it stopped rather than hanging on a step that never finished.

To make the step testable without a workspace, the agent moves the listeners out of `app.js` into `listeners/` (`messages.js`, `actions.js`, `functions.js`) with a `register(app)` entry point, the layout the Bolt starter template uses, so `app.js` keeps only the `App` construction and the start call. It adds `node:test` tests in `tests/functions.test.js` that invoke the step handler with fake `inputs`, a stub `client.chat.postMessage`, and recording `complete` and `fail`, asserting that a successful post completes with the timestamp and a thrown error fails with its message; `package.json` gains a `test` script of `node --test`. It runs `node --check app.js` and `npm test`, and because the manifest is applied by hand in the app's settings (the README's step 0), the pull request lists exactly what to paste and where.

The agent cannot install the app or open Workflow Builder from the sandbox, and says so: the manifest change adds no scope, so an existing install keeps working, but the new `functions` block must be saved in the app configuration before the step appears in the Builder's step picker under the app's name. Socket Mode needs no change, because `function_executed` arrives over the same connection as the message events.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a custom Workflow Builder step to this Slack Bolt app. Read app.js, manifest.json, package.json, package-lock.json, AGENTS.md and README.md first. In manifest.json add a functions section with a send_greeting step: title, description, input_parameters user_id (slack#/types/user_id, required) and message (string), and output_parameters with the posted message timestamp; add function_executed to the bot events. Move the listeners into listeners/ (messages.js, actions.js, functions.js) with a register(app) entry so app.js only builds and starts the App. Implement app.function('send_greeting') to post inputs.message to inputs.user_id with client.chat.postMessage, call complete with the outputs on success and fail with the error message on failure. Add tests/functions.test.js using node:test with a stub client and recording complete and fail, and a test script of node --test. Follow AGENTS.md: no code comments, reasons in the pull request. Run node --check app.js and npm test until they pass, then open a pull request that explains how to update the app manifest in the app settings and where the step appears in Workflow Builder.",
  "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

The pull request changes `app.js`, `manifest.json` and `package.json`, and adds `listeners/messages.js`, `listeners/actions.js`, `listeners/functions.js`, `listeners/index.js` and `tests/functions.test.js`. Its description shows the manifest diff, quotes the `node --test` summary from the sandbox, and gives the three steps a maintainer takes next: paste the manifest into the app's settings, reinstall only if a scope was added (none was), and open Workflow Builder to find `send_greeting` under the app's name.

It records the reasons `AGENTS.md` keeps out of the code: why every path calls `complete` or `fail`, why the listeners moved into modules (so a handler can be called in a test without starting a socket), and why the step takes a user id rather than a channel, which is the shape Workflow Builder's own person picker provides.

Before merging, a reviewer runs the app once against a development workspace, adds the step to a test workflow, and checks the posted message and the output variable in the Builder. A step that must pause for a button press later is the natural follow-up, and the description points at the interactivity pattern for it.

## Run it on every Linear issue labelled slack-step

An automation on the Project with a `linear` trigger on `linear.issue.labeled`, `slack-step` in `config.labels`, and the prompt 'this issue describes a step a workflow builder should be able to add; declare it in manifest.json, implement it in listeners/functions.js with complete and fail on every path, test it with node --test, and open a pull request' starts one run per labelled issue once the first step exists. The trigger adds the issue after the prompt and fills in nothing else, so a request for a step that looks up a customer and a request for one that files a ticket each get their own function and test.

A team that maintains several Bolt apps sends this body once per repository from its own server, each `POST /o/{org}/sessions` 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. Each run reads its own manifest: an app that already serves steps gets the new one in the same section, and an app on HTTP mode instead of Socket Mode gets the same handler with the pull request noting that the request URL already receives the event.

## Why run it on Rush?

A custom step is small and unforgiving: a manifest and a handler that disagree on a parameter name, a path that returns without `complete` or `fail`, or a listener that cannot be exercised without a live socket, and the step silently never finishes in a workflow. The agent reads the manifest and the app as they are, keeps the change to the shape Slack documents, and leaves a test that runs in any sandbox.

The test output and the diff stay with the run, so a reviewer sees the success and failure paths asserted before touching a workspace. A team with several apps runs the same request across all of them at once.

## Frequently asked questions

### Do I have to reinstall the app?

Only if the manifest adds a scope. This step posts with `chat:write`, which the app already has, so saving the updated manifest in the app's settings is enough. A step that reads channel history or files would need its scope added and a reinstall, and the pull request would say so.

### Does this work in Socket Mode?

Yes. The `function_executed` event reaches the app over the same Socket Mode connection as the message events, so nothing about hosting changes. An app that moves to HTTP mode later keeps the same handler.

### Where does the step show up?

In Workflow Builder's step picker, under the app's name, in any workspace where the app is installed. The manifest's `org_deploy_enabled` is already true in this app, so an organization-wide install exposes it across workspaces.

### What happens if the handler never calls complete?

The workflow waits on that step, which is why the handler wraps the Slack call in a try and calls `fail` with the error message in the catch, and why the test asserts both paths. A step that intentionally pauses for a button must call `complete` or `fail` from the action handler instead, after acknowledging it.

## More Slack Bolt jobs

- [Write a Dockerfile for a Bolt for JavaScript Slack App](https://getrush.ai/run/add-dockerfile/slack-bolt/)
- [Deduplicate Retried Slack Events in a Bolt App](https://getrush.ai/run/add-event-deduplication/slack-bolt/)
- [Set Up GitHub Actions CI for a Slack Bolt App](https://getrush.ai/run/add-github-actions-ci/slack-bolt/)

## More jobs like this: Hand off a long task

- [Add DAG and Task Documentation to Airflow DAGs](https://getrush.ai/run/add-dag-docs/airflow/)
- [Add Params to Airflow DAGs](https://getrush.ai/run/add-dag-params/airflow/)
- [Add Timeouts to Airflow DAGs](https://getrush.ai/run/add-dag-timeouts/airflow/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
