--- name: "discord-bot-stinger" description: "Build Discord bots. Use for slash commands, modals, voice, gateway design, rate limits, or verification. Read README.md for the guide map." license: AGPL-3.0-or-later --- # discord-bot-stinger Start with [README.md](README.md) for the workflow map and detailed references. Equips `discord-bot-wasp-drone` to build, review, and audit Discord bots and applications on the 2026 Discord API surface. Read this file first on every invocation, then follow the guide pointer for the specific task. --- ## Quick-reference: critical API facts (May 2026) | Fact | Value | Source | |------|-------|--------| | discord.js stable | **v14.25.1** (v15 pre-release, ~94% milestone; not production-ready) | `research/external/2026-05-20-discordjs-v15-status.md` | | discord.py stable | **v2.x** (CommandTree + app_commands) | `research/external/2026-05-20-discordpy-app-commands.md` | | Wavelink status | **ABANDONED**: do not recommend | `research/external/2026-05-20-wavelink-deprecated.md` | | Voice clients (Python) | **Mafic** or **lavalink.py** (both DAVE-compliant) | `research/external/2026-05-20-lavalink-clients-2026.md` | | Voice clients (Node.js) | **Shoukaku** or **Lavalink-Client** (both DAVE-compliant) | `research/external/2026-05-20-lavalink-clients-2026.md` | | Lavalink version | **v4** | `research/external/2026-05-20-lavalink-clients-2026.md` | | DAVE protocol | Mandatory in all voice channels since **March 1, 2026** | `research/external/2026-05-20-discord-changelog-2026.md` | | Discord API version | **v10** (Gateway v10) | `research/external/2026-05-20-discord-api-v10-changes-2026.md` | | Sharding required at | **2,500 guilds** (hard enforcement) | `research/external/2026-05-20-discord-sharding-guide.md` | | Privileged intent gate | Apply at **75 servers**; hard block at **100** | `research/external/2026-05-20-discord-privileged-intents.md` | | Data retention limit | **30 days** max for privileged intent approval | `research/external/2026-05-20-discord-privileged-intents.md` | | Global command propagation | **~1 hour** | `research/external/2026-05-20-discord-application-commands-spec.md` | | Guild command propagation | **Instant**: use in dev | `research/external/2026-05-20-discord-application-commands-spec.md` | | Modal custom_id max | **100 characters** | `research/external/2026-05-20-discord-components-modals.md` | | Buttons per message | **25 max** (5 action rows × 5 buttons) | `research/external/2026-05-20-discord-components-modals.md` | | Node.js minimum | **22.12.0** for discord.js | `research/external/2026-05-20-discordjs-v14-slash-commands.md` | --- ## Critical directives (non-negotiables) Every code sample, review comment, and recommendation from this stinger must respect: 1. **Never hardcode bot tokens or client secrets.** Use `process.env.DISCORD_TOKEN` (JS) or `os.environ["DISCORD_TOKEN"]` (Python). Tokens committed to source are harvested by secret-scanning bots immediately. 2. **Always specify the minimum required Gateway Intents.** Over-privileged intents trigger the Privileged Intent approval gate, slow verification, and increase PII exposure. See `guides/03-gateway-intents.md`. 3. **Pin SDK major versions in package manifests.** discord.js and discord.py introduce breaking changes. Unpinned installs silently break bots in CI. 4. **Surface bot-verification at 75 servers, not 100.** The verification application takes 1-5 business days; missing the gate hard-blocks new guild joins. See `guides/06-verification-checklist.md`. 5. **Register commands to a test guild during development.** Global registration has ~1 hour propagation delay; guild-scoped is instant. See `guides/02-slash-commands.md`. 6. **Do not recommend Wavelink.** It is abandoned. Use Mafic/lavalink.py (Python) or Shoukaku/Lavalink-Client (Node.js). See `guides/04-voice-pipeline.md`. 7. **All new voice code must use DAVE-compliant clients.** The DAVE E2EE protocol is mandatory in all voice channels since March 1, 2026. --- ## Guide index | Guide | When to use | |-------|-------------| | `guides/00-principles.md` | Architecture decisions: gateway vs HTTP, intent scoping, token hygiene | | `guides/01-sdk-selection.md` | Choosing between discord.js, discord.py, Serenity, and forks | | `guides/02-slash-commands.md` | Authoring slash, user-context, message-context commands; DeferReply pattern | | `guides/03-gateway-intents.md` | Minimum-intent discipline, privileged intents, partial intents | | `guides/04-voice-pipeline.md` | Lavalink 4 setup, DAVE-compliant clients, queue + event model | | `guides/05-scaling-ops.md` | Sharding, REST-only mode, rate-limit handling, container health checks | | `guides/06-verification-checklist.md` | Bot verification step-by-step (75-server trigger, 100-server hard block) | | `guides/07-components-modals.md` | Buttons, select menus, modals, custom_id namespacing, ephemeral flows | --- ## Template index | Template | Purpose | |----------|---------| | `templates/slash-command-discord-js.ts` | Minimal idiomatic slash command for discord.js v14 | | `templates/slash-command-discord-py.py` | Minimal idiomatic slash command using discord.py app_commands | | `templates/voice-queue-discord-js.ts` | Lavalink 4 + Shoukaku queue stub for discord.js | | `templates/bot-verification-checklist.md` | Fillable checklist for the 100-server verification process | | `templates/audit-report.md` | Skeleton for a full bot audit report | --- ## Example index | Example | Demonstrates | |---------|-------------| | `examples/happy-path-slash-command.md` | End-to-end: register command, handle interaction, DeferReply | | `examples/edge-case-modal-timeout.md` | Modal flow with orphaned-interaction handling | --- ## Open questions (flagged by scripture-historian) > **TODO: stinger-forge open questions; resolve before next refresh:** 1. **Serenity/Poise (Rust)**: API surface not fully covered in research. Guides reference Rust conceptually; confirm `poise` slash command macro syntax from `docs.rs/poise` before next refresh. 2. **DisTube DAVE support**: Not confirmed. `guides/04-voice-pipeline.md` omits DisTube from active recommendations until DAVE compatibility is verified at `github.com/skick1234/DisTube`. 3. **Lavalink 4 Docker Compose YAML**: Reference snippet not retrieved. `guides/04-voice-pipeline.md` provides the install URL; embed the snippet on next refresh. 4. **discord.js REST rate-limit knobs**: Specific `RESTOptions` fields not retrieved. `guides/05-scaling-ops.md` covers the pattern; add specific field names on next refresh. 5. **Pycord vs discord.py**: Pycord is a maintained fork with growing adoption. `guides/01-sdk-selection.md` acknowledges the fork; defaults remain the Rapptz main-line unless the user specifies Pycord. --- ## Refresh cadence - **Trigger immediately**: discord.js v15 reaches stable; Wavelink resumes maintenance (check `github.com/PythonistaGuild/Wavelink`); Discord announces API v11. - **Annual review**: Full `normal`-depth scripture-historian re-run. - **Quarterly**: Skim `discord.com/developers/docs/change-log` for breaking changes. --- *Forged by stinger-forge from `ai-tools/command-briefs/discord-bot-wasp-drone-command-brief.md` + `research/research-summary.md`. Part of The Wasp Nest, curated by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*