168 lines
8.2 KiB
Markdown
168 lines
8.2 KiB
Markdown
---
|
|
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] <current year>`
|
|
* `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
|