nextcord.ext.application_checks - checks and hooks for application commands

This extension aids in development of application commands by hooking and checking before, during, after invoke and handling errors. It has a similar interface to ext.commands checks

Checks

@nextcord.ext.application_checks.check(predicate)

A decorator that adds a check to the BaseApplicationCommand or its subclasses. These checks are accessible via BaseApplicationCommand.checks.

These checks should be predicates that take in a single parameter taking a Interaction. If the check returns a False-like value, an ApplicationCheckFailure is raised during invocation and sent to the on_application_command_error() event.

If an exception should be thrown in the predicate then it should be a subclass of ApplicationError. Any exception not subclassed from it will be propagated while those subclassed will be sent to on_application_command_error().

A special attribute named predicate is bound to the value returned by this decorator to retrieve the predicate passed to the decorator. This allows the following introspection and chaining to be done:

def owner_or_permissions(**perms):
    original = application_checks.has_permissions(**perms).predicate
    async def extended_check(interaction: Interaction):
        if interaction.guild is None:
            return False

        return (
            interaction.guild.owner_id == interaction.user.id
            or await original(interaction)
        )
    return application_checks.check(extended_check)

Note

The function returned by predicate is always a coroutine, even if the original function was not a coroutine.

Examples

Creating a basic check to see if the command invoker is you.

def check_if_it_is_me(interaction: Interaction):
    return interaction.message.author.id == 85309593344815104

@bot.slash_command()
@application_checks.check(check_if_it_is_me)
async def only_for_me(interaction: Interaction):
    await interaction.response.send_message('I know you!')

Transforming common checks into its own decorator:

def is_me():
    def predicate(interaction: Interaction):
        return interaction.user.id == 85309593344815104
    return application_checks.check(predicate)

@bot.slash_command()
@is_me()
async def only_me(interaction: Interaction):
    await interaction.response.send_message('Only you!')
Parameters:

predicate (Callable[[Interaction], bool]) – The predicate to check if the command should be invoked.

@nextcord.ext.application_checks.check_any(*checks)

A check() that will pass if any of the given checks pass, i.e. using logical OR.

If all checks fail then ApplicationCheckAnyFailure is raised to signal the failure. It inherits from ApplicationCheckFailure.

Note

The predicate attribute for this function is a coroutine.

Parameters:

*checks (Callable[[Interaction], bool]) – An argument list of checks that have been decorated with the check() decorator.

Raises:

TypeError – A check passed has not been decorated with the check() decorator.

Examples

Creating a basic check to see if it’s the bot owner or the server owner:

def is_guild_owner():
    def predicate(interaction: Interaction):
        return (
            interaction.guild is not None
            and interaction.guild.owner_id == interaction.user.id
        )
    return application_checks.check(predicate)

@bot.slash_command()
@application_checks.check_any(applications_checks.is_owner(), is_guild_owner())
async def only_for_owners(interaction: Interaction):
    await interaction.response.send_message('Hello mister owner!')

Included Checks

Role Checks

@nextcord.ext.application_checks.has_role(item)

A check() that is added that checks if the member invoking the command has the role specified via the name or ID specified.

If a string is specified, you must give the exact name of the role, including caps and spelling.

If an integer is specified, you must give the exact snowflake ID of the role.

If the message is invoked in a private message context then the check will return False.

This check raises one of two special exceptions, MissingRole if the user is missing a role, or NoPrivateMessage if it is used in a private message. Both inherit from ApplicationCheckFailure.

Parameters:

item (Union[int, str]) – The name or ID of the role to check.

Example

@bot.slash_command()
@application_checks.has_role('Cool Role')
async def cool(interaction: Interaction):
    await interaction.response.send_message('You are cool indeed')
@nextcord.ext.application_checks.has_any_role(*items)

A check() that is added that checks if the member invoking the command has any of the roles specified. This means that if they have one out of the three roles specified, then this check will return True.

Similar to has_role(), the names or IDs passed in must be exact.

This check raises one of two special exceptions, MissingAnyRole if the user is missing all roles, or NoPrivateMessage if it is used in a private message. Both inherit from ApplicationCheckFailure.

Parameters:

items (List[Union[str, int]]) – An argument list of names or IDs to check that the member has roles wise.

Example

@bot.slash_command()
@application_checks.has_any_role('Moderators', 492212595072434186)
async def cool(interaction: Interaction):
    await interaction.response.send_message('You are cool indeed')
@nextcord.ext.application_checks.bot_has_role(item)

Similar to has_role() except checks if the bot itself has the role.

This check raises one of two special exceptions, ApplicationBotMissingRole if the bot is missing the role, or ApplicationNoPrivateMessage if it is used in a private message. Both inherit from ApplicationCheckFailure.

Parameters:

