API overview

This page maps the package’s main APIs. Use the focused guides for routing, interactions, and installation.

Commands

Build Discord application commands with Command, UserCommand, and MessageCommand. Chat commands accept typed option builders such as StringOption, IntegerOption, BooleanOption, UserOption, and ChannelOption; subcommands and groups use SubCommand and SubCommandGroup.

Call Build to receive a *discordgo.ApplicationCommand and an error, or MustBuild for static declarations where invalid definitions should panic. BuildCommands builds several declarations and returns the first error. Builders validate Discord’s name, description, option count, unique sibling names, nesting, and required-before-optional rules. You still choose when and where to register the resulting commands.

ping, err := discordkit.Command("ping", "Check whether the bot is responding").Build()
if err != nil {
    return err
}

Routing and middleware

A Router dispatches slash commands, component interactions, modal submissions, and autocomplete. Register handlers with Command, Component, Modal, and Autocomplete, then attach router.Handle to discordgo’s session using Session.AddHandler. A handler has the form func(*discordkit.Context) error.

Routes can include named segments in command names or custom IDs; see the router guide. Group adds a shared prefix and middleware. Middleware wraps handlers in registration order; Use adds router-wide middleware and route registrations can add route-specific middleware. The built-in Recovery middleware recovers panics and converts them to errors. Configure OnError to observe dispatch errors; without a hook the router logs them.

Context and responses

A handler’s Context exposes the discordgo session and interaction, typed option accessors, route parameters, and response helpers. Use ReplyText or Reply for a first response. Use Defer when work may exceed Discord’s initial response window, then complete it with EditReply or Followup. Component handlers can acknowledge with Update or DeferUpdate. Ephemeral controls visibility where supported.

The context tracks acknowledgement state and returns an error when an operation is invalid for the current interaction lifecycle. A defer acknowledges the interaction; it does not make the handler run asynchronously. Your application remains responsible for timeouts, external work, and error policy. See the interaction model.

Messages and Components V2

Use MessageSpec to describe response content, embeds, flags, files, and components, then pass it to the context response methods. The Components DSL includes Row, Button, link and premium buttons, string/entity/channel selects, sections, containers, text displays, galleries, separators, thumbnails, and file displays. Raw wraps a discordgo component when you need a type not covered by a builder.

DiscordKit validates component placement, action-row composition, custom IDs, gallery sizes, and the recursive component budget before sending. Components V2 messages set the required V2 flag automatically when their component tree uses V2 components. Discord’s V2 message restrictions still apply; don’t mix legacy message content or embeds with a V2 layout. Component interactions are routed by custom ID.

Modals and form values

Build modal components with labels and supported inputs, then create and send a modal through the context. The package supports text inputs, string selects, and file uploads where allowed by the modal API and the pinned discordgo version. Read submitted values through the context’s modal value helpers. Validate the modal tree before sending: each label must contain one supported input and the modal must have at least one component. File upload values refer to attachments supplied by Discord; your app decides how to store or process them.

Custom IDs

DiscordKit’s CustomID helper builds and parses slash-delimited IDs with named parameters. Use it to keep component and modal IDs structured, then register the matching route with Router.Component or Router.Modal. IDs must satisfy Discord’s length limit; avoid placing secrets or sensitive user data in them because clients can see them.

Command synchronization

DiffCommands compares desired declarations with commands already fetched from Discord and returns a SyncPlan without network I/O. SyncCommands fetches the remote set and applies creates and updates; obsolete commands are only deleted when SyncOptions.Delete is true. Set GuildID for guild-scoped commands; an empty value means global commands. Review deletion behavior carefully before enabling it in production.

Errors and escape hatches

Builders and validators return errors that can be inspected with errors.Is against package sentinel errors such as ErrInvalidCommand, ErrInvalidComponent, ErrInvalidModal, ErrAlreadyAcknowledged, and ErrRouteNotFound. DiscordKit deliberately exposes discordgo types and the underlying session: use the raw APIs when Discord adds a feature before the DSL supports it.