Discord bot builder
Deliver a bot that performs the requested action in Discord, not just a repository of starter files. Follow the existing project's language and runtime where possible. Use the current Discord quick start, application commands, and interaction response documentation as the authority for API behavior.
Inputs: define one working vertical slice
Identify the bot's users, install context (server, user, or both), exact commands and options, response visibility (public or ephemeral), data it must store, hosting target, and an acceptance test. Inspect an existing codebase before picking a library. For a new project, choose a maintained library and runtime supported by the environment; record the version so method names can be checked against its documentation.
Write one command contract before coding:
| Contract field | Example for a fictional /status command |
|---|---|
| Input | No arguments; only server members may call it |
| Success | Ephemeral “Service is available” with checked time |
| Error | Ephemeral “Status is temporarily unavailable” |
| Side effects | None |
| Verification | Run in a test server as allowed and disallowed users |
Change the contract to match the user's bot. Commands that mutate data need explicit authorization rules, idempotency or duplicate handling, and a way to report partial failure.
Workflow: choose the interaction architecture
Prefer application commands for user-initiated tasks. A public HTTP interactions endpoint is a good fit for serverless or request-driven hosting; verify Discord's signature against the raw request body, handle its PING challenge, and expose the URL over HTTPS. A Gateway connection fits long-lived event listeners or stateful features; request only the intents those events require. Do not enable privileged intents just to make a slash command work. If the existing project already has a functioning architecture, extend it rather than rebuilding it.
For either path, register commands in a test guild first so changes can be exercised before wider registration. Use the required installation scopes and only the bot permissions needed for the actions. Distinguish OAuth scopes, bot permissions, command contexts, and Gateway intents; they solve different problems. Record the final choices in a small permissions table.
Discord requires an initial interaction response within three seconds. A task that may take longer should acknowledge or defer promptly, run the work, and edit the response or send a follow-up within the interaction token's validity window. Choose ephemeral responses for private results or permission errors. Escape or suppress unwanted mentions in user-supplied output.
3. Build the smallest end-to-end implementation
Keep command registration, interaction verification/dispatch, business logic, and configuration separate enough that each can be tested. For a new JavaScript project, this might be src/register-commands.js, src/interactions.js, src/commands/status.js, and .env.example; adapt to the existing project rather than forcing these filenames.
The handler's essential path is:
receive interaction
→ verify source (for HTTP) and recognize PING
→ identify command and validate options/context
→ check authorization and required permission
→ reply or defer before the interaction deadline
→ perform work with bounded timeouts and safe retries
→ edit or follow up with success or actionable error
Use environment variables or a secrets manager for the bot token, application ID, public key, and service credentials. Commit only a placeholder .env.example; ignore actual secrets. Never print tokens, request signatures, private message content, or raw interaction payloads into ordinary logs. Rotate a leaked token rather than merely deleting it from the latest commit.
4. Exercise behavior, not just compilation
Test pure command logic with representative valid and invalid inputs. Then install the app in a test server or test user context and invoke the command. Verify:
- The command appears in the intended context and completes before timeout.
- Allowed users receive the intended result; disallowed users receive a clear private denial.
- Missing or malformed options, service failures, and unavailable permissions are handled.
- Repeating a mutating command does not duplicate its effect unexpectedly.
- No token or private content appears in logs or committed files.
- Registration can be repeated safely and the bot can restart without losing required state.
Record the test account/context and actual outcome. If credentials, a test guild, or an accessible endpoint are unavailable, complete source and local tests, mark the live interaction unverified, and give the exact steps needed to verify it. Do not claim a bot works because it starts or typechecks.
5. Deploy and hand off
Provide source files, install/run commands, required environment variable names, a command list, permissions/intents table, deployment and restart procedure, and tested results. Include a minimal rollback or disable path for a bad release, a credential rotation note, and how to unregister an obsolete command. For bots that retain user data, document what is stored and how it is removed.
Worked example: If a user asks for “a support bot that answers /faq topic,” first implement one recognized topic and a private unknown-topic response. Test both in a guild, then add remaining topics and any external knowledge source. Avoid collecting message history or requesting Message Content intent for this command unless another approved feature actually needs it.
Use the Discord bot skill guide for a reader-facing walkthrough. Recheck current Discord documentation before writing library-specific code because endpoint and SDK details change.