item (Union[int, str]) – The name or ID of the role to check.

Example

@bot.slash_command()
@application_checks.bot_has_role(492212595072434186)
async def hasrole(interaction: Interaction):
    await interaction.response.send_message('I have the required role!')
@nextcord.ext.application_checks.bot_has_any_role(*items)

Similar to has_any_role() except checks if the bot itself has any of the roles listed.

This check raises one of two special exceptions, ApplicationBotMissingAnyRole if the bot is missing all roles, or ApplicationNoPrivateMessage if it is used in a private message. Both inherit from ApplicationCheckFailure.

Parameters:

*items (Union[str, int]) – An argument list of names or IDs to check that the bot has roles wise.

Example

@bot.slash_command()
@application_checks.bot_has_any_role('Moderators', 492212595072434186)
async def cool(interaction: Interaction):
    await interaction.response.send_message('I have a required role!')

Permission Checks

@nextcord.ext.application_checks.has_permissions(**perms)

A check() that is added that checks if the member has all of the permissions necessary.

Note that this check operates on the current channel permissions, not the guild wide permissions.

The permissions passed in must be exactly like the properties shown under nextcord.Permissions.

This check raises a special exception, ApplicationMissingPermissions that is inherited from ApplicationCheckFailure.

If this check is called in a DM context, it will raise an exception, ApplicationNoPrivateMessage.

Parameters:

perms (bool) – An argument list of permissions to check for.

Example

@bot.slash_command()
@application_checks.has_permissions(manage_messages=True)
async def testperms(interaction: Interaction):
    await interaction.response.send_message('You can manage messages.')
@nextcord.ext.application_checks.bot_has_permissions(**perms)

Similar to has_permissions() except checks if the bot itself has the permissions listed.

This check raises a special exception, ApplicationBotMissingPermissions that is inherited from ApplicationCheckFailure.

If this check is called in a DM context, it will raise an exception, ApplicationNoPrivateMessage.

@nextcord.ext.application_checks.has_guild_permissions(**perms)

Similar to has_permissions(), but operates on guild wide permissions instead of the current channel permissions.

If this check is called in a DM context, it will raise an exception, ApplicationNoPrivateMessage.

Parameters:

perms (bool) – An argument list of guild permissions to check for.

Example

@bot.slash_command()
@application_checks.has_guild_permissions(manage_messages=True)
async def permcmd(interaction: Interaction):
    await interaction.response.send_message('You can manage messages!')
@nextcord.ext.application_checks.bot_has_guild_permissions(**perms)

Similar to has_guild_permissions(), but checks the bot members guild permissions.

Scope Checks

@nextcord.ext.application_checks.dm_only

A check() that indicates this command must only be used in a DM context. Only private messages are allowed when using the command.

This check raises a special exception, ApplicationPrivateMessageOnly that is inherited from ApplicationCheckFailure.

Example

@bot.slash_command()
@application_checks.dm_only()
async def dmcmd(interaction: Interaction):
    await interaction.response.send_message('This is in DMS!')
@nextcord.ext.application_checks.guild_only

A check() that indicates this command must only be used in a guild context only. Basically, no private messages are allowed when using the command.

This check raises a special exception, ApplicationNoPrivateMessage that is inherited from ApplicationCheckFailure.

Example

@bot.slash_command()
@application_checks.guild_only()
async def dmcmd(interaction: Interaction):
    await interaction.response.send_message('This is in a GUILD!')

Other Checks

@nextcord.ext.application_checks.is_owner

A check() that checks if the person invoking this command is the owner of the bot.

This is powered by ext.commands.Bot.is_owner().

This check raises a special exception, ApplicationNotOwner that is derived from ApplicationCheckFailure.

This check may only be used with Bot. Otherwise, it will raise ApplicationCheckForBotOnly.

Example

bot = commands.Bot(owner_id=297045071457681409)

@bot.slash_command()
@application_checks.is_owner()
async def ownercmd(interaction: Interaction):
    await interaction.response.send_message('Only you!')
@nextcord.ext.application_checks.is_nsfw

A check() that checks if the channel is a NSFW channel.

This check raises a special exception, ApplicationNSFWChannelRequired that is derived from ApplicationCheckFailure.

Example

@bot.slash_command()
@application_checks.is_nsfw()
async def ownercmd(interaction: Interaction):
    await interaction.response.send_message('Only NSFW channels!')

Hooks

@nextcord.ext.application_checks.application_command_before_invoke(coro)

A decorator that registers a coroutine as a pre-invoke hook.

This allows you to refer to one before invoke hook for several commands that do not have to be within the same cog.

Example

async def record_usage(interaction: Interaction):
    print(
        interaction.user,
        "used",
        interaction.application_command,
        "at",
        interaction.message.created_at
    )

