Discord -- Community Integration Expert

---

name: discord description: > Build Discord bots, slash commands, embeds, and voice channel integrations. USE WHEN: User needs to implement Discord bots, slash commands, embeds, voice features, or community automation. DON'T USE WHEN: User needs general chat integration. Use Slack for workspace messaging. Use Relay for notification patterns. OUTPUTS: Bot configurations, slash command handlers, embed builders, voice implementations, permission systems, gateway event handlers. version: 1.0.0 author: SpookyJuice tags: [discord, bots, slash-commands, embeds, voice, community] price: 14 author_url: "https://www.shopclawmart.com" support: "brian@gorzelic.net" license: proprietary osps_version: "0.1" content_hash: "sha256:f5d3c25739171a4ffb043678da94f24546cbb90614da17f9ac657e53d9868e8c"

#‍​‌‌​‌‌‌‌​‌‌‌​​‌‌​‌‌‌​​​​​‌‌‌​​‌‌​​‌‌‌​‌​​​‌‌​​​‌​​‌‌‌​‌​​‌‌‌​​‌‌​‌‌​‌​‌​​​‌​‌‌​‌​​‌‌‌​​​​​‌‌​​​​​​‌‌​‌‌‌​‌‌​​‌‌​​​‌‌‌​​​​‌‌​​​‌‌​​‌‌​​‌‌​‌‌​​​‌‌‍ Discord

Version: 1.0.0 Price: $14 Type: Skill

Description

Production-grade Discord integration patterns for bots that handle real community load. Discord's gateway API demands careful intent selection, slash command registration has a global vs. guild propagation split that confuses every first-time builder, and rate limiting is per-route with burst buckets that punish naive implementations. The real pain surfaces at scale: sharding thresholds, permission bit manipulation across role hierarchies, embed field limits that silently truncate, and voice connections that drop without proper heartbeat handling. This skill gives you patterns that survive 10k+ member servers, not quickstart demos.

Prerequisites

• Discord Developer account at discord.com/developers
• Bot application created with bot user enabled
• Bot token: found under Bot tab in application settings
• Privileged Gateway Intents enabled: Message Content, Server Members, Presence (as needed)
• Node.js 18+ or Python 3.10+ for bot runtime

Setup

1. Copy SKILL.md into your OpenClaw skills directory
2. Set environment variables:

   export DISCORD_BOT_TOKEN="your-bot-token"
   export DISCORD_CLIENT_ID="your-application-client-id"
   export DISCORD_GUILD_ID="your-dev-server-id"  # for dev-only command registration
   

3. Reload OpenClaw

Commands

• "Build a Discord bot for [use case]"
• "Register slash commands for [feature set]"
• "Create rich embeds for [content type]"
• "Implement voice channel [join/playback/recording]"
• "Set up auto-moderation for [community rules]"
• "Handle gateway events for [member/message/reaction tracking]"
• "Design a role-based permission system for [server structure]"

Workflow

Bot Architecture

1. Gateway connection -- choose between discord.js (Node.js, largest ecosystem, best TypeScript support) or discord.py (Python, cleaner async patterns, cog system). Initialize the client with explicit intent flags -- Discord rejects connections that request intents the bot hasn't been approved for, and the error message doesn't tell you which intent failed.
2. Intent selection -- intents control which events the gateway sends your bot. Non-privileged intents (Guilds, GuildMessages, MessageContent for DMs) work immediately. Privileged intents (GuildMembers, GuildPresences, MessageContent for guild messages) require manual approval in the Developer Portal for bots in 100+ servers.
3. Event handling -- register listeners for gateway events using the framework's event system. Critical events: ready (bot connected), interactionCreate (slash commands, buttons, modals), guildMemberAdd/Remove (join/leave tracking), messageCreate (message processing). Always handle error and shardError to prevent silent crashes.
4. Command framework -- structure commands as individual modules (discord.js Collection pattern or discord.py Cogs). Each command module exports: command definition (name, description, options), permission requirements, and execute handler. Load commands dynamically from a directory so adding commands doesn't require code changes to the main bot file.
5. Sharding strategy -- Discord requires sharding at 2,500 guilds. Use the framework's built-in ShardingManager (discord.js) or AutoShardedClient (discord.py) rather than manual shard management. Each shard maintains its own gateway connection and handles a subset of guilds. Cross-shard communication uses IPC or a shared data store like Redis.
6. Graceful shutdown -- handle SIGINT and SIGTERM to cleanly disconnect from the gateway, finish processing in-flight interactions (you have 3 seconds to respond to an interaction before it expires), and close database connections. Without this, your bot leaves ghost sessions that block reconnection for several minutes.

