# The interaction model Understand how Discord interactions travel through discordgo, the DiscordKit Router, middleware, Context, and application handlers. Most of DiscordKit is built around one idea: **Discord sends interactions, and your application routes them to handlers.** Commands are only one kind of interaction. DiscordKit uses the same application model for commands, components, modal submissions, and autocomplete. ## The complete flow At a high level: ```text Discord │ │ Interaction ▼ discordgo.Session │ ▼ Router.Handle │ ▼ Context │ ▼ Route resolution │ ▼ Global middleware │ ▼ Route middleware │ ▼ Handler │ ▼ Response │ ▼ Discord ``` Understanding each stage explains most of the framework. ## Discord sends an interaction Interactions are generated by actions such as: * executing a slash command; * using a user context command; * using a message context command; * clicking a button; * choosing an item from a select menu; * submitting a modal; * typing into an autocomplete-enabled command option. discordgo receives those interactions from Discord. DiscordKit does not replace that connection. ## `Router.Handle` is a discordgo handler A DiscordKit Router is connected to discordgo like this: ```go session.AddHandler(router.Handle) ``` `Router.Handle` is responsible for adapting the incoming discordgo interaction into the DiscordKit application model. It creates a `Context` and dispatches it through the Router. ## Context represents one interaction Every DiscordKit handler receives: ```go *discordkit.Context ``` A Context exists for exactly one interaction. It gives the handler access to: * the underlying `*discordgo.Session`; * the original interaction; * command options; * resolved users, roles, channels, members, and attachments; * route parameters; * form submissions; * response helpers; * a standard Go `context.Context`. For example: ```go func greet(c *discordkit.Context) error { user, err := c.RequireUserOption("user") if err != nil { return err } return c.ReplyText("Hello, " + user.Username) } ``` ## Route resolution depends on the interaction type DiscordKit supports four route categories. ### Commands ```go router.Command("ping", pingHandler) ``` A command with subcommands uses its full command path: ```go router.Command("admin ban", banHandler) ``` ### Components Components are routed through their `custom_id`: ```go router.Component( "/jobs/:jobID/save", saveJobHandler, ) ``` Named route parameters become available through Context: ```go jobID := c.MustParam("jobID") ``` ### Modal submissions Modal submissions use the same pattern-based routing model: ```go router.Modal( "/jobs/:jobID/edit", editJobHandler, ) ``` ### Autocomplete Autocomplete routes combine the command path with the focused option: ```go router.Autocomplete( "search", "query", searchAutocomplete, ) ``` ## Middleware wraps handlers Middleware can run behavior before or after application handlers. DiscordKit middleware follows the standard Go wrapping model: ```go type Middleware func(Handler) Handler ``` For example: ```go router := discordkit.NewRouter( discordkit.Logging(nil), discordkit.RequireGuild(), ) ``` Global middleware is applied to all matched routes. A route can also have additional middleware: ```go router.Command( "admin", adminHandler, discordkit.RequirePermissions( discordgo.PermissionAdministrator, ), ) ``` ## Recovery is always applied The Router automatically applies DiscordKit's recovery middleware around dispatch. If a handler panics, the panic becomes a `*discordkit.PanicError` instead of escaping through the interaction handler. Recovery does **not** automatically send an error message to the user. Applications remain responsible for deciding how user-facing errors should be presented. ## Handlers return errors A Handler is: ```go type Handler func(*Context) error ``` Returning errors instead of handling every failure locally allows errors to propagate through middleware and eventually reach the Router error hook. For example: ```go router.OnError(func(c *discordkit.Context, err error) { slog.Error("interaction failed", "error", err) }) ``` If no custom hook is installed, DiscordKit logs the error using `slog`. ## Responses acknowledge interactions Discord interactions must be acknowledged according to Discord's interaction rules. A handler may send an initial response: ```go return c.ReplyText("Done") ``` or defer work: ```go if err := c.Defer(false); err != nil { return err } // perform work... _, err := c.Edit( discordkit.MessageSpec{ Content: "Done", }, ) return err ``` DiscordKit tracks this lifecycle to prevent invalid sequences such as sending two initial responses. ## One Router, several interaction types A larger application can register different interaction types in the same Router: ```go router := discordkit.NewRouter( discordkit.Logging(nil), ) router.Command( "jobs search", searchJobs, ) router.Component( "/jobs/:jobID/save", saveJob, ) router.Modal( "/jobs/:jobID/edit", editJob, ) router.Autocomplete( "jobs search", "query", autocompleteJobs, ) ``` These routes use the same Context, Handler, middleware, error handling, and response model. That consistency is one of DiscordKit's central design goals. ## The mental model A useful way to think about DiscordKit is: ```text Discord interaction + routing information + application middleware = handler execution ``` The framework does not attempt to hide Discord. Instead, it provides a structured path from an incoming Discord interaction to application code. ## Next Continue with [Router](/concepts/router/) to learn how route registration, groups, parameters, conflicts, and middleware composition work.