Checks

Checks provide a way to define a reusable, generic set of predicates that may be applied to event handlers, commands, components, and other APIs.

In its simplest form, a check is an extension or receiver function against the CheckContext or CheckContextWithCache types, making use of the predefined check functions or APIs provided.

check { hasPermissions( // Same as the perms required to mass-ban members // using the "Members" management panel in the Discord // client. Permission.BanMembers + Permission.ManageGuild ) }

The default state for all checks is passed, with the passed property set to true. A check will not fail unless passed is set to false, but this property is automatically set for you when using the provided API functions.

Check Context API

When writing your own checks, the following APIs are available.

Functions

Name	Description
`fail`	Mark this check as having failed. This function optionally takes a message explaining the failure, which will be displayed to the user in most situations. Use the `translate` functions to provide a translated message.
`failIf`	Mark this check as having failed if the callable block returns `true`. This function optionally takes a message explaining the failure, which will be displayed to the user in most situations. Use the `translate` functions to provide a translated message.
`failIfNot`	Mark this check as having failed if the callable block returns `false`. This function optionally takes a message explaining the failure, which will be displayed to the user in most situations. Use the `translate` functions to provide a translated message.
`pass`	Mark this check as having passed.
`passIf`	Mark this check as having passed if the callable block returns `true`.
`passIfNot`	Mark this check as having passed if the callable block returns `false`.
`translate`	There are a number of overloads for this function, which allows you to translate a given string key based on the check's current 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.
`Boolean.whenFalse`	If the receiver is `false`, execute the provided callable block. Otherwise, do nothing.
`Boolean.whenTrue`	If the receiver is `true`, execute the provided callable block. Otherwise, do nothing.

Properties

	Name	Type	Description
	`cache`	`MutableStringKeyedMap<Any>`	For `CheckContextWithCache`, cache object shared with other checks that are part of the current invocation, and provided within any relevant contexts if all checks pass. You may store data in this cache to be shared between your checks or contexts as required. In some cases, this may help you to avoid making long-running calculations or API calls multiple times, which will speed up your bot.
🏷️	`defaultBundle`	`String?`	Bundle to be used by the `translate` functions by default.
🌐	`errorResponseKey`	`String`	Translation key to use when generating an error message for display on Discord, intended only for formatting. Defaults to `checks.responseTemplate`, and must contain a single indexed argument to be replaced with the error message provided by the various `fail` functions.
	`event`	`T: Event`	Event object that triggered this check.
	`locale`	`Locale`	Relevant locale object for this check. Provided by whatever system the check belongs to, and used by the `translate` functions.
	`message`	`String?`	Error message to return to the user, typically set by the `fail` functions. Will not be automatically translated, so use the `translate` functions if needed.
	`passed`	`Boolean`	Whether this check is currently passing. Set by the `fail` and `pass` functions. Defaults to `true`.

Bundled Checks

Kord Extensions provides a large number of predefined check functions. These checks are generic and work with all event types, with some caveats that are documented below.

Before writing your own checks, it's best to make sure that there are no existing checks that cover your use-case!

Channel Checks

All functions in this section take either a Snowflake argument representing a channel ID, or a suspending callable block that returns a ChannelBehavior.

Name	Description
`channelAbove`	Check whether the channel the event fired in is above the given channel in the channel list. This check attempts to calculate the channel positions in the same way Discord does: Compares channels within the same category by their relative positions. Compares channels within different categories by the categories' relative positions, where channels not in a category are always above channels that are within categories. Always fails when the event doesn't concern a channel, or concerns a DM channel.
`channelBelow`	Check whether the channel the event fired in is below the given channel in the channel list. This check attempts to calculate the channel positions in the same way Discord does: Compares channels within the same category by their relative positions. Compares channels within different categories by the categories' relative positions, where channels not in a category are always above channels that are within categories. Always fails when the event doesn't concern a channel, or concerns a DM channel.
`inCategory`	Check whether the event fired within the given category. Always fails when the event doesn't concern a channel, or concerns a DM channel.
`inChannel`	Check whether the event fired within the given channel. Always fails when the event doesn't concern a channel.
`notInCategory`	Check whether the event didn't fire within the given category. Always passes when the event doesn't concern a channel, or concerns a DM channel.
`notInChannel`	Check whether the event didn't fire within the given channel. Always passes when the event doesn't concern a channel.

Channel Type Checks

All functions in this section take a variadic argument, allowing you to specify more than one channel type.

Name	Description
`channelType`	Check whether the channel the event fired in is one of the given channel types. Always fails when the event doesn't concern a channel.
`notChannelType`	Check whether the channel the event fired in is not one of the given channel types. Always passes when the event doesn't concern a channel.

Name

Description

channelType

Check whether the channel the event fired in is one of the given channel types.

Always fails when the event doesn't concern a channel.

notChannelType

Check whether the channel the event fired in is not one of the given channel types.

Always passes when the event doesn't concern a channel.

Guild Checks

All functions that take arguments in this section take either a Snowflake argument representing a guild ID, or a suspending callable block that returns a GuildBehavior.

Name	Description
`inGuild`	Check whether the event fired within the given guild. Always fails when the event doesn't concern a guild.
`notInGuild`	Check whether the event didn't fire within the given guild. Always passes when the event doesn't concern a guild.
`anyGuild`	Check whether the event fired within a guild. Always fails when the event doesn't concern a guild, or when the corresponding `GuildBehavior` can't be retrieved. If you're not seeing the results you expected, please double-check your cache configuration.
`noGuild`	Check whether the event didn't fire within a guild. Always passes when the event doesn't concern a guild, or when the corresponding `GuildBehavior` can't be retrieved. If you're not seeing the results you expected, please double-check your cache configuration.

Member Checks

Name	Description
`hasPermission`	Check whether the guild member an event fired for has the given permission, or the Administrator permission. Always fails when the event doesn't concern a guild member, or when the corresponding `MemberBehavior` can't be retrieved. If you're not seeing the results you expected, please double-check your cache configuration and intents configuration.
`hasPermissions`	Check whether the guild member an event fired for has the given permissions set, or the Administrator permission. Always fails when the event doesn't concern a guild member, or when the corresponding `MemberBehavior` can't be retrieved. If you're not seeing the results you expected, please double-check your cache configuration and intents configuration.
`notHasPermission`	Check whether the guild member an event fired for doesn't have the given permission, and doesn't have the Administrator permission. Always passes when the event doesn't concern a guild member, or when the corresponding `MemberBehavior` can't be retrieved. If you're not seeing the results you expected, please double-check your cache configuration and intents configuration.
`notHasPermissions`	Check whether the guild member an event fired for doesn't have the given permissions set, and doesn't have the Administrator permission. Always passes when the event doesn't concern a guild member, or when the corresponding `MemberBehavior` can't be retrieved. If you're not seeing the results you expected, please double-check your cache configuration and intents configuration.

Miscellaneous Checks

Name	Description
`isBot`	Check whether the user an event fired for is a bot. Always fails when the event doesn't concern a user.
`isBotAdmin`	Check whether the user an event fired for is one of the current bot's application admins. The team the application belongs to on the Discord developer dashboard defines the application's admins. Always fails when the event doesn't concern a user, or the bot's application doesn't belong to a team.
`isBotOwner`	Check whether the user an event fired for is the current bot's application owner. For applications that don't belong to a team, this is the person that owns the bot's application on the Discord developer dashboard. Always fails when the event doesn't concern a user, or the bot's application belongs to a team.
`isInThread`	Check whether the event fired within a thread. Always fails when the event doesn't concern a channel.
`isNotBot`	Check whether the user an event fired for is not a bot. Always passes when the event doesn't concern a user.
`isNotBotAdmin`	Check whether the user an event fired for is not one of the current bot's application admins. The team the application belongs to on the Discord developer dashboard defines the application's admins. Always passes when the event doesn't concern a user, or the bot's application doesn't belong to a team.
`isNotBotOwner`	Check whether the user an event fired for is not the current bot's application owner. For applications that don't belong to a team, this is the person that owns the bot's application on the Discord developer dashboard. Always passes when the event doesn't concern a user, or the bot's application belongs to a team.
`isNotInThread`	Check whether the event didn't fire within a thread. Always passes when the event doesn't concern a channel.

NSFW Checks

Name	Description
`channelIsNsfw`	Check whether the event fired in an age-restricted channel. Always fails when the event doesn't concern a channel.
`channelOrGuildIsNsfw`	Check whether the event fired in an age-restricted channel, or an NSFW-marked guild. Always fails when the event doesn't concern a channel or guild. This check combines the `channelIsNsfw` and `guildNsfwLevelHigherOrEqual` checks, with the latter function being called with `NsfwLevel.AgeRestricted` as the first argument.
`guildNsfwLevelHigher`	Check whether the event fired in a guild that has a more severe NSFW level than the given one. See the note at the top of this section for information on how Kord Extensions compares NSFW levels. Always fails when the event doesn't concern a guild.
`guildNsfwLevelHigherOrEqual`	Check whether the event fired in a guild that has an equal or more severe NSFW level than the given one. See the note at the top of this section for information on how Kord Extensions compares NSFW levels. Always fails when the event doesn't concern a guild.
`guildNsfwLevelLower`	Check whether the event fired in a guild that has a less severe NSFW level than the given one. See the note at the top of this section for information on how Kord Extensions compares NSFW levels. Always fails when the event doesn't concern a guild.
`guildNsfwLevelLowerOrEqual`	Check whether the event fired in a guild that has an equal or less severe NSFW level than the given one. See the note at the top of this section for information on how Kord Extensions compares NSFW levels. Always fails when the event doesn't concern a guild.
`hasGuildNsfwLevel`	Check whether the event fired in a guild with the given NSFW level. Always fails when the event doesn't concern a guild.
`notChannelIsNsfw`	Check whether the event didn't fire in an age-restricted channel. Always passes when the event doesn't concern a channel.
`notChannelOrGuildIsNsfw`	Check whether the event didn't fire in an age-restricted channel or an NSFW-marked guild. This check combines the `notChannelIsNsfw` and `guildNsfwLevelLower` checks, with the latter function being called with `NsfwLevel.AgeRestricted` as the first argument.
`notHasGuildNsfwLevel`	Check whether the event didn't fire in a guild with the given NSFW level. Always passes when the event doesn't concern a guild.

Role Checks

All functions in this section take either a Snowflake argument representing a role ID, or a suspending callable block that returns a RoleBehavior.

Name	Description
`hasRole`	Check whether the guild member an event fired for has the given role. Always fails when the event doesn't concern a guild member, when the corresponding `MemberBehavior` can't be retrieved, or when the given role doesn't exist or can't be retrieved. If you're not seeing the results you expected, please double-check your cache configuration.
`notHasRole`	Check whether the guild member an event fired for doesn't have the given role. Always passes when the event doesn't concern a guild member, when the corresponding `MemberBehavior` can't be retrieved, or when the given role doesn't exist or can't be retrieved. If you're not seeing the results you expected, please double-check your cache configuration.
`topRoleEqual`	Check whether the guild member an event fired for has the given role as their top role. Always fails when the event doesn't concern a guild member, when the guild member doesn't have any roles, when the corresponding `MemberBehavior` can't be retrieved, or when the given role doesn't exist or can't be retrieved.
`topRoleHigher`	Check whether the guild member an event fired for has a top role listed above the given role. Always fails when the event doesn't concern a guild member, when the guild member doesn't have any roles, when the corresponding `MemberBehavior` can't be retrieved, or when the given role doesn't exist or can't be retrieved.
`topRoleHigherOrEqual`	Check whether the guild member an event fired for has a top role equal to or listed above the given role. Always fails when the event doesn't concern a guild member, when the guild member doesn't have any roles, when the corresponding `MemberBehavior` can't be retrieved, or when the given role doesn't exist or can't be retrieved.
`topRoleLower`	Check whether the guild member an event fired for has a top role listed below the given role. Always fails when the event doesn't concern a guild member, when the guild member doesn't have any roles, when the corresponding `MemberBehavior` can't be retrieved, or when the given role doesn't exist or can't be retrieved.
`topRoleLowerOrEqual`	Check whether the guild member an event fired for has a top role equal to or listed below the given role. Always fails when the event doesn't concern a guild member, when the guild member doesn't have any roles, when the corresponding `MemberBehavior` can't be retrieved, or when the given role doesn't exist or can't be retrieved.
`topRoleNotEqual`	Check whether the guild member an event fired for doesn't have the given role as their top role. Always passes when the event doesn't concern a guild member, when the guild member doesn't have any roles, when the corresponding `MemberBehavior` can't be retrieved, or when the given role doesn't exist or can't be retrieved.

Top Channel Checks

All functions in this section take either a Snowflake argument representing a role ID, or a suspending callable block that returns a ChannelBehavior.

Name	Description
`inTopChannel`	Check whether the event fired within the given top channel. Resolves the parent channel when the event fired within a thread, and uses that for the comparison. Always fails when the event doesn't concern a channel.
`notInTopChannel`	Check whether the event didn't fire within the given top channel. Resolves the parent channel when the event fired within a thread, and uses that for the comparison. Always passes when the event doesn't concern a channel.

Name

Description

inTopChannel

Check whether the event fired within the given top channel. Resolves the parent channel when the event fired within a thread, and uses that for the comparison.

Always fails when the event doesn't concern a channel.

notInTopChannel

Check whether the event didn't fire within the given top channel. Resolves the parent channel when the event fired within a thread, and uses that for the comparison.

Always passes when the event doesn't concern a channel.

Utilities

Kord Extensions provides several utilities to help you when working with checks.

General Functions

These functions are extension functions against the CheckContext type.

Name	Description
`or`	Convenience function intended for combining checks. This allows you to supply multiple checks, where only one of them needs to pass. public suspend fun CheckContext<*>.channelOrGuildIsNsfw() { channelIsNsfw() or { guildNsfwLevelHigherOrEqual(NsfwLevel.AgeRestricted) } } Combines failure messages when there's already a check failure message and the check within the `or` block sets a failure message. If any previous checks have passed, doesn't run the code within the `or` block.
`silence`	If a check has set a failure message, this function will clear it. This prevents an error message from being sent if the check fails.

Name

Description

or

Convenience function intended for combining checks. This allows you to supply multiple checks, where only one of them needs to pass.

public suspend fun CheckContext<*>.channelOrGuildIsNsfw() { channelIsNsfw() or { guildNsfwLevelHigherOrEqual(NsfwLevel.AgeRestricted) } }

Combines failure messages when there's already a check failure message and the check within the or block sets a failure message.

If any previous checks have passed, doesn't run the code within the or block.

silence

If a check has set a failure message, this function will clear it. This prevents an error message from being sent if the check fails.

Entity Extraction Functions

These functions exist to provide easy ways to extract entities from generic events. While these functions are particularly useful for implementing checks, they may also be useful in other scenarios.

Name	Description
`channelFor`	Retrieve the corresponding `ChannelBehavior` for the given event, or `null` when the event doesn't concern a channel or the `ChannelBehavior` can't be retrieved.
`guildFor`	Retrieve the corresponding `GuildBehavior` for the given event, or `null` when the event doesn't concern a guild or the `GuildBehavior` can't be retrieved.
`interactionFor`	Retrieve the corresponding `Interaction` for the given event, or `null` when the event doesn't concern an interaction.
`memberFor`	Retrieve the corresponding `MemberBehavior` for the given event, or `null` when the event doesn't concern a guild member or the `MemberBehavior` can't be retrieved.
`messageFor`	Retrieve the corresponding `MessageBehavior` for the given event, or `null` when the event doesn't concern a message or the `MessageBehavior` can't be retrieved.
`roleFor`	Retrieve the corresponding `RoleBehavior` for the given event, or `null` when the event doesn't concern a role or the `RoleBehavior` can't be retrieved.
`threadFor`	Retrieve the corresponding `ThreadChannelBehavior` for the given event, or `null` when the event doesn't concern a role or the `ThreadChannelBehavior` can't be retrieved.
`topChannelFor`	Retrieve the corresponding `ChannelBehavior` for the given event, or `null` when the event doesn't concern a channel or the `ChannelBehavior` can't be retrieved. Retrieves the parent channel when the event concerns a thread.
`userFor`	Retrieve the corresponding `UserBehavior` for the given event, or `null` when the event doesn't concern a user or the`UserBehavior` can't be retrieved.

Logging Functions

These functions are extension functions against the KLogger type, part of the Kotlin Logging library. Designed for specific situations, these functions log predefined messages for you.

Name	Description
`failed`	Log a failing check, along with a message that explains why.
`noCategoryId`	Log that this check failed because the given ID doesn't correspond with a known category.
`noChannelId`	Log that this check failed because the given ID doesn't correspond with a known channel.
`noGuildId`	Log that this check failed because the given ID doesn't correspond with a known guild.
`noRoleId`	Log that this check failed because the given ID doesn't correspond with a known role.
`nullChannel`	Log that the event's channel is null, and that this check may not support the event.
`nullGuild`	Log that the event's guild is null, and that this check may not support the event.
`nullMember`	Log that the event's member is null, and that this check may not support the event.
`nullMessage`	Log that the event's message is null, and that this check may not support the event.
`passed`	Log a passing check, optionally along with a message.

Custom Check Functions

Sometimes, it can be useful to define your own check functions. This allows you to create custom, reusable checks for your own use-cases.

All check functions are extension functions against the CheckContext type, and they may or may not take arguments as required. There's no mandated structure for these functions, but you may wish to use a similar structure to the bundled checks:

public suspend fun <T: Event> CheckContext<T>.myCheck() { if (!passed) { // This check context has already failed, so bail early. return } // Create a logger that's exclusive to this check. val logger = KotlinLogging.logger("package.and.function.myCheck") // Extract the relevant entities from the event. val eventChannel = channelFor(event) // Do a null check, if necessary. if (eventChannel == null) { logger.nullChannel(event) fail() } else { // Do your check logic here. if (eventChannel.id.toString().startsWith("1")) { // When the check passes, remember to log it. logger.passed() pass() } else { // When the check faiils, remember to log exactly why it failed. logger.failed("Channel ID did not start with 1") fail("Channel ID did not start with 1") } } }

If you need more examples, feel free to take a look at the bundled checks.

Last modified: 03 September 2024