Slash Commands

1. Registration model -- guild commands update instantly (use for development). Global commands take up to one hour to propagate across all servers. Register guild commands during development by passing a guild ID, then switch to global registration for production deployment.
2. Command definition -- define commands with SlashCommandBuilder (discord.js) or app_commands (discord.py). Each command has: name (lowercase, no spaces, max 32 chars), description (max 100 chars), and up to 25 options. Option types: String, Integer, Boolean, User, Channel, Role, Mentionable, Number, Attachment.
3. Autocomplete -- options with autocomplete: true trigger a separate autocomplete interaction as the user types. Respond with up to 25 choices within 3 seconds. Use this for dynamic data (search results, database lookups) instead of static choice lists. Cache frequent autocomplete queries to stay within the response window.
4. Subcommands -- group related functionality with subcommands and subcommand groups. Structure: /settings notifications enable, /settings notifications channel #alerts. Maximum depth is group > subcommand (two levels). Subcommands are not individual commands -- they share the parent command's permissions.
5. Permission defaults -- set default_member_permissions on the command definition to restrict by permission flag (e.g., MANAGE_GUILD for admin commands). Server admins can override these defaults per role or channel in Server Settings > Integrations. Use dm_permission: false to block commands in DMs.
6. Deferred responses -- if your command handler takes more than 3 seconds (database queries, external API calls), call deferReply() immediately. This gives you 15 minutes to send the actual response via editReply(). Without deferral, the interaction token expires and the user sees "This interaction failed."

Rich Embeds & Components

1. Embed construction -- build embeds with: title (256 chars), description (4096 chars), up to 25 fields (name: 256 chars, value: 1024 chars each), footer (2048 chars), author, thumbnail, and image. Total embed content across all fields cannot exceed 6000 characters. Send up to 10 embeds per message.
2. Button rows -- add up to 5 ActionRows per message, each containing up to 5 buttons. Button styles: Primary (blurple), Secondary (grey), Success (green), Danger (red), and Link (opens URL, no interaction event). Each non-link button needs a unique customId (max 100 chars) that your interaction handler matches on.
3. Select menus -- StringSelectMenu for custom options (up to 25), UserSelectMenu, RoleSelectMenu, ChannelSelectMenu, and MentionableSelectMenu for Discord object pickers. Each select menu takes a full ActionRow (one per row). Set min_values and max_values for multi-select.
4. Modal forms -- triggered by button or slash command interactions (not by select menus or other modals). Modals contain up to 5 ActionRows, each with one TextInput (short or paragraph). Collect: text input with min/max length, placeholder text, and pre-filled values. Modal submissions arrive as a separate interaction event.
5. Component collectors -- set up interaction collectors to listen for button/select menu responses on a specific message. Configure: filter (only the original user), time limit (prevent stale interactions), and max interactions. Handle the end event to disable components when the collector expires so users don't click dead buttons.
6. Pagination pattern -- for large data sets, build a pagination embed with Previous/Next buttons. Store the current page index in the button's customId (e.g., page_3_next). Update the embed content and buttons via interaction.update() to avoid creating new messages. Disable Previous on page 1 and Next on the last page.

Community Management

