Application Commands#

Command Permission Decorators#

@discord.commands.default_permissions(**perms)[source]#

A decorator that limits the usage of an application command to members with certain permissions.

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

Note

These permissions can be updated by server administrators per-guild. As such, these are only “defaults”, as the name suggests. If you want to make sure that a user always has the specified permissions regardless, you should use an internal check such as has_permissions().

Parameters:

**perms (Dict[str, bool]) – An argument list of permissions to check for.

Return type:

Callable

Example

from discord import default_permissions

@bot.slash_command()
@default_permissions(manage_messages=True)
async def test(ctx):
    await ctx.respond('You can manage messages.')
@discord.commands.guild_only[source]#

A decorator that limits the usage of an application command to guild contexts. The command won’t be able to be used in private message channels.

Return type:

Callable

Example

from discord import guild_only

@bot.slash_command()
@guild_only()
async def test(ctx):
    await ctx.respond("You're in a guild.")
@discord.commands.is_nsfw[source]#

A decorator that limits the usage of an application command to 18+ channels and users. In guilds, the command will only be able to be used in channels marked as NSFW. In DMs, users must have opted into age-restricted commands via privacy settings.

Note that apps intending to be listed in the App Directory cannot have NSFW commands.

Return type:

Callable

Example

from discord import is_nsfw

@bot.slash_command()
@is_nsfw()
async def test(ctx):
    await ctx.respond("This command is age restricted.")

Commands#

Shortcut Decorators#

@discord.commands.application_command(cls=<class 'discord.commands.core.SlashCommand'>, **attrs)[source]#

A decorator that transforms a function into an ApplicationCommand. More specifically, usually one of SlashCommand, UserCommand, or MessageCommand. The exact class depends on the cls parameter. By default, the description attribute is received automatically from the docstring of the function and is cleaned up with the use of inspect.cleandoc. If the docstring is bytes, then it is decoded into str using utf-8 encoding. The name attribute also defaults to the function name unchanged.

New in version 2.0.

Parameters:
  • cls (ApplicationCommand) – The class to construct with. By default, this is SlashCommand. You usually do not change this.

  • attrs – Keyword arguments to pass into the construction of the class denoted by cls.

Returns:

A decorator that converts the provided method into an ApplicationCommand, or subclass of it.

Return type:

Callable[…, ApplicationCommand]

Raises:

TypeError – If the function is not a coroutine or is already a command.

@discord.commands.command(**kwargs)[source]#

An alias for application_command().

Note

This decorator is overridden by ext.commands.command().

New in version 2.0.

Returns:

A decorator that converts the provided method into an ApplicationCommand.

Return type:

Callable[…, ApplicationCommand]

@discord.commands.slash_command(**kwargs)[source]#

Decorator for slash commands that invokes application_command().

New in version 2.0.

Returns:

A decorator that converts the provided method into a SlashCommand.

Return type:

Callable[…, SlashCommand]

@discord.commands.user_command(**kwargs)[source]#

Decorator for user commands that invokes application_command().

New in version 2.0.

Returns:

A decorator that converts the provided method into a UserCommand.

Return type:

Callable[…, UserCommand]

@discord.commands.message_command(**kwargs)[source]#

Decorator for message commands that invokes application_command().

New in version 2.0.

Returns:

A decorator that converts the provided method into a MessageCommand.

Return type:

Callable[…, MessageCommand]

Objects#

class discord.ApplicationCommand(func, **kwargs)[source]#
Parameters:

func (Callable) –

is_on_cooldown(ctx)[source]#

Checks whether the command is currently on cooldown.

Note

This uses the current time instead of the interaction time.

Parameters:

ctx (ApplicationContext) – The invocation context to use when checking the command’s cooldown status.

Returns:

A boolean indicating if the command is on cooldown.

Return type:

bool

reset_cooldown(ctx)[source]#

Resets the cooldown on this command.

Parameters:

ctx (ApplicationContext) – The invocation context to reset the cooldown under.

Return type:

None

get_cooldown_retry_after(ctx)[source]#

Retrieves the amount of seconds before this command can be tried again.

Note

This uses the current time instead of the interaction time.

Parameters:

ctx (ApplicationContext) – The invocation context to retrieve the cooldown from.

Returns:

The amount of time left on this command’s cooldown in seconds. If this is 0.0 then the command isn’t on cooldown.

Return type:

float

error(coro)[source]#

