Extra Events

Kord Extensions provides a number of extra event types. You can make use of these in your extensions in the usual way.

Command Events

Command events relate to various stages in a command's execution.

Generic Types

The generic command event types represent the different actions command events may be fired for. These base types include the properties you'll need to work with the relevant commands and events, along with other shared properties.

All generic command events take two generic types, which will be used later:

C, the Command type.
E, the Event type.

The above types are used to define two properties that are common to all command events:

Name	Type	Description
`command`	`C`	The relevant command object.
`event`	`E`	The relevant event object.

Command Invocation

The type for this event is CommandInvocationEvent.

This event is fired when a command is invoked, before any processing happens. As this event is fired as soon as the command is invoked, you'll receive it regardless of whether the invocation succeeds or fails.

This event does not support any extra properties.

Command Invocation Success

The type for this event is CommandSucceededEvent.

This event is fired after a successful command invocation.

This event does not support any extra properties.

Command Invocation Failure

The type for this event is CommandFailedEvent.

This event is fired after a failed command invocation. As command invocations may fail for a number of reasons, this is a base type that's extended by more specific event types.

This event does not support any extra properties.

Command Invocation Failure: Check

The type for this event is CommandFailedChecksEvent.

This event is fired after a failed command invocation, where the invocation failed because a required check didn't pass.

This event supports the following extra properties:

Name	Type	Description
`reason`	`Key`	Key object representing a human-readable string, which is the error string returned by the failing check.

Command Invocation Failure: Exception

The type for this event is CommandFailedWithExceptionEvent.

This event is fired after a failed command invocation, where the invocation failed because an unexpected exception was thrown

This event supports the following extra properties:

Name	Type	Description
`throwable`	`Throwable`	The unexpected `Throwable` that was thrown. This will usually be an `Exception`, but an extension can realistically throw anything that extends `Throwable`, so this isn't guaranteed.

Command Invocation Failure: Parsing

The type for this event is CommandFailedParsingEvent.

This event is fired after a failed command invocation, where the invocation failed because of a command argument processing failure. This event type will only be fired by slash and chat commands, as other command types do not support argument parsing.

This event supports the following extra properties:

Name	Type	Description
`exception`	`ArgumentParsingException`	An exception object representing the argument parsing failure. Contains the reason for the failure.

Chat Commands

Chat command events extend the generic command events, with the following generic types supplied:

C: ChatCommand<*>
E: MessageCreateEvent

The following subtypes are supported for chat commands:

ChatCommandInvocationEvent
ChatCommandSucceededEvent
ChatCommandFailedChecksEvent
ChatCommandFailedParsingEvent
ChatCommandFailedWithExceptionEvent

Message Commands

Message command events extend the generic command events, with the following generic types supplied:

C: MessageCommand<*, *>
E: MessageCommandInteractionCreateEvent

The following generic base types are supported for message commands:

MessageCommandInvocationEvent
MessageCommandSucceededEvent
MessageCommandFailedEvent
MessageCommandFailedChecksEvent
MessageCommandFailedWithExceptionEvent

The above generic base types exist because message commands are a form of application command. Concrete types exist, with the following prefixes based on the current interaction type:

Ephemeral for the ephemeral interaction type.
Public for the public interaction type.

Slash Commands

Slash command events extend the generic command events, with the following generic types supplied:

C: SlashCommand<*, *, *>
E: ChatInputCommandInteractionCreateEvent (Discord calls these interactions "chat input command interactions", so Kord mirrors that naming scheme).

The following generic base types are supported for slash commands:

SlashCommandInvocationEvent
SlashCommandSucceededEvent
SlashCommandFailedEvent
SlashCommandFailedChecksEvent
SlashCommandFailedParsingEvent
SlashCommandFailedWithExceptionEvent

The above generic base types exist because slash commands are a form of application command. Concrete types exist, with the following prefixes based on the current interaction type:

Ephemeral for the ephemeral interaction type.
Public for the public interaction type.

User Commands

User command events extend the generic command events, with the following generic types supplied:

C: UserCommand<*, *>
E: UserCommandInteractionCreateEvent

The following generic base types are supported for user commands:

UserCommandInvocationEvent
UserCommandSucceededEvent
UserCommandFailedEvent
UserCommandFailedChecksEvent
UserCommandFailedWithExceptionEvent

The above generic base types exist because user commands are a form of application command. Concrete types exist, with the following prefixes based on the current interaction type:

Ephemeral for the ephemeral interaction type.
Public for the public interaction type.

Extension Events

Extension events directly relate to extensions, rather than the components that belong to them.

Extension State Change

The type for this event is ExtensionStateEvent.

This event is fired when an extension's loading state changes. This may happen during any point in the bot's lifecycle, as extensions are loaded and unloaded.

This event supports the following extra properties:

Name	Type	Description
`extension`	`Extension`	The extension which has had its state changed.
`state`	`ExtensionState`	The extension's new state, one of: `FAILED_LOADING`, `FAILED_UNLOADING`, `LOADED`, `LOADING`, `UNLOADED` or `UNLOADING`.

Modal events relate to the Modals framework, and its various states of execution.

The type for this event is ModalInteractionCompleteEvent.

This event is fired when a modal interaction has completed. Generally, this is used by the commands framework to figure out when a modal action should be run. You can use this to respond to modals yourself as well. For more information on modals, see the dedicated documentation.

This event supports the following extra properties:

Name	Type	Description
`id`	`String`	The modal form's ID.
`interaction`	`ModalSubmitInteraction`	The interaction object provided by the corresponding Kord event.

Supplementary Events

Supplementary events fill in the gaps, providing extra events for situations Kord doesn't provide a useful event for. This may include experimental Discord features, or Discord features that aren't widely supported.

If Kord doesn't support a Discord event, it will fire an UnknownEvent. If you're listening for this event, make sure you avoid processing it when you're listening for the corresponding supplementary event.

Guild Join Requests

Guild join request events are fired during the various stages of onboarding a user must pass through before being granted access to a guilds.

These events also include the data for an old, experimental Discord feature, which allowed servers to create a set of questions users must answer when joining a guilds, preventing them from interacting until the guilds's staff team reviewed them.

Discord ultimately decided against going through with this feature, as it negatively impacted user retention (and thus made the guilds using it less profitable for the platform). However, the guilds that took part in the experiment no longer have a way to configure or disable it, necessitating access to this event data.

For guilds not taking part in the above experiment, these events may still be fired as part of the normal onboarding process.

Delete Event

The type for this event is GuildJoinRequestDeleteEvent. It extends the following types:

This event is fired when a user's guild join request is deleted, which happens when they leave the server before submitting or finishing their application. No delta information is provided by Discord, so you may need to keep track of your own state along with the relevant member's pending property.

This event supports the following extra properties:

Name	Type	Description
`data`	`GuildJoinRequestDelete`	Container class representing the data from Discord.
`guildId`	`Snowflake`	The relevant guild ID.
`requestId`	`Snowflake`	The relevant guild request ID.
`userId`	`Snowflake`	The relevant user ID.

Update Event

The type for this event is GuildJoinRequestUpdateEvent. It extends the following types:

This event is fired when a user's guild join request is created or updated. No delta information is provided by Discord, so you may need to keep track of your own state along with the relevant member's pending property.

This event supports the following extra properties:

Name	Type	Description
`data`	`GuildJoinRequestUpdate`	Container class representing the data from Discord.
`guildId`	`Snowflake`	The relevant guild ID.
`request`	`GuildJoinRequest`	Guild join request data class, mostly containing data relating to guild access application questions.
`requestId`	`Snowflake`	The relevant guild request ID.
`status`	`ApplicationStatus`	Enum representing the status of the current guild join request.
`userId`	`Snowflake`	The relevant user ID.

Last modified: 20 November 2024

Extra Events

Command Events

Generic Types

Command Invocation

Command Invocation Success

Command Invocation Failure

Command Invocation Failure: Check

Command Invocation Failure: Exception

Command Invocation Failure: Parsing

Chat Commands

Message Commands

Slash Commands

User Commands

Extension Events

Extension State Change

Modal Events

Modal Interaction complete

Supplementary Events

Guild Join Requests

Delete Event

Update Event