# Add Modals to a discord.js Bot

Yes. An agent adds a modal interface, a submit handler and a sample command that opens a form to a discord.js bot, tests them and opens a pull request.

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

## What the agent does

The agent first finds where interactions are routed, because that is where modal submissions are being dropped today. On KevinNovak/Discord-Bot-TypeScript-Template, `package.json` pins `discord.js` at `^14.22.1` in an ES module project, and `src/models/bot.ts` has one `onInteraction` method: a `CommandInteraction` or `AutocompleteInteraction` goes to `commandHandler.process`, a `ButtonInteraction` goes to `buttonHandler.process`, and every other interaction type falls off the end of the `if`. Buttons are the closest existing pattern. `src/buttons/button.ts` declares a `Button` with `ids`, a `deferType`, two guard flags and `execute`; `src/events/button-handler.ts` rate-limits by user from `Config.rateLimiting.buttons`, looks the button up by `intr.customId`, defers, builds `EventData` and calls it. `src/start-bot.ts` collects `commands`, `buttons`, `reactions` and `triggers` in arrays marked with TODO comments and passes one handler for each into `new Bot(...)`.

It adds the modal path in that shape and adds nothing the template would not have written itself. A `src/modals/modal.ts` declares `Modal` with `ids`, a `ModalDeferType` and `execute(intr: ModalSubmitInteraction, data: EventData)`. A `ModalHandler` in `src/events/` mirrors the button handler line for line: ignore bots, take from a `RateLimiter` built from a new `rateLimiting.modals` block, find the modal by custom id, defer through `InteractionUtils`, whose `deferReply` and `send` signatures already accept `ModalSubmitInteraction`, then execute. `bot.ts` gains a third branch for modal submissions and a constructor argument, and `start-bot.ts` gains a `modals` array with the same TODO comment. The new block goes into `config/config.example.json`; the real `config/config.json` is ignored by `.gitignore` and loaded with `require`, so the pull request tells whoever deploys to add the block there too, or the handler's constructor will throw on the missing key.

The sample is where the one real trap sits. A modal has to be the first response to an interaction, and `CommandHandler` defers the reply before `execute` whenever a command's `deferType` is `PUBLIC` or `HIDDEN`. So the sample `/feedback` command is declared with `CommandDeferType.NONE` and calls `intr.showModal(...)` itself, building the form from `ModalBuilder`, `TextInputBuilder` and an `ActionRowBuilder`. Its name and description go through `Lang.getRef` into `src/commands/metadata.ts` with their localization maps, and the modal's title, field label and the confirmation embed go into `lang/lang.en-US.json` and `lang/lang.en-GB.json`, since the template keeps every user-facing string in those files. The submit side reads the field with `intr.fields.getTextInputValue` and answers with an embed from `Lang.getEmbed`.

Tests follow the existing ones under `tests/`, which build Discord objects with `mockDeep` in `tests/builders/discord-builders.ts` and mock `InteractionUtils`. The agent adds a modal-submit builder, a handler test (unknown id ignored, bot user ignored, rate-limited user ignored, known id deferred and executed) and a command test asserting that `showModal` is called and `deferReply` is not. It copies the three `*.example.json` files in `config/` to their real names inside the sandbox so the modules load, then runs `npm run lint`, `npm run format`, `npm run build` and `npm test`. It does not run `npm run commands:register`: that needs the bot's token, which the run does not have.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add modal support to this discord.js bot, following the way buttons are built. Read CLAUDE.md, package.json, src/models/bot.ts, src/start-bot.ts, src/buttons/button.ts, src/events/button-handler.ts, src/commands/command.ts, src/events/command-handler.ts, src/commands/metadata.ts, src/utils/interaction-utils.ts, config/config.example.json, lang/lang.en-US.json and the tests under tests/ first. Add a Modal interface in src/modals, a ModalHandler in src/events that mirrors ButtonHandler (bot check, per-user rate limit from a new rateLimiting.modals block in config.example.json, lookup by custom id, defer, execute), a branch for ModalSubmitInteraction in Bot.onInteraction and a modals array in start-bot.ts. Add a sample /feedback chat command that opens a modal with one paragraph field and a modal that answers with a confirmation embed. The command must use CommandDeferType.NONE and call showModal itself, because a modal cannot follow a deferred reply. Put every string in the lang files and the command in metadata.ts. Add test builders and tests for the handler and the command. Copy the example config files to their real names locally without committing them, then run npm run lint, npm run format, npm run build and npm test. Do not register commands with Discord. Open a pull request that says what to add to config.json and to run commands:register after merging.",
  "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