A decorator that registers a coroutine as a local error handler.

A local error handler is an on_command_error() event limited to a single command. However, the on_command_error() is still invoked afterwards as the catch-all.

Parameters:

coro (coroutine) – The coroutine to register as the local error handler.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

has_error_handler()[source]#

Checks whether the command has an error handler registered.

Return type:

bool

before_invoke(coro)[source]#

A decorator that registers a coroutine as a pre-invoke hook. A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required.

This pre-invoke hook takes a sole parameter, an ApplicationContext. See Bot.before_invoke() for more info.

Parameters:

coro (coroutine) – The coroutine to register as the pre-invoke hook.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

after_invoke(coro)[source]#

A decorator that registers a coroutine as a post-invoke hook. A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required.

This post-invoke hook takes a sole parameter, an ApplicationContext. See Bot.after_invoke() for more info.

Parameters:

coro (coroutine) – The coroutine to register as the post-invoke hook.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

property full_parent_name#

Retrieves the fully qualified parent command name.

This the base command name required to execute it. For example, in /one two three the parent name would be one two.

property qualified_name#

Retrieves the fully qualified command name.

This is the full parent name with the command name as well. For example, in /one two three the qualified name would be one two three.

property qualified_id#

Retrieves the fully qualified command ID.

This is the root parent ID. For example, in /one two three the qualified ID would return one.id.

class discord.SlashCommand(func, *args, **kwargs)[source]#

A class that implements the protocol for a slash command.

These are not created manually, instead they are created via the decorator or functional interface.

New in version 2.0.

name#

The name of the command.

Type:

str

callback#

The coroutine that is executed when the command is called.

Type:

coroutine

description#

The description for the command.

Type:

Optional[str]

guild_ids#

The ids of the guilds where this command will be registered.

Type:

Optional[List[int]]

options#

The parameters for this command.

Type:

List[Option]

parent#

The parent group that this command belongs to. None if there isn’t one.

Type:

Optional[SlashCommandGroup]

mention#

Returns a string that allows you to mention the slash command.

Type:

str

guild_only#

Whether the command should only be usable inside a guild.

Deprecated since version 2.6: Use the contexts parameter instead.

Type:

bool

nsfw#

Whether the command should be restricted to 18+ channels and users. Apps intending to be listed in the App Directory cannot have NSFW commands.

Type:

bool

default_member_permissions#

The default permissions a member needs to be able to run the command.

Type:

Permissions

cog#

The cog that this command belongs to. None if there isn’t one.

Type:

Optional[Cog]

checks#

A list of predicates that verifies if the command could be executed with the given ApplicationContext as the sole parameter. If an exception is necessary to be thrown to signal failure, then one inherited from ApplicationCommandError should be used. Note that if the checks fail then CheckFailure exception is raised to the on_application_command_error() event.

Type:

List[Callable[[ApplicationContext], bool]]

cooldown#

The cooldown applied when the command is invoked. None if the command doesn’t have a cooldown.

Type:

Optional[Cooldown]

name_localizations#

The name localizations for this command. The values of this should be "locale": "name". See here for a list of valid locales.

Type:

Dict[str, str]

description_localizations#

The description localizations for this command. The values of this should be "locale": "description". See here for a list of valid locales.

Type:

Dict[str, str]

integration_types#

The type of installation this command should be available to. For instance, if set to IntegrationType.user_install, the command will only be available to users with the application installed on their account. Unapplicable for guild commands.

Type:

Set[IntegrationType]

contexts#

The location where this command can be used. Cannot be set if this is a guild command.

Type:

Set[InteractionContextType]

Parameters:

func (Callable) –

copy()[source]#

Creates a copy of this command.

Returns:

A new instance of this command.

Return type:

SlashCommand

class discord.SlashCommandGroup(name, description=None, guild_ids=None, parent=None, cooldown=None, max_concurrency=None, **kwargs)[source]#

A class that implements the protocol for a slash command group.

These can be created manually, but they should be created via the decorator or functional interface.

name#

The name of the command.

Type:

str

description#

The description for the command.

Type:

Optional[str]

guild_ids#

The ids of the guilds where this command will be registered.

Type:

Optional[List[int]]

parent#

The parent group that this group belongs to. None if there isn’t one.

Type:

Optional[SlashCommandGroup]

guild_only#

Whether the command should only be usable inside a guild.

Deprecated since version 2.6: Use the contexts parameter instead.