@bot.slash_command()
@application_checks.application_command_before_invoke(record_usage)
async def who(interaction: Interaction): # Output: <User> used who at <Time>
    await interaction.response.send_message("I am a bot")

class What(commands.Cog):
    @application_checks.application_command_before_invoke(record_usage)
    @nextcord.slash_command()
    async def when(self, interaction: Interaction):
        # Output: <User> used when at <Time>
        await interaction.response.send_message(
            f"and i have existed since {interaction.client.user.created_at}"
        )

    @nextcord.slash_command()
    async def where(self, interaction: Interaction): # Output: <Nothing>
        await interaction.response.send_message("on Discord")

    @nextcord.slash_command()
    async def why(self, interaction: Interaction): # Output: <Nothing>
        await interaction.response.send_message("because someone made me")

bot.add_cog(What())
@nextcord.ext.application_checks.application_command_after_invoke(coro)

A decorator that registers a coroutine as a post-invoke hook.

This allows you to refer to one after invoke hook for several commands that do not have to be within the same cog.

Events

nextcord.ext.application_checks.on_application_command_error(interaction, error)

The event that is fired when an error occurs during application command invocation.

Parameters:

  • interaction (Interaction) – The interaction that caused the error.

  • error (Exception) – The error that occurred.

nextcord.ext.application_checks.on_application_command_completion(interaction)

The event that is fired when the application command invoked completed successfully without any errors.

Parameters:

interaction (Interaction) – The interaction of the invoked application command.

Exceptions

exception nextcord.ext.application_checks.ApplicationCheckAnyFailure(checks, errors)

Exception raised when all predicates in check_any() fail.

This inherits from ApplicationCheckFailure.

errors

A list of errors that were caught during execution.

Type:

List[ApplicationCheckFailure]

checks

A list of check predicates that failed.

Type:

List[Callable[[Interaction], bool]]

exception nextcord.ext.application_checks.ApplicationNoPrivateMessage(message=None)

Exception raised when an operation does not work in private message contexts.

This inherits from ApplicationCheckFailure

exception nextcord.ext.application_checks.ApplicationMissingRole(missing_role)

Exception raised when the command invoker lacks a role to run a command.

This inherits from ApplicationCheckFailure

New in version 1.1.

missing_role

The required role that is missing. This is the parameter passed to has_role().

Type:

Union[str, int]

exception nextcord.ext.application_checks.ApplicationMissingAnyRole(missing_roles)

Exception raised when the command invoker lacks any of the roles specified to run a command.

This inherits from ApplicationCheckFailure

missing_roles

The roles that the invoker is missing. These are the parameters passed to has_any_role().

Type:

List[Union[str, int]]

exception nextcord.ext.application_checks.ApplicationBotMissingRole(missing_role)

Exception raised when the bot’s member lacks a role to run a command.

This inherits from ApplicationCheckFailure

New in version 1.1.

missing_role

The required role that is missing. This is the parameter passed to has_role().

Type:

Union[str, int]

exception nextcord.ext.application_checks.ApplicationBotMissingAnyRole(missing_roles)

Exception raised when the bot’s member lacks any of the roles specified to run a command.

This inherits from ApplicationCheckFailure

New in version 1.1.

missing_roles

The roles that the bot’s member is missing. These are the parameters passed to has_any_role().

Type:

List[Union[str, int]]

exception nextcord.ext.application_checks.ApplicationMissingPermissions(missing_permissions, *args)

Exception raised when the command invoker lacks permissions to run a command.

This inherits from ApplicationCheckFailure

missing_permissions

The required permissions that are missing.

Type:

List[str]

exception nextcord.ext.application_checks.ApplicationBotMissingPermissions(missing_permissions, *args)

Exception raised when the bot’s member lacks permissions to run a command.

This inherits from ApplicationCheckFailure

missing_permissions

The required permissions that are missing.

Type:

List[str]

exception nextcord.ext.application_checks.ApplicationPrivateMessageOnly(message=None)

Exception raised when an operation does not work outside of private message contexts.

This inherits from ApplicationCheckFailure

exception nextcord.ext.application_checks.ApplicationNotOwner(message=None, *args)

Exception raised when the message author is not the owner of the bot.

This inherits from ApplicationCheckFailure

exception nextcord.ext.application_checks.ApplicationNSFWChannelRequired(channel)

Exception raised when a channel does not have the required NSFW setting.

This inherits from ApplicationCheckFailure.

Parameters:

channel (Optional[Union[abc.GuildChannel, Thread, PartialMessageable]]) – The channel that does not have NSFW enabled.

exception nextcord.ext.application_checks.ApplicationCheckForBotOnly

Exception raised when the application check may only be used for Bot.

This inherits from ApplicationCheckFailure

Exception Hierarchy