Events

To react to things happening on Discord (and within your bot), you can register event handlers in your extensions. This is done simply:

override suspend fun setup() { event<MessageCreateEvent> { action { if (event.message.content == "hello") { event.message.respond("Hello!") } } } }

The event function takes several parameters:

T: Event - the type of event to listen for.
constructor - allows you to provide a callable object (usually a constructor) that returns an alternative implementation of EventHandler.
body - the function receiver which binds this tho EventHandler <T>.

Event Handler API

The EventHandler type provides several APIs that aid in working with events.

Builders

Builder	Receiver	Description
`action`	`EventContext <T>`	Provide the code that should be run when the event defined by `T` is fired. Note: All event handlers must have an `action`.
`check`	`CheckContext <T>`	Register a check that must pass for the event's `action` to be run.

Functions

The following functions are extension functions on the Event type, and must be called against an Event object. For brevity, this object will be represented by E below.

Function	Description
`E.getLocale`	Resolve the contextual locale for the given event, using the resolvers defined in the bot's configuration. Will default to the configured default bot locale if one can't be resolved. This may be useful for work related to Internationalization (i18n).
`E.translate`	There are a number of overloads for this function. It allows you to translate a given string key based on the event's locale, or another given locale. For more information on translations, see the dedicated documentation, and examine the functions in your IDE for more information on their parameters.

Properties

Name	Type	Description
`extension`	`Extension`	The extension this event handler belongs to.
`kord`	`Kord`	Quick access to the bot's current Kord object.
`sentry`	`SentryAdapter`	Quick access to the bot's Sentry adapter.
`translationsProvider`	`TranslationsProvider`	Quick access to the bot's translations provider.

Event Context API

The API above provides an action builder, which is a receiver on the EventContext type. This type provides some APIs for you to use when handling an event.

Functions

Function	Description
`getLocale`	Resolve the contextual locale for the current event, using the resolvers defined in the bot's configuration. Will default to the configured default bot locale if one can't be resolved. This may be useful for work related to Internationalization (i18n).

Properties

Name	Type	Description
`cache`	`MutableStringKeyedMap <Any>`	Data cache shared with the checks defined for the current event handler. For more information, see the dedicated documentation.
`eventHandler`	`EventHandler <T>`	The current event handler object.
`event`	`T: Event`	The event currently being handled.
`sentry`	`SentryContext`	Sentry context object, allowing you to provide extra context (such as breadcrumbs) to your `action`. For more information, see the dedicated documentation.
`translationsProvider`	`TranslationsProvider`	Quick access to the bot's translations provider.

Custom Context

Kord Extensions sets the customContext property for all events (Kord or otherwise) to an empty MutableStringKeyedMap <Any>. This allows you to store extra data on your events as part of processing.

Kord Extensions provides extension APIs to make this easier and more convenient.

Properties

The following properties are extensions on the Event type. The current event object will be represented using E below.

Name	Type	Description
`E.extraData`	`MutableStingKeyedMap <Any>`	Quick access to the properly-cast `customContext` property. Prefer this instead of direct access, to avoid casting it yourself.

Functions

The following functions are extensions on the StringKeyedMap <*> type. This will be represented using S below. Additionally, MutableStringKeyedMap <*> will be represented using M below.

Name	Parameters	Description
`S.getOf`	`T: Any`, `String`	Retrieve the value for the given key, casting it to `T` for you. Throws if the key is missing or the value cannot be cast.
`S.getOfOrDefault`	`T: Any`, `String`, `T`	Retrieve the value for the given key, casting it to `T` for you. Returns the provided default value if the key is missing or the value cannot be cast.
`M.getOfOrDefault`	`V: Any`, `T: V`, `String`, `T`, `Boolean`	Retrieve the value for the given key, casting it to `T` for you. Returns the provided default value if the key is missing or the value cannot be cast. Allows you to additionally store the default value in the map when it is returned.
`S.getOfOrNull`	`T: Any`, `String`	Retrieve the value for the given key, casting it to `T` for you. Returns `null` if the key is missing or the value cannot be cast.

Last modified: 20 November 2024