Type:

bool

nsfw#

Whether the command should be restricted to 18+ channels and users. Apps intending to be listed in the App Directory cannot have NSFW commands.

Type:

bool

default_member_permissions#

The default permissions a member needs to be able to run the command.

Type:

Permissions

checks#

A list of predicates that verifies if the command could be executed with the given ApplicationContext as the sole parameter. If an exception is necessary to be thrown to signal failure, then one inherited from ApplicationCommandError should be used. Note that if the checks fail then CheckFailure exception is raised to the on_application_command_error() event.

Type:

List[Callable[[ApplicationContext], bool]]

name_localizations#

The name localizations for this command. The values of this should be "locale": "name". See here for a list of valid locales.

Type:

Dict[str, str]

description_localizations#

The description localizations for this command. The values of this should be "locale": "description". See here for a list of valid locales.

Type:

Dict[str, str]

integration_types#

The type of installation this command should be available to. For instance, if set to IntegrationType.user_install, the command will only be available to users with the application installed on their account. Unapplicable for guild commands.

Type:

Set[IntegrationType]

contexts#

The location where this command can be used. Unapplicable for guild commands.

Type:

Set[InteractionContextType]

Parameters:
  • name (str) –

  • description (str | None) –

  • guild_ids (list[int] | None) –

  • parent (SlashCommandGroup | None) –

  • cooldown (CooldownMapping | None) –

  • max_concurrency (MaxConcurrency | None) –

create_subgroup(name, description=None, guild_ids=None, **kwargs)[source]#

Creates a new subgroup for this SlashCommandGroup.

Parameters:
  • name (str) – The name of the group to create.

  • description (Optional[str]) – The description of the group to create.

  • guild_ids (Optional[List[int]]) – A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if None is passed.

  • guild_only (bool) – Whether the command should only be usable inside a guild.

  • nsfw (bool) – Whether the command should be restricted to 18+ channels and users. Apps intending to be listed in the App Directory cannot have NSFW commands.

  • default_member_permissions (Permissions) – The default permissions a member needs to be able to run the command.

  • checks (List[Callable[[ApplicationContext], bool]]) – A list of predicates that verifies if the command could be executed with the given ApplicationContext as the sole parameter. If an exception is necessary to be thrown to signal failure, then one inherited from ApplicationCommandError should be used. Note that if the checks fail then CheckFailure exception is raised to the on_application_command_error() event.

  • name_localizations (Dict[str, str]) –

    The name localizations for this command. The values of this should be "locale": "name". See here for a list of valid locales.

  • description_localizations (Dict[str, str]) –

    The description localizations for this command. The values of this should be "locale": "description". See here for a list of valid locales.

Returns:

The slash command group that was created.

Return type:

SlashCommandGroup

subgroup(name=None, description=None, guild_ids=None)[source]#

A shortcut decorator that initializes the provided subclass of SlashCommandGroup as a subgroup.

New in version 2.0.

Parameters:
  • name (Optional[str]) – The name of the group to create. This will resolve to the name of the decorated class if None is passed.

  • description (Optional[str]) – The description of the group to create.

  • guild_ids (Optional[List[int]]) – A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if None is passed.

Returns:

The slash command group that was created.

Return type:

Callable[[Type[SlashCommandGroup]], SlashCommandGroup]

for ... in walk_commands()[source]#

An iterator that recursively walks through all slash commands and groups in this group.

Yields:

SlashCommand | SlashCommandGroup – A nested slash command or slash command group from the group.

Return type:

Generator[SlashCommand | SlashCommandGroup, None, None]

copy()[source]#

Creates a copy of this command group.

Returns:

A new instance of this command group.

Return type:

SlashCommandGroup

class discord.UserCommand(func, *args, **kwargs)[source]#

A class that implements the protocol for user context menu commands.

These are not created manually, instead they are created via the decorator or functional interface.

name#

The name of the command.

Type:

str

callback#

The coroutine that is executed when the command is called.

Type:

coroutine

guild_ids#

The ids of the guilds where this command will be registered.

Type:

Optional[List[int]]

guild_only#

Whether the command should only be usable inside a guild.

Deprecated since version 2.6: Use the contexts parameter instead.

Type:

bool

nsfw#

Whether the command should be restricted to 18+ channels and users. Apps intending to be listed in the App Directory cannot have NSFW commands.

Type:

bool

default_member_permissions#