1. Auto-moderation -- use Discord's native AutoMod API to create rules: keyword filters (regex supported), spam detection, mention spam limits, and blocked links. AutoMod runs before your bot sees the message, so it catches content faster than bot-side filtering. Supplement with bot-side checks for complex rules like image scanning or context-aware moderation.
2. Role management -- implement reaction roles (user reacts to a message, bot assigns a role) or button roles (cleaner, no reaction limit). Track role assignments in your database to handle edge cases: role deleted from server, user already has role, bot's role hierarchy too low to assign. Always check guild.members.me.roles.highest against the target role position before attempting assignment.
3. Audit logging -- listen to moderation events: guildBanAdd, guildBanRemove, guildMemberUpdate (role/nickname changes), messageDelete, messageUpdate. Log to a designated channel with embeds showing: who, what, when, and the original content for deleted messages. Pull from Discord's native audit log via guild.fetchAuditLogs() to identify which moderator took the action.
4. Welcome flows -- handle guildMemberAdd to send welcome messages (DM or channel), assign default roles, and start verification flows. For verification: send a DM with a button, member clicks it, bot assigns the verified role and grants channel access. Handle: DMs disabled (fall back to a welcome channel mention), member leaving before verifying, and re-joining members who were previously verified.
5. Scheduled events -- use Discord's native ScheduledEvent API for server events with RSVP tracking. Create events with: name, description, start/end time, location (voice channel, stage, or external URL). Listen to guildScheduledEventUserAdd/Remove for RSVP changes. Send reminders via DM or channel mention before the event starts.
6. Ticket system -- implement support tickets with button-triggered private channels (or threads for lower overhead). On button click: create a channel with permissions for the user and support staff only, send an initial embed with the issue template, and add Close/Claim buttons. On close: generate a transcript, send it to a log channel, and delete or archive the ticket channel.

Output Format

DISCORD -- IMPLEMENTATION GUIDE
Integration: [Bot/Commands/Embeds/Community]
Server: [Development/Production]
Date: [YYYY-MM-DD]

=== ARCHITECTURE ===
[Gateway connection flow: client -> intents -> event handlers -> command router]

=== IMPLEMENTATION ===
[Code snippets with inline comments explaining each decision]

=== CONFIGURATION ===
| Setting | Value | Why |
|---------|-------|-----|
| [config] | [value] | [rationale] |

=== GATEWAY EVENTS ===
| Event | Handler | Action | Notes |
|-------|---------|--------|-------|
| [event] | [handler] | [what it does] | [edge cases] |

=== TESTING CHECKLIST ===
- [ ] [Test scenario with expected behavior]

=== COMMON PITFALLS ===
- [Pitfall and how to avoid it]

Common Pitfalls

• Missing privileged intents -- your bot connects but receives no member or message events. The Developer Portal requires you to manually toggle privileged intents, and bots in 100+ servers need Discord's approval. The gateway disconnect error code (4014) doesn't clearly state which intent is missing.
• Global vs. guild command registration delay -- global commands take up to one hour to propagate. Developers register globally, see nothing, and re-register in a loop that creates duplicate commands. Use guild commands during development (instant), global commands for production only.
• Interaction token expiry -- you have 3 seconds to respond to an interaction (or defer it) and 15 minutes to follow up after deferring. Expired tokens throw errors that look like network failures. Always defer for any handler that might be slow.
• Embed field limits -- total character count across all embed fields must stay under 6000. The API returns a generic "Invalid Form Body" error with no indication of which field exceeded limits. Validate total length before sending.
• Permission integer overflow -- Discord permissions are a bitfield stored as a string (too large for 32-bit integers). Using standard integer operations in JavaScript silently truncates permission values. Always use BigInt for permission calculations or use the framework's built-in permission utilities.
• Rate limit per-route buckets -- Discord rate limits are per-route, not global. Sending 5 messages to channel A doesn't affect your limit for channel B. But hitting a rate limit on one route can trigger a global cooldown if you're flagged for abuse. Respect X-RateLimit-Remaining headers and implement exponential backoff.

Guardrails

• Never exposes bot token. The bot token is server-only and never appears in client-side code, logs, or error messages. Token leaks grant full bot account access -- Discord invalidates tokens that appear in public repositories.
• Privileged intents are minimal. Only requests the intents the bot actually uses. Requesting unnecessary privileged intents triggers extra review from Discord and delays bot verification for large bots.
• Rate limits are respected. All API calls use the framework's built-in rate limit handler. Manual API calls include X-RateLimit-* header parsing with exponential backoff. No retry loops without delay.
• Permissions are verified before action. Every moderation action checks that the bot's role hierarchy allows the operation before attempting it. Attempting to ban a user with a higher role throws an API error and confuses users.
• User input is sanitized. Embed fields, command responses, and logged content are stripped of @everyone, @here, and role mentions to prevent mention injection. User-supplied URLs are validated before embedding.
• Sensitive data is never logged. Bot tokens, webhook URLs, and user DM content are excluded from application logs. User IDs are logged for audit trails, but message content is only logged when explicitly required for moderation.

Support

Questions or issues with this skill? Contact brian@gorzelic.net Published by SpookyJuice — https://www.shopclawmart.com