Files
dragonroll/.agents/skills/discord-bot/SKILL.md
Aran Roig a6ad14a1b5
All checks were successful
Test / test (push) Successful in 1s
Build and Deploy Nuxt / build (push) Successful in 54s
Added skills
(cherry picked from commit bb4b3c4553)
2026-10-14 18:46:17 +02:00

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-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

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