The default permissions a member needs to be able to run the command.

Type:

Permissions

cog#

The cog that this command belongs to. None if there isn’t one.

Type:

Optional[Cog]

checks#

A list of predicates that verifies if the command could be executed with the given ApplicationContext as the sole parameter. If an exception is necessary to be thrown to signal failure, then one inherited from ApplicationCommandError should be used. Note that if the checks fail then CheckFailure exception is raised to the on_application_command_error() event.

Type:

List[Callable[[ApplicationContext], bool]]

cooldown#

The cooldown applied when the command is invoked. None if the command doesn’t have a cooldown.

Type:

Optional[Cooldown]

name_localizations#

The name localizations for this command. The values of this should be "locale": "name". See here for a list of valid locales.

Type:

Dict[str, str]

integration_types#

The installation contexts where this command is available. Unapplicable for guild commands.

Type:

Set[IntegrationType]

contexts#

The interaction contexts where this command is available. Unapplicable for guild commands.

Type:

Set[InteractionContextType]

Parameters:

func (Callable) –

copy()[source]#

Creates a copy of this command.

Returns:

A new instance of this command.

Return type:

UserCommand

class discord.MessageCommand(func, *args, **kwargs)[source]#

A class that implements the protocol for message context menu commands.

These are not created manually, instead they are created via the decorator or functional interface.

name#

The name of the command.

Type:

str

callback#

The coroutine that is executed when the command is called.

Type:

coroutine

guild_ids#

The ids of the guilds where this command will be registered.

Type:

Optional[List[int]]

guild_only#

Whether the command should only be usable inside a guild.

Deprecated since version 2.6: Use the contexts parameter instead.

Type:

bool

nsfw#

Whether the command should be restricted to 18+ channels and users. Apps intending to be listed in the App Directory cannot have NSFW commands.

Type:

bool

default_member_permissions#

The default permissions a member needs to be able to run the command.

Type:

Permissions

cog#

The cog that this command belongs to. None if there isn’t one.

Type:

Optional[Cog]

checks#

A list of predicates that verifies if the command could be executed with the given ApplicationContext as the sole parameter. If an exception is necessary to be thrown to signal failure, then one inherited from ApplicationCommandError should be used. Note that if the checks fail then CheckFailure exception is raised to the on_application_command_error() event.

Type:

List[Callable[[ApplicationContext], bool]]

cooldown#

The cooldown applied when the command is invoked. None if the command doesn’t have a cooldown.

Type:

Optional[Cooldown]

name_localizations#

The name localizations for this command. The values of this should be "locale": "name". See here for a list of valid locales.

Type:

Dict[str, str]

integration_types#

The installation contexts where this command is available. Unapplicable for guild commands.

Type:

Set[IntegrationType]

contexts#

The interaction contexts where this command is available. Unapplicable for guild commands.

Type:

Set[InteractionContextType]

Parameters:

func (Callable) –

copy()[source]#

Creates a copy of this command.

Returns:

A new instance of this command.

Return type:

MessageCommand

Options#

Shortcut Decorators#

@discord.commands.option(name, input_type=None, **kwargs)[source]#

A decorator that can be used instead of typehinting Option.

New in version 2.0.

discord.commands.parameter_name#

The name of the target function parameter this option is mapped to. This allows you to have a separate UI name and parameter name.

Type:

str

Objects#

class discord.Option(input_type=<class 'str'>, /, description=None, **kwargs)[source]#

Represents a selectable option for a slash command.

input_type#

The type of input that is expected for this option. This can be a SlashCommandOptionType, an associated class, a channel type, a Converter, a converter class or an enum.Enum. If a enum.Enum is used and it has up to 25 values, choices will be automatically filled. If the enum.Enum has more than 25 values, autocomplete will be implemented with discord.utils.basic_autocomplete() instead.

Type:

Union[Type[str], Type[bool], Type[int], Type[float], Type[abc.GuildChannel], Type[Thread], Type[Member], Type[User], Type[Attachment], Type[Role], Type[abc.Mentionable], SlashCommandOptionType, Type[ext.commands.Converter], Type[enums.Enum], Type[Enum]]

name#

The name of this option visible in the UI. Inherits from the variable name if not provided as a parameter.

Type:

str

description#

The description of this option. Must be 100 characters or fewer. If input_type is a enum.Enum and description is not specified, input_type’s docstring will be used.

Type:

