--- name: discord-bot description: Discord bot development on Cloudflare Workers — Discord API, Developer Portal, slash commands, Gateway WebSocket, Interactions Endpoint, bot permissions, intents, and Ed25519 verification. --- # Discord Bot Development Use this skill when working on Discord bots, Discord API integration, bot setup/configuration, or slash command registration. Triggered by mentions of Discord bots, Discord Developer Portal, Discord API, slash commands, Gateway, or Interactions Endpoint. ## Search before giving portal instructions The Discord Developer Portal UI changes often, so web-search current instructions before describing: * Where settings are located in the Developer Portal * OAuth2 flow steps * Bot permission configuration * Interactions Endpoint setup * Install link generation Useful queries: * `Discord Developer Portal [specific task] ` * `Discord bot setup [specific feature] latest` If search results are older than 6 months, note this to the user and suggest they verify in the portal. ## Discord Bot Architecture on Cloudflare Workers Two models for receiving Discord events: ### Interactions Endpoint (HTTP) * Discord POSTs slash commands and component interactions to your Worker URL * No persistent connection needed — pure request/response * Set the URL in Developer Portal → General Information → Interactions Endpoint URL * Requires Ed25519 signature verification on every request (`discord-interactions` npm package) * Supports: slash commands, buttons, select menus, modals, autocomplete ### Gateway (WebSocket) * Persistent WebSocket connection to `wss://gateway.discord.gg` * Required for: reaction events, message events, presence, voice state, typing indicators * On Cloudflare Workers: use a **Durable Object** with `new WebSocket(url)` for the outbound connection * NOT `fetch()` with `Upgrade: websocket` — that doesn't work for `wss://` URLs * DO won't hibernate while outbound WS is open — use alarm-based keepalive (30s interval) * Deploys evict the DO; alarm reconnects within ~30 seconds ### Which Do You Need? | Feature | Interactions Endpoint | Gateway | |---------|----------------------|---------| | Slash commands | Yes | Not needed | | Message reactions | No | Required | | Message content | No | Required (with intent) | | Typing indicators | No | Required | | Presence updates | No | Required | | Voice state | No | Required | Most bots need both: Interactions Endpoint for slash commands, Gateway for real-time events. ## Setting Up a New Discord Bot ### 1. Create Application * Go to https://discord.com/developers/applications * Click **New Application**, name it, click Create * Copy **Application ID** and **Public Key** from General Information page ### 2. Get Bot Token * Sidebar → **Bot** * Click **Reset Token**, copy immediately (shown once) * Toggle privileged intents as needed (see Intents section below) ### 3. Configure Installation * Sidebar → **Installation** * Enable **Guild Install** * Select **Discord Provided Link** * Under Default Install Settings → Guild Install: * **Scopes:** `bot`, `applications.commands` * **Permissions:** Select based on your bot's needs (see Permissions section) ### 4. Set Interactions Endpoint * Sidebar → **General Information** * Set **Interactions Endpoint URL** to your Worker's `/interactions` path * Discord sends a PING to verify — your code must handle it (return Pong) * Save — if verification fails, your endpoint isn't working ### 5. Register Slash Commands * Use `PUT https://discord.com/api/v10/applications/{app_id}/commands` * Global commands can take up to an hour to propagate * Guild-specific commands update instantly (useful for testing) ### 6. Install to Server * Copy the Install Link from the Installation page * Paste in browser, select server, authorize ## Intents Gateway intents control which events Discord sends to your bot. **Standard intents** (no approval needed): * `GUILDS` (1 << 0) — guild create/update/delete, role changes * `GUILD_MESSAGES` (1 << 9) — message create/update/delete in guilds * `GUILD_MESSAGE_REACTIONS` (1 << 10) — reaction add/remove **Privileged intents** (must be enabled in Developer Portal → Bot): * `MESSAGE_CONTENT` (1 << 15) — access to message content via Gateway AND REST API. Without this, `message.content` is empty for messages the bot didn't send or wasn't mentioned in. * `GUILD_MEMBERS` (1 << 1) — member join/leave/update events * `GUILD_PRESENCES` (1 << 8) — presence (online/offline) updates **No approval needed for bots in <100 servers.** Over 100 servers requires Discord review. ## Common Permissions | Permission | Bit | When needed | |-----------|-----|-------------| | View Channels | 1 << 10 | See channels and receive events from them | | Send Messages | 1 << 11 | Send messages (DMs, channel messages) | | Read Message History | 1 << 16 | Fetch messages via REST API | | Use Slash Commands | 1 << 31 | Use application commands | | Manage Roles | 1 << 28 | Assign/remove roles from members | | Add Reactions | 1 << 6 | Add reactions to messages | ## Common Gotchas ### Bot doesn't receive reaction events * **Missing intent:** Must request `GUILD_MESSAGE_REACTIONS` in Gateway IDENTIFY * **Missing VIEW_CHANNEL:** The bot's role needs View Channels permission. Public channels inherit from @everyone, but **private channels require the bot role to be explicitly added** to the channel's permissions ### Empty message.content from REST API * **Missing MESSAGE_CONTENT intent:** Must be enabled in Developer Portal → Bot → Privileged Gateway Intents. Also include `MESSAGE_CONTENT` (1 << 15) in the Gateway IDENTIFY intents value ### Slash command not visible * **Propagation delay:** Global commands take up to an hour. Use guild-specific commands for testing * **Permission restriction:** `default_member_permissions` hides commands from users without the specified permission * **Subcommand required:** If a command has subcommands defined, the base command can't be run alone — Discord requires picking a subcommand ### "The application did not respond" on a slash command that actually worked * Discord gives an interaction **3 seconds** to receive a response. A handler that runs its side effects synchronously before responding (REST calls, role changes, D1 writes) blows the deadline — Discord shows the error, but the Worker invocation keeps running, so the side effects still complete. Looks like a failure, is usually a success with a lost reply. * For any command doing more than ~1 REST round trip: immediately return type 5 (`DeferredChannelMessageWithSource`, keep the ephemeral flag if needed), run the work in `ctx.waitUntil()`, then PATCH the result to `/webhooks/{application_id}/{interaction_token}/messages/@original`. ### WebSocket connection drops on Cloudflare Workers * **DO eviction:** Use alarm-based keepalive (30s interval) to prevent idle eviction * **Deploy:** Deploys always evict the DO. Alarm reconnects within ~30s. Use `/gateway/reconnect` for immediate recovery * **Use `new WebSocket(url)` not `fetch()` with Upgrade header** for `wss://` URLs ### Discord rate limits * REST API returns 429 with `retry_after` field (seconds). Wait and retry. * Gateway has identify rate limits (1 per 5 seconds). Don't reconnect in a tight loop. ## Verification Checklist When setting up or debugging a Discord bot: - [ ] Bot token is set and valid (test with `GET /api/v10/users/@me`) - [ ] Interactions Endpoint URL is set and verified (Developer Portal shows success) - [ ] Slash commands are registered (`PUT .../commands` returns 200) - [ ] Bot is installed to the target server (visible in member list) - [ ] Bot role has necessary permissions (check via REST API `GET /guilds/{id}/members/{bot_id}`) - [ ] Privileged intents are enabled in Developer Portal if needed - [ ] Gateway intents in IDENTIFY include all needed flags - [ ] VIEW_CHANNEL permission is set for private channels - [ ] Gateway connection is alive (`/gateway/status` returns `connected: true`) ## Reference: Elereada v2 Working example of a Discord bot on Cloudflare Workers: `github.com/rianvdm/elereada-v2` * Durable Object outbound WebSocket for Gateway * Hono for HTTP routing + Interactions Endpoint * D1 for storage * Alarm-based keepalive for DO persistence * Ed25519 verification via `discord-interactions` package