A pull request with `src/modals/` (the interface, an index and the feedback modal), `src/events/modal-handler.ts` and its export, the new branch in `src/models/bot.ts`, the wiring in `src/start-bot.ts`, the `/feedback` command with its entry in `src/commands/metadata.ts`, the strings in both lang files, the `rateLimiting.modals` block in `config/config.example.json`, and the builders and tests. Its description quotes the output of the four npm scripts and lists the two steps a person has to take after merging: add the block to the deployed `config.json`, and run `npm run commands:register` so Discord learns about `/feedback`.

A reviewer checks the custom ids first, since the handler matches on them and a typo means a submission that silently does nothing. They check that no command which opens a modal has a `deferType` other than `NONE`, and that the handler logs an unknown id the way `CommandHandler` logs an unknown command instead of returning quietly as `ButtonHandler` does, which the pull request calls out as a deliberate difference. The form itself can only be seen in a Discord client, so the last check is a person running `/feedback` on a test server.

## Run it on every Linear issue labelled bot-form

Once the handler exists, each new form is a small change: one modal class, one command or button that opens it, a few strings. In the console, add an automation on the bot's Project with a `linear` trigger on `linear.issue.labeled` and the label `bot-form`, and a prompt that says to add the form the issue describes using the `Modal` interface and the lang files. The issue arrives after the prompt as the event, so the fields and wording come from whoever wrote it. A person in your Rush org has to apply the label; a label set by an app integration does not fire.

The automation's own limit, its max runs per hour, decides how many of these start in an hour; an issue past it gets a run that waits as `queued`. Each run opens its own pull request on its own branch, so three forms asked for in one afternoon are three reviews, not one tangled diff.

## Why run it on Rush?

The template's value is its conventions, and a modal bolted on outside them is a second way of doing things. The agent reads the button path end to end in a fresh sandbox, copies its structure, and then runs the same four scripts a contributor would, with the complete output of each kept in the run's record. A reviewer can open that record and see `tsc` and `vitest` pass on the exact tree in the pull request.

It also avoids borrowing anyone's bot token. The config files that hold `client.token` are ignored by git and never reach the sandbox, so the run works from the example files and stops short of Discord. Someone who does want the agent to register commands on a test application can put a token in the Project as a secret and say so in the prompt; nothing in this request assumes it.

## Frequently asked questions

### Why does the sample command not defer its reply?

Discord accepts a modal only as the first response to an interaction. `CommandHandler` defers before `execute` for `PUBLIC` and `HIDDEN` commands, and a `showModal` after that is rejected. Declaring the command with `CommandDeferType.NONE` leaves the first response free for the modal.

### Can a button open a modal too?

Yes, with the same rule. A `Button` whose `deferType` is `ButtonDeferType.NONE` can call `showModal` in its `execute`. The pull request's sample uses a slash command because the template registers no buttons yet.

### Does the agent need my bot token?

No. Building, linting and the vitest suite run without one, and the tests replace Discord objects with deep mocks from `vitest-mock-extended`. Only `npm run commands:register` talks to Discord, and the request tells the agent to leave that to you.

### Will this work with sharding and clustering turned on?

The change does not touch `src/start-manager.ts` or the controllers. Interactions arrive on whichever shard owns the guild and go through the same `Bot.onInteraction`, so the modal branch behaves the same in every mode the template starts in.

## More discord.js jobs

- [Add a Slash Command to a discord.js Bot](https://getrush.ai/run/add-slash-command/discord-js/)
- [Enable TypeScript Strict Mode in a discord.js Bot](https://getrush.ai/run/enable-strict-mode/discord-js/)
- [Fix TypeError: Cannot Read Properties of Undefined (Reading 'FLAGS') in discord.js 14](https://getrush.ai/run/fix-intents-flags-removed/discord-js/)

## The same job on other stacks

- [Add a Modal to a Slack Bolt App](https://getrush.ai/run/add-modals/slack-bolt/)

## More jobs like this: Turn a Linear label into a PR

- [Add Model Contracts to a dbt Project](https://getrush.ai/run/add-model-contracts/dbt/)
- [Add a Fallback Model to a LangGraph Agent](https://getrush.ai/run/add-model-fallbacks/langgraph/)

## 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/)