Optional[str]

choices#

The list of available choices for this option. Can be a list of values or OptionChoice objects (which represent a name:value pair). If provided, the input from the user must match one of the choices in the list.

Type:

Optional[List[Union[Any, OptionChoice]]]

required#

Whether this option is required.

Type:

Optional[bool]

default#

The default value for this option. If provided, required will be considered False.

Type:

Optional[Any]

min_value#

The minimum value that can be entered. Only applies to Options with an input_type of int or float.

Type:

Optional[int]

max_value#

The maximum value that can be entered. Only applies to Options with an input_type of int or float.

Type:

Optional[int]

min_length#

The minimum length of the string that can be entered. Must be between 0 and 6000 (inclusive). Only applies to Options with an input_type of str.

Type:

Optional[int]

max_length#

The maximum length of the string that can be entered. Must be between 1 and 6000 (inclusive). Only applies to Options with an input_type of str.

Type:

Optional[int]

autocomplete#

The autocomplete handler for the option. Accepts a callable (sync or async) that takes a single argument of AutocompleteContext. The callable must return an iterable of str or OptionChoice. Alternatively, discord.utils.basic_autocomplete() may be used in place of the callable.

Note

Does not validate the input value against the autocomplete results.

Type:

Optional[Callable[[AutocompleteContext], Awaitable[Union[Iterable[OptionChoice], Iterable[str], Iterable[int], Iterable[float]]]]]

channel_types#

A list of channel types that can be selected in this option. Only applies to Options with an input_type of discord.SlashCommandOptionType.channel. If this argument is used, input_type will be ignored.

Type:

list[discord.ChannelType] | None

name_localizations#

The name localizations for this option. The values of this should be "locale": "name". See here for a list of valid locales.

Type:

Dict[str, str]

description_localizations#

The description localizations for this option. The values of this should be "locale": "description". See here for a list of valid locales.

Type:

Dict[str, str]

Examples

Basic usage:

@bot.slash_command(guild_ids=[...])
async def hello(
    ctx: discord.ApplicationContext,
    name: Option(str, "Enter your name"),
    age: Option(int, "Enter your age", min_value=1, max_value=99, default=18)
    # passing the default value makes an argument optional
    # you also can create optional argument using:
    # age: Option(int, "Enter your age") = 18
):
    await ctx.respond(f"Hello! Your name is {name} and you are {age} years old.")

New in version 2.0.

Parameters:
  • input_type (InputType) –

  • description (str | None) –

class discord.ThreadOption(thread_type)[source]#

Represents a class that can be passed as the input_type for an Option class.

New in version 2.0.

Parameters:

thread_type (Literal["public", "private", "news"]) – The thread type to expect for this options input.

class discord.OptionChoice(name, value=None, name_localizations=...)[source]#

Represents a name:value pairing for a selected Option.

New in version 2.0.

name#

The name of the choice. Shown in the UI when selecting an option.

Type:

str

value#

The value of the choice. If not provided, will use the value of name.

Type:

Optional[Union[str, int, float]]

name_localizations#

The name localizations for this choice. The values of this should be "locale": "name". See here for a list of valid locales.

Type:

Dict[str, str]

Parameters:

Context Objects#

class discord.ApplicationContext(bot, interaction)[source]#

Represents a Discord application command interaction context.

This class is not created manually and is instead passed to application commands as the first parameter.

New in version 2.0.

bot#

The bot that the command belongs to.

Type:

Bot

interaction#

The interaction object that invoked the command.

Type:

Interaction

command#

The command that this context belongs to.

Type:

ApplicationCommand

Parameters:
await invoke(command, /, *args, **kwargs)[source]#

This function is a coroutine.

Calls a command with the arguments given. This is useful if you want to just call the callback that a ApplicationCommand holds internally.

Note

This does not handle converters, checks, cooldowns, pre-invoke, or after-invoke hooks in any matter. It calls the internal callback directly as-if it was a regular function. You must take care in passing the proper arguments when using this function.

Parameters:
  • command (ApplicationCommand) – The command that is going to be called.

  • *args – The arguments to use.

  • **kwargs – The keyword arguments to use.

Raises:

TypeError – The command argument to invoke is missing.

channel#

Union[abc.GuildChannel, PartialMessageable, Thread]: Returns the channel associated with this context’s command. Shorthand for Interaction.channel.

channel_id#

