8.2 KiB
name, description
| name | description |
|---|---|
| discord-bot | 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-interactionsnpm 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()withUpgrade: websocket— that doesn't work forwss://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)
- Scopes:
4. Set Interactions Endpoint
- Sidebar → General Information
- Set Interactions Endpoint URL to your Worker's
/interactionspath - 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 changesGUILD_MESSAGES(1 << 9) — message create/update/delete in guildsGUILD_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.contentis empty for messages the bot didn't send or wasn't mentioned in.GUILD_MEMBERS(1 << 1) — member join/leave/update eventsGUILD_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_REACTIONSin 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_permissionshides 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 inctx.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/reconnectfor immediate recovery - Use
new WebSocket(url)notfetch()with Upgrade header forwss://URLs
Discord rate limits
- REST API returns 429 with
retry_afterfield (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 .../commandsreturns 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/statusreturnsconnected: 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-interactionspackage