Returns the ID of the channel associated with this context’s command. Shorthand for Interaction.channel_id.

guild#

Returns the guild associated with this context’s command. Shorthand for Interaction.guild.

guild_id#

Returns the ID of the guild associated with this context’s command. Shorthand for Interaction.guild_id.

locale#

Returns the locale of the guild associated with this context’s command. Shorthand for Interaction.locale.

guild_locale#

Returns the locale of the guild associated with this context’s command. Shorthand for Interaction.guild_locale.

me#

Union[Member, ClientUser]: Similar to Guild.me except it may return the ClientUser in private message message contexts, or when Intents.guilds() is absent.

message#

Returns the message sent with this context’s command. Shorthand for Interaction.message, if applicable.

user#

Returns the user that sent this context’s command. Shorthand for Interaction.user.

author#

Returns the user that sent this context’s command. Shorthand for Interaction.user.

property voice_client#

Returns the voice client associated with this context’s command. Shorthand for Interaction.guild.voice_client, if applicable.

response#

Returns the response object associated with this context’s command. Shorthand for Interaction.response.

property selected_options#

The options and values that were selected by the user when sending the command.

Returns:

A dictionary containing the options and values that were selected by the user when the command was processed, if applicable. Returns None if the command has not yet been invoked, or if there are no options defined for that command.

Return type:

Optional[List[Dict[str, Any]]]

property unselected_options#

The options that were not provided by the user when sending the command.

Returns:

A list of Option objects (if any) that were not selected by the user when the command was processed. Returns None if there are no options defined for that command.

Return type:

Optional[List[Option]]

property send_modal#

This function is a coroutine. Responds to this interaction by sending a modal dialog. This cannot be used to respond to another modal dialog submission.

Parameters:

modal (discord.ui.Modal) – The modal dialog to display to the user.

Raises:
property respond#

This function is a coroutine.

Sends either a response or a message using the followup webhook determined by whether the interaction has been responded to or not.

Returns:

The response, its type depending on whether it’s an interaction response or a followup.

Return type:

Union[discord.Interaction, discord.WebhookMessage]

property send_response#

This function is a coroutine.

Responds to this interaction by sending a message.

Parameters:
  • content (Optional[str]) – The content of the message to send.

  • embeds (List[Embed]) – A list of embeds to send with the content. Maximum of 10. This cannot be mixed with the embed parameter.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with embeds parameter.

  • tts (bool) – Indicates if the message should be sent using text-to-speech.

  • view (discord.ui.View) – The view to send with the message.

  • ephemeral (bool) – Indicates if the message should only be visible to the user who started the interaction. If a view is sent with an ephemeral message, and it has no timeout set then the timeout is set to 15 minutes.

  • allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.

  • delete_after (float) – If provided, the number of seconds to wait in the background before deleting the message we just sent.

  • file (File) – The file to upload.

  • files (List[File]) – A list of files to upload. Must be a maximum of 10.

  • poll (Poll) –

    The poll to send.

    New in version 2.6.

Returns:

The interaction object associated with the sent message.

Return type:

Interaction

Raises:
property send_followup#

This function is a coroutine.

Sends a message using the webhook.

The content must be a type that can convert to a string through str(content).

To upload a single file, the file parameter should be used with a single File object.

If the embed parameter is provided, it must be of type Embed and it must be a rich embed type. You cannot mix the embed parameter with the embeds parameter, which must be a list of Embed objects to send.

Parameters:
  • content (str) – The content of the message to send.

  • wait (bool) – Whether the server should wait before sending a response. This essentially means that the return type of this function changes from None to a WebhookMessage if set to True. If the type of webhook is WebhookType.application then this is always set to True.

  • username (str) – The username to send with this message. If no username is provided then the default username for the webhook is used.

  • avatar_url (str) – The avatar URL to send with this message. If no avatar URL is provided then the default avatar for the webhook is used. If this is not a string then it is explicitly cast using str.

  • tts (bool) – Indicates if the message should be sent using text-to-speech.

  • ephemeral (bool) –

    Indicates if the message should only be visible to the user. This is only available to WebhookType.application webhooks. If a view is sent with an ephemeral message, and it has no timeout set then the timeout is set to 15 minutes.

    New in version 2.0.

  • file (File) – The file to upload. This cannot be mixed with files parameter.

  • files (List[File]) – A list of files to send with the content. This cannot be mixed with the file parameter.

  • embed (Embed) – The rich embed for the content to send. This cannot be mixed with embeds parameter.

  • embeds (List[Embed]) – A list of embeds to send with the content. Maximum of 10. This cannot be mixed with the embed parameter.

  • allowed_mentions (AllowedMentions) –

    Controls the mentions being processed in this message.

    New in version 1.4.

  • view (discord.ui.View) –

    The view to send with the message. You can only send a view if this webhook is not partial and has state attached. A webhook has state attached if the webhook is managed by the library.

    New in version 2.0.

  • thread (Snowflake) –

    The thread to send this webhook to.

    New in version 2.0.

  • thread_name (str) –

    The name of the thread to create. Only works for forum channels.

    New in version 2.0.

  • applied_tags (List[Snowflake]) –

    A list of tags to apply to the message. Only works for threads.

    New in version 2.5.

  • delete_after (float) – If provided, the number of seconds to wait in the background before deleting the message we just sent.

  • poll (Poll) –

    The poll to send.

    New in version 2.6.

Returns:

If wait is True then the message that was sent, otherwise None.

Return type:

Optional[WebhookMessage]

Raises:
  • HTTPException – Sending the message failed.

  • NotFound – This webhook was not found.

  • Forbidden – The authorization token for the webhook is incorrect.

  • TypeError – You specified both embed and embeds or file and files.

  • ValueError – The length of embeds was invalid.

  • InvalidArgument – Either there was no token associated with this webhook, ephemeral was passed with the improper webhook type, there was no state attached with this webhook when giving it a view, you specified both thread_name and thread, or applied_tags was passed with neither thread_name nor thread specified.

property defer#

This function is a coroutine.

Defers the interaction response.

This is typically used when the interaction is acknowledged and a secondary action will be done later.

This can only be used with the following interaction types:

Note

The follow-up response will also be non-ephemeral if the ephemeral argument is False, and ephemeral if True.

Parameters:
Raises:
property followup#

Returns the followup webhook for followup interactions.

await delete(*, delay=None)[source]#

This function is a coroutine.

Deletes the original interaction response message.

This is a higher level interface to Interaction.delete_original_response().

Parameters:

delay (Optional[float]) – If provided, the number of seconds to wait before deleting the message.

Raises:
  • HTTPException – Deleting the message failed.

  • Forbidden – You do not have proper permissions to delete the message.

Return type:

None

property edit#

This function is a coroutine.

Edits the original interaction response message.

This is a lower level interface to InteractionMessage.edit() in case you do not want to fetch the message and save an HTTP request.

This method is also the only way to edit the original message if the message sent was ephemeral.

Parameters:
  • content (Optional[str]) – The content to edit the message with or None to clear it.

  • embeds (List[Embed]) – A list of embeds to edit the message with.

  • embed (Optional[Embed]) – The embed to edit the message with. None suppresses the embeds. This should not be mixed with the embeds parameter.

  • file (File) – The file to upload. This cannot be mixed with files parameter.

  • files (List[File]) – A list of files to send with the content. This cannot be mixed with the file parameter.

  • attachments (List[Attachment]) – A list of attachments to keep in the message. If [] is passed then all attachments are removed.

  • allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.

  • view (Optional[View]) – The updated view to update this message with. If None is passed then the view is removed.

  • delete_after (Optional[float]) – If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored.

  • suppress (bool) – Whether to suppress embeds for the message.

Returns:

The newly edited message.

Return type:

InteractionMessage

Raises:
  • HTTPException – Editing the message failed.

  • Forbidden – Edited a message that is not yours.

  • TypeError – You specified both embed and embeds or file and files

  • ValueError – The length of embeds was invalid.

property cog#

Returns the cog associated with this context’s command. None if it does not exist.

class discord.AutocompleteContext(bot, interaction)[source]#

Represents context for a slash command’s option autocomplete.

This class is not created manually and is instead passed to an Option’s autocomplete callback.

New in version 2.0.

bot#

The bot that the command belongs to.

Type:

Bot

interaction#

The interaction object that invoked the autocomplete.

Type:

Interaction

command#

The command that this context belongs to.

Type:

ApplicationCommand

focused#

The option the user is currently typing.

Type:

Option

value#

The content of the focused option.

Type:

str

options#

A name to value mapping of the options that the user has selected before this option.

Type:

Dict[str, Any]

Parameters:
property cog#

Returns the cog associated with this context’s command. None if it does not exist.