Bots

This section documents everything related to bots - specialized disnake.Clients whose purpose is to streamline and simplify development of (application) commands.

Classes

Bot

Attributes
Methods
class disnake.ext.commands.Bot(command_prefix=None, help_command=<default-help-command>, description=None, *, strip_after_prefix=False, **options)[source]

Represents a discord bot.

This class is a subclass of disnake.Client and as a result anything that you can do with a disnake.Client you can do with this bot.

This class also subclasses GroupMixin to provide the functionality to manage commands.

Parameters:

  • test_guilds (List[int]) –

    The list of IDs of the guilds where you’re going to test your application commands. Defaults to None, which means global registration of commands across all guilds.

    New in version 2.1.

  • command_sync_flags (CommandSyncFlags) –

    The command sync flags for the session. This is a way of controlling when and how application commands will be synced with the Discord API. If not given, defaults to CommandSyncFlags.default().

    New in version 2.7.

  • sync_commands (bool) –

    Whether to enable automatic synchronization of application commands in your code. Defaults to True, which means that commands in API are automatically synced with the commands in your code.

    New in version 2.1.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • sync_commands_on_cog_unload (bool) –

    Whether to sync the application commands on cog unload / reload. Defaults to True.

    New in version 2.1.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • sync_commands_debug (bool) –

    Whether to always show sync debug logs (uses INFO log level if it’s enabled, prints otherwise). If disabled, uses the default DEBUG log level which isn’t shown unless the log level is changed manually. Useful for tracking the commands being registered in the API. Defaults to False.

    New in version 2.1.

    Changed in version 2.4: Changes the log level of corresponding messages from DEBUG to INFO or prints them, instead of controlling whether they are enabled at all.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • localization_provider (LocalizationProtocol) –

    An implementation of LocalizationProtocol to use for localization of application commands. If not provided, the default LocalizationStore implementation is used.

    New in version 2.5.

  • strict_localization (bool) –

    Whether to raise an exception when localizations for a specific key couldn’t be found. This is mainly useful for testing/debugging, consider disabling this eventually as missing localized names will automatically fall back to the default/base name without it. Only applicable if the localization_provider parameter is not provided. Defaults to False.

    New in version 2.5.

command_prefix

The command prefix is what the message content must contain initially to have a command invoked. This prefix could either be a string to indicate what the prefix should be, or a callable that takes in the bot as its first parameter and disnake.Message as its second parameter and returns the prefix. This is to facilitate “dynamic” command prefixes. This callable can be either a regular function or a coroutine.

An empty string as the prefix always matches, enabling prefix-less command invocation. While this may be useful in DMs it should be avoided in servers, as it’s likely to cause performance issues and unintended command invocations.

The command prefix could also be an iterable of strings indicating that multiple checks for the prefix should be used and the first one to match will be the invocation prefix. You can get this prefix via Context.prefix. To avoid confusion empty iterables are not allowed.

If the prefix is None, the bot won’t listen to any prefixes, and prefix commands will not be processed. If you don’t need prefix commands, consider using InteractionBot or AutoShardedInteractionBot instead, which are drop-in replacements, just without prefix command support.

This can be provided as a parameter at creation.

Note

When passing multiple prefixes be careful to not pass a prefix that matches a longer prefix occurring later in the sequence. For example, if the command prefix is ('!', '!?') the '!?' prefix will never be matched to any message as the previous one matches messages starting with !?. This is especially important when passing an empty string, it should always be last as no prefix after it will be matched.

case_insensitive

Whether the commands should be case insensitive. Defaults to False. This attribute does not carry over to groups. You must set it to every group if you require group commands to be case insensitive as well.

This can be provided as a parameter at creation.

Type:

bool

description

The content prefixed into the default help message.

This can be provided as a parameter at creation.

Type:

str

help_command[source]

The help command implementation to use. This can be dynamically set at runtime. To remove the help command pass None. For more information on implementing a help command, see Help Commands.

This can be provided as a parameter at creation.

Type:

Optional[HelpCommand]

owner_id

The user ID that owns the bot. If this is not set and is then queried via is_owner() then it is fetched automatically using application_info().

This can be provided as a parameter at creation.

Type:

Optional[int]

owner_ids

The user IDs that owns the bot. This is similar to owner_id. If this is not set and the application is team based, then it is fetched automatically using application_info(). For performance reasons it is recommended to use a set for the collection. You cannot set both owner_id and owner_ids.

This can be provided as a parameter at creation.

New in version 1.3.

Type:

Optional[Collection[int]]

strip_after_prefix

Whether to strip whitespace characters after encountering the command prefix. This allows for !   hello and !hello to both work if the command_prefix is set to !. Defaults to False.

This can be provided as a parameter at creation.

New in version 1.7.

Type:

bool

reload

Whether to enable automatic extension reloading on file modification for debugging. Whenever you save an extension with reloading enabled the file will be automatically reloaded for you so you do not have to reload the extension manually. Defaults to False

This can be provided as a parameter at creation.

New in version 2.1.

Type:

bool

i18n

An implementation of LocalizationProtocol used for localization of application commands.

New in version 2.5.

Type:

LocalizationProtocol

@after_invoke[source]

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

This is for text commands only, and doesn’t apply to application commands.

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, a Context.

Note

Similar to before_invoke(), this is not called unless checks and argument parsing procedures succeed. This hook is, however, always called regardless of the internal command callback raising an error (i.e. CommandInvokeError). This makes it ideal for clean-up scenarios.

Parameters:

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

Raises:

TypeError – The coroutine passed is not actually a coroutine.

@after_slash_command_invoke[source]

Similar to Bot.after_invoke() but for slash commands, and it takes an ApplicationCommandInteraction as its only parameter.

@after_user_command_invoke[source]

Similar to Bot.after_slash_command_invoke() but for user commands.

@after_message_command_invoke[source]

Similar to Bot.after_slash_command_invoke() but for message commands.

@before_invoke[source]

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

This is for text commands only, and doesn’t apply to application commands.

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, a Context.

Note

The before_invoke() and after_invoke() hooks are only called if all checks and argument parsing procedures pass without error. If any check or argument parsing procedures fail then the hooks are not called.

Parameters:

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

Raises:

TypeError – The coroutine passed is not actually a coroutine.

@before_slash_command_invoke[source]

Similar to Bot.before_invoke() but for slash commands, and it takes an ApplicationCommandInteraction as its only parameter.

@before_user_command_invoke[source]

Similar to Bot.before_slash_command_invoke() but for user commands.

@before_message_command_invoke[source]

Similar to Bot.before_slash_command_invoke() but for message commands.

@check[source]

A decorator that adds a global check to the bot.

This is for text commands only, and doesn’t apply to application commands.

A global check is similar to a check() that is applied on a per command basis except it is run before any command checks have been verified and applies to every command the bot has.

Note

This function can either be a regular function or a coroutine.

Similar to a command check(), this takes a single parameter of type Context and can only raise exceptions inherited from CommandError.

Example

@bot.check
def check_commands(ctx):
    return ctx.command.qualified_name in allowed_commands
@check_once[source]

A decorator that adds a “call once” global check to the bot.

This is for text commands only, and doesn’t apply to application commands.

Unlike regular global checks, this one is called only once per invoke() call.

Regular global checks are called whenever a command is called or Command.can_run() is called. This type of check bypasses that and ensures that it’s called only once, even inside the default help command.

Note

When using this function the Context sent to a group subcommand may only parse the parent command and not the subcommands due to it being invoked once per Bot.invoke() call.

Note

This function can either be a regular function or a coroutine.

Similar to a command check(), this takes a single parameter of type Context and can only raise exceptions inherited from CommandError.

Example

@bot.check_once
def whitelist(ctx):
    return ctx.message.author.id in my_whitelist
@command(*args, **kwargs)[source]

A shortcut decorator that invokes command() and adds it to the internal command list via add_command().

Returns:

A decorator that converts the provided method into a Command, adds it to the bot, then returns it.

Return type:

Callable[…, Command]

@slash_command(*args, **kwargs)[source]

A shortcut decorator that invokes slash_command() and adds it to the internal command list.

Parameters:

  • name (Optional[Union[str, Localized]]) –

    The name of the slash command (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • description (Optional[Union[str, Localized]]) –

    The description of the slash command. It will be visible in Discord.

    Changed in version 2.5: Added support for localizations.

  • options (List[Option]) – The list of slash command options. The options will be visible in Discord. This is the old way of specifying options. Consider using Parameters instead.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

    The default required permissions for this command. See ApplicationCommand.default_member_permissions for details.

    New in version 2.5.

  • nsfw (bool) –

    Whether this command is age-restricted. Defaults to False.

    New in version 2.8.

  • auto_sync (bool) – Whether to automatically register the command. Defaults to True

  • guild_ids (Sequence[int]) – If specified, the client will register the command in these guilds. Otherwise, this command will be registered globally.

  • connectors (Dict[str, str]) – Binds function names to option names. If the name of an option already matches the corresponding function param, you don’t have to specify the connectors. Connectors template: {"option-name": "param_name", ...}. If you’re using Parameters, you don’t need to specify this.

  • extras (Dict[str, Any]) –

    A dict of user provided extras to attach to the command.

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

A decorator that converts the provided method into an InvokableSlashCommand, adds it to the bot, then returns it.

Return type:

Callable[…, InvokableSlashCommand]

@user_command(*args, **kwargs)[source]

A shortcut decorator that invokes user_command() and adds it to the internal command list.

Parameters:

  • name (Optional[Union[str, Localized]]) –

    The name of the user command (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

    The default required permissions for this command. See ApplicationCommand.default_member_permissions for details.

    New in version 2.5.

  • nsfw (bool) –

    Whether this command is age-restricted. Defaults to False.

    New in version 2.8.

  • auto_sync (bool) – Whether to automatically register the command. Defaults to True.

  • guild_ids (Sequence[int]) – If specified, the client will register the command in these guilds. Otherwise, this command will be registered globally.

  • extras (Dict[str, Any]) –

    A dict of user provided extras to attach to the command.

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

A decorator that converts the provided method into an InvokableUserCommand, adds it to the bot, then returns it.

Return type:

Callable[…, InvokableUserCommand]

@message_command(*args, **kwargs)[source]

A shortcut decorator that invokes message_command() and adds it to the internal command list.

Parameters:

  • name (Optional[Union[str, Localized]]) –

    The name of the message command (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

    The default required permissions for this command. See ApplicationCommand.default_member_permissions for details.

    New in version 2.5.

  • nsfw (bool) –

    Whether this command is age-restricted. Defaults to False.

    New in version 2.8.

  • auto_sync (bool) – Whether to automatically register the command. Defaults to True

  • guild_ids (Sequence[int]) – If specified, the client will register the command in these guilds. Otherwise, this command will be registered globally.

  • extras (Dict[str, Any]) –

    A dict of user provided extras to attach to the command.

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

A decorator that converts the provided method into an InvokableMessageCommand, adds it to the bot, then returns it.

Return type:

Callable[…, InvokableMessageCommand]

@event[source]

A decorator that registers an event to listen to.

You can find more info about the events in the documentation.

The events must be a coroutine, if not, TypeError is raised.

Example

@client.event
async def on_ready():
    print('Ready!')
Raises:

TypeError – The coroutine passed is not actually a coroutine.

@group(*args, **kwargs)[source]

A shortcut decorator that invokes group() and adds it to the internal command list via add_command().

Returns:

A decorator that converts the provided method into a Group, adds it to the bot, then returns it.

Return type:

Callable[…, Group]

@listen(name=None)[source]

A decorator that registers another function as an external event listener. Basically this allows you to listen to multiple events from different places e.g. such as on_ready()

The functions being listened to must be a coroutine.

Example

@bot.listen()
async def on_message(message):
    print('one')

# in some other file...

@bot.listen('on_message')
async def my_message(message):
    print('two')

# in yet another file
@bot.listen(Event.message)
async def another_message(message):
    print('three')

Would print one, two and three in an unspecified order.

Raises:

TypeError – The function being listened to is not a coroutine or a string or an Event was not passed as the name.

property activity[source]

The activity being used upon logging in.

Type:

Optional[BaseActivity]

add_app_command_check(func, *, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

Adds a global application command check to the bot.

This is the non-decorator interface to check(), check_once(), slash_command_check() and etc.

You must specify at least one of the bool parameters, otherwise the check won’t be added.

Parameters:

  • func – The function that will be used as a global check.

  • call_once (bool) – Whether the function should only be called once per invoke call.

  • slash_commands (bool) – Whether this check is for slash commands.

  • user_commands (bool) – Whether this check is for user commands.

  • message_commands (bool) – Whether this check is for message commands.

add_check(func, *, call_once=False)[source]

Adds a global check to the bot.

This is for text commands only, and doesn’t apply to application commands.

This is the non-decorator interface to check() and check_once().

Parameters:

  • func – The function that was used as a global check.

  • call_once (bool) – If the function should only be called once per invoke() call.

add_cog(cog, *, override=False)[source]

Adds a “cog” to the bot.

A cog is a class that has its own event listeners and commands.

Changed in version 2.0: ClientException is raised when a cog with the same name is already loaded.

Parameters:

  • cog (Cog) – The cog to register to the bot.

  • override (bool) –

    If a previously loaded cog with the same name should be ejected instead of raising an error.

    New in version 2.0.

Raises:
add_command(command)[source]

Adds a Command into the internal list of commands.

This is usually not called, instead the command() or group() shortcut decorators are used instead.

Changed in version 1.4: Raise CommandRegistrationError instead of generic ClientException

Parameters:

command (Command) – The command to add.

Raises:
add_listener(func, name=...)[source]

The non decorator alternative to listen().

Parameters:

  • func (coroutine) – The function to call.

  • name (Union[str, Event]) – The name of the event to listen for. Defaults to func.__name__.

Example

async def on_ready(): pass
async def my_message(message): pass
async def another_message(message): pass

bot.add_listener(on_ready)
bot.add_listener(my_message, 'on_message')
bot.add_listener(another_message, Event.message)
Raises:

TypeError – The function is not a coroutine or a string or an Event was not passed as the name.

add_message_command(message_command)[source]

Adds an InvokableMessageCommand into the internal list of message commands.

This is usually not called, instead the message_command() or shortcut decorators are used.

Parameters:

message_command (InvokableMessageCommand) – The message command to add.

Raises:
add_slash_command(slash_command)[source]

Adds an InvokableSlashCommand into the internal list of slash commands.

This is usually not called, instead the slash_command() or shortcut decorators are used.

Parameters:

slash_command (InvokableSlashCommand) – The slash command to add.

Raises:
add_user_command(user_command)[source]

Adds an InvokableUserCommand into the internal list of user commands.

This is usually not called, instead the user_command() or shortcut decorators are used.

Parameters:

user_command (InvokableUserCommand) – The user command to add.

Raises:
add_view(view, *, message_id=None)[source]

Registers a View for persistent listening.

This method should be used for when a view is comprised of components that last longer than the lifecycle of the program.

New in version 2.0.

Parameters:

  • view (disnake.ui.View) – The view to register for dispatching.

  • message_id (Optional[int]) – The message ID that the view is attached to. This is currently used to refresh the view’s state during message update events. If not given then message update events are not propagated for the view.

Raises:

  • TypeError – A view was not passed.

  • ValueError – The view is not persistent. A persistent view has no timeout and all their components have an explicitly provided custom_id.

property allowed_mentions[source]

The allowed mention configuration.

New in version 1.4.

Type:

Optional[AllowedMentions]

application_command_check(*, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

A decorator that adds a global application command check to the bot.

A global check is similar to a check() that is applied on a per command basis except it is run before any application command checks have been verified and applies to every application command the bot has.

Note

This function can either be a regular function or a coroutine.

Similar to a command check(), this takes a single parameter of type ApplicationCommandInteraction and can only raise exceptions inherited from CommandError.

Example

@bot.application_command_check()
def check_app_commands(inter):
    return inter.channel_id in whitelisted_channels
Parameters:

  • call_once (bool) – Whether the function should only be called once per invoke call.

  • slash_commands (bool) – Whether this check is for slash commands.

  • user_commands (bool) – Whether this check is for user commands.

  • message_commands (bool) – Whether this check is for message commands.

property application_commands[source]

A set of all application commands the bot has.

Type:

Set[InvokableApplicationCommand]

property application_flags[source]

The client’s application flags.

New in version 2.0.

Type:

ApplicationFlags

property application_id[source]

The client’s application ID.

If this is not passed via __init__ then this is retrieved through the gateway when an event contains the data. Usually after on_connect() is called.

New in version 2.0.

Type:

Optional[int]

await application_info()[source]

This function is a coroutine.

Retrieves the bot’s application information.

Raises:

HTTPException – Retrieving the information failed somehow.

Returns:

The bot’s application information.

Return type:

AppInfo

await before_identify_hook(shard_id, *, initial=False)[source]

This function is a coroutine.

A hook that is called before IDENTIFYing a session. This is useful if you wish to have more control over the synchronization of multiple IDENTIFYing clients.

The default implementation sleeps for 5 seconds.

New in version 1.4.

Parameters:

  • shard_id (int) – The shard ID that requested being IDENTIFY’d

  • initial (bool) – Whether this IDENTIFY is the first initial IDENTIFY.

await bulk_fetch_command_permissions(guild_id)[source]

This function is a coroutine.

Retrieves a list of GuildApplicationCommandPermissions configured for the guild with the given ID.

New in version 2.1.

Parameters:

guild_id (int) – The ID of the guild to inspect.

await bulk_overwrite_global_commands(application_commands)[source]

This function is a coroutine.

Overwrites several global application commands in one API request.

New in version 2.1.

Parameters:

application_commands (List[ApplicationCommand]) – A list of application commands to insert instead of the existing commands.

Returns:

A list of registered application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await bulk_overwrite_guild_commands(guild_id, application_commands)[source]

This function is a coroutine.

Overwrites several guild application commands in one API request.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild where the application commands should be overwritten.

  • application_commands (List[ApplicationCommand]) – A list of application commands to insert instead of the existing commands.

Returns:

A list of registered application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

property cached_messages[source]

Read-only list of messages the connected client has cached.

New in version 1.1.

Type:

Sequence[Message]

await change_presence(*, activity=None, status=None)[source]

This function is a coroutine.

Changes the client’s presence.

Changed in version 2.0: Removed the afk keyword-only parameter.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Example

game = disnake.Game("with the API")
await client.change_presence(status=disnake.Status.idle, activity=game)
Parameters:

  • activity (Optional[BaseActivity]) – The activity being done. None if no currently active activity is done.

  • status (Optional[Status]) – Indicates what status to change to. If None, then Status.online is used.

Raises:

TypeError – If the activity parameter is not the proper type.

clear()[source]

Clears the internal state of the bot.

After this, the bot can be considered “re-opened”, i.e. is_closed() and is_ready() both return False along with the bot’s internal cache cleared.

await close()[source]

This function is a coroutine.

Closes the connection to Discord.

property cogs[source]

A read-only mapping of cog name to cog.

Type:

Mapping[str, Cog]

property command_sync_flags[source]

The command sync flags configured for this bot.

New in version 2.7.

Type:

CommandSyncFlags

property commands[source]

A unique set of commands without aliases that are registered.

Type:

Set[Command]

await connect(*, reconnect=True, ignore_session_start_limit=False)[source]

This function is a coroutine.

Creates a websocket connection and lets the websocket listen to messages from Discord. This is a loop that runs the entire event system and miscellaneous aspects of the library. Control is not resumed until the WebSocket connection is terminated.

Changed in version 2.6: Added usage of SessionStartLimit when connecting to the API. Added the ignore_session_start_limit parameter.

Parameters:

  • reconnect (bool) – Whether reconnecting should be attempted, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

  • ignore_session_start_limit (bool) –

    Whether the API provided session start limit should be ignored when connecting to the API.

    New in version 2.6.

Raises:

  • GatewayNotFound – If the gateway to connect to Discord is not found. Usually if this is thrown then there is a Discord API outage.

  • ConnectionClosed – The websocket connection has been terminated.

  • SessionStartLimitReached – If the client doesn’t have enough connects remaining in the current 24-hour window and ignore_session_start_limit is False this will be raised rather than connecting to the gateawy and Discord resetting the token. However, if ignore_session_start_limit is True, the client will connect regardless and this exception will not be raised.

await create_dm(user)[source]

This function is a coroutine.

Creates a DMChannel with the given user.

This should be rarely called, as this is done transparently for most people.

New in version 2.0.

Parameters:

user (Snowflake) – The user to create a DM with.

Returns:

The channel that was created.

Return type:

DMChannel

await create_global_command(application_command)[source]

This function is a coroutine.

Creates a global application command.

New in version 2.1.

Parameters:

application_command (ApplicationCommand) – An object representing the application command to create.

Returns:

The application command that was created.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await create_guild(*, name, icon=..., code=...)[source]

This function is a coroutine.

Creates a Guild.

See guild_builder() for a more comprehensive alternative.

Bot accounts in 10 or more guilds are not allowed to create guilds.

Note

Using this, you will not receive Guild.channels, Guild.members, Member.activity and Member.voice per Member.

Changed in version 2.5: Removed the region parameter.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:
Raises:
Returns:

The created guild. This is not the same guild that is added to cache.

Return type:

Guild

await create_guild_command(guild_id, application_command)[source]

This function is a coroutine.

Creates a guild application command.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild where the application command should be created.

  • application_command (ApplicationCommand) – The application command.

Returns:

The newly created application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await delete_global_command(command_id)[source]

This function is a coroutine.

Deletes a global application command.

New in version 2.1.

Parameters:

command_id (int) – The ID of the application command to delete.

await delete_guild_command(guild_id, command_id)[source]

This function is a coroutine.

Deletes a guild application command.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild where the applcation command should be deleted.

  • command_id (int) – The ID of the application command to delete.

await delete_invite(invite)[source]

This function is a coroutine.

Revokes an Invite, URL, or ID to an invite.

You must have manage_channels permission in the associated guild to do this.

Parameters:

invite (Union[Invite, str]) – The invite to revoke.

Raises:

  • Forbidden – You do not have permissions to revoke invites.

  • NotFound – The invite is invalid or expired.

  • HTTPException – Revoking the invite failed.

await edit_global_command(command_id, new_command)[source]

This function is a coroutine.

Edits a global application command.

New in version 2.1.

Parameters:

  • command_id (int) – The ID of the application command to edit.

  • new_command (ApplicationCommand) – An object representing the edited application command.

Returns:

The edited application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await edit_guild_command(guild_id, command_id, new_command)[source]

This function is a coroutine.

Edits a guild application command.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild where the application command should be edited.

  • command_id (int) – The ID of the application command to edit.

  • new_command (ApplicationCommand) – An object representing the edited application command.

Returns:

The newly edited application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await edit_role_connection_metadata(records)[source]

This function is a coroutine.

Edits the ApplicationRoleConnectionMetadata records for the application.

An application can have up to 5 metadata records.

Warning

This will overwrite all existing metadata records. Consider fetching them first, and constructing the new list of metadata records based off of the returned list.

New in version 2.8.

Parameters:

records (Sequence[ApplicationRoleConnectionMetadata]) – The new metadata records.

Raises:

HTTPException – Editing the metadata records failed.

Returns:

The list of newly edited metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

property emojis[source]

The emojis that the connected client has.

Type:

List[Emoji]

property extensions[source]

A read-only mapping of extension name to extension.

Type:

Mapping[str, types.ModuleType]

await fetch_channel(channel_id, /)[source]

This function is a coroutine.

Retrieves a abc.GuildChannel, abc.PrivateChannel, or Thread with the specified ID.

Note

This method is an API call. For general usage, consider get_channel() instead.

New in version 1.2.

Parameters:

channel_id (int) – The ID of the channel to retrieve.

Raises:

  • InvalidData – An unknown channel type was received from Discord.

  • HTTPException – Retrieving the channel failed.

  • NotFound – Invalid Channel ID.

  • Forbidden – You do not have permission to fetch this channel.

Returns:

The channel from the ID.

Return type:

Union[abc.GuildChannel, abc.PrivateChannel, Thread]

await fetch_command_permissions(guild_id, command_id)[source]

This function is a coroutine.

Retrieves GuildApplicationCommandPermissions for a specific application command in the guild with the given ID.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild to inspect.

  • command_id (int) –

    The ID of the application command, or the application ID to fetch application-wide permissions.

    Changed in version 2.5: Can now also fetch application-wide permissions.

Returns:

The permissions configured for the specified application command.

Return type:

GuildApplicationCommandPermissions

await fetch_global_command(command_id)[source]

This function is a coroutine.

Retrieves a global application command.

New in version 2.1.

Parameters:

command_id (int) – The ID of the command to retrieve.

Returns:

The requested application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await fetch_global_commands(*, with_localizations=True)[source]

This function is a coroutine.

Retrieves a list of global application commands.

New in version 2.1.

Parameters:

with_localizations (bool) –

Whether to include localizations in the response. Defaults to True.

New in version 2.5.

Returns:

A list of application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await fetch_guild(guild_id, /)[source]

This function is a coroutine.

Retrieves a Guild from the given ID.

Note

Using this, you will not receive Guild.channels, Guild.members, Member.activity and Member.voice per Member.

Note

This method is an API call. For general usage, consider get_guild() instead.

Parameters:

guild_id (int) – The ID of the guild to retrieve.

Raises:
Returns:

The guild from the given ID.

Return type:

Guild

await fetch_guild_command(guild_id, command_id)[source]

This function is a coroutine.

Retrieves a guild application command.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild to fetch command from.

  • command_id (int) – The ID of the application command to retrieve.

Returns:

The requested application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await fetch_guild_commands(guild_id, *, with_localizations=True)[source]

This function is a coroutine.

Retrieves a list of guild application commands.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild to fetch commands from.

  • with_localizations (bool) –

    Whether to include localizations in the response. Defaults to True.

    New in version 2.5.

Returns:

A list of application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await fetch_guild_preview(guild_id, /)[source]

This function is a coroutine.

Retrieves a GuildPreview from the given ID. Your bot does not have to be in this guild.

Note

This method may fetch any guild that has DISCOVERABLE in Guild.features, but this information can not be known ahead of time.

This will work for any guild that you are in.

Parameters:

guild_id (int) – The ID of the guild to to retrieve a preview object.

Raises:

NotFound – Retrieving the guild preview failed.

Returns:

The guild preview from the given ID.

Return type:

GuildPreview

fetch_guilds(*, limit=100, before=None, after=None)[source]

Retrieves an AsyncIterator that enables receiving your guilds.

Note

Using this, you will only receive Guild.id, Guild.name, Guild.features, Guild.icon, and Guild.banner per Guild.

Note

This method is an API call. For general usage, consider guilds instead.

Examples

Usage

async for guild in client.fetch_guilds(limit=150):
    print(guild.name)

Flattening into a list

guilds = await client.fetch_guilds(limit=150).flatten()
# guilds is now a list of Guild...

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of guilds to retrieve. If None, it retrieves every guild you have access to. Note, however, that this would make it a slow operation. Defaults to 100.

  • before (Union[abc.Snowflake, datetime.datetime]) – Retrieves guilds before this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Union[abc.Snowflake, datetime.datetime]) – Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

Raises:

HTTPException – Retrieving the guilds failed.

Yields:

Guild – The guild with the guild data parsed.

await fetch_invite(url, *, with_counts=True, with_expiration=True, guild_scheduled_event_id=None)[source]

This function is a coroutine.

Retrieves an Invite from a discord.gg URL or ID.

Note

If the invite is for a guild you have not joined, the guild and channel attributes of the returned Invite will be PartialInviteGuild and PartialInviteChannel respectively.

Parameters:

  • url (Union[Invite, str]) – The Discord invite ID or URL (must be a discord.gg URL).

  • with_counts (bool) – Whether to include count information in the invite. This fills the Invite.approximate_member_count and Invite.approximate_presence_count fields.

  • with_expiration (bool) –

    Whether to include the expiration date of the invite. This fills the Invite.expires_at field.

    New in version 2.0.

  • guild_scheduled_event_id (int) –

    The ID of the scheduled event to include in the invite. If not provided, defaults to the event parameter in the URL if it exists, or the ID of the scheduled event contained in the provided invite object.

    New in version 2.3.

Raises:
Returns:

The invite from the URL/ID.

Return type:

Invite

await fetch_premium_sticker_packs()[source]

This function is a coroutine.

Retrieves all available premium sticker packs.

New in version 2.0.

Raises:

HTTPException – Retrieving the sticker packs failed.

Returns:

All available premium sticker packs.

Return type:

List[StickerPack]

await fetch_role_connection_metadata()[source]

This function is a coroutine.

Retrieves the ApplicationRoleConnectionMetadata records for the application.

New in version 2.8.

Raises:

HTTPException – Retrieving the metadata records failed.

Returns:

The list of metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

await fetch_stage_instance(channel_id, /)[source]

This function is a coroutine.

Retrieves a StageInstance with the given ID.

Note

This method is an API call. For general usage, consider get_stage_instance() instead.

New in version 2.0.

Parameters:

channel_id (int) – The stage channel ID.

Raises:

  • NotFound – The stage instance or channel could not be found.

  • HTTPException – Retrieving the stage instance failed.

Returns:

The stage instance from the given ID.

Return type:

StageInstance

await fetch_sticker(sticker_id, /)[source]

This function is a coroutine.

Retrieves a Sticker with the given ID.

New in version 2.0.

Parameters:

sticker_id (int) – The ID of the sticker to retrieve.

Raises:
Returns:

The sticker you requested.

Return type:

Union[StandardSticker, GuildSticker]

await fetch_template(code)[source]

This function is a coroutine.

Retrieves a Template from a discord.new URL or code.

Parameters:

code (Union[Template, str]) – The Discord Template Code or URL (must be a discord.new URL).

Raises:
Returns:

The template from the URL/code.

Return type:

Template

await fetch_user(user_id, /)[source]

This function is a coroutine.

Retrieves a User based on their ID. You do not have to share any guilds with the user to get this information, however many operations do require that you do.

Note

This method is an API call. If you have disnake.Intents.members and member cache enabled, consider get_user() instead.

Parameters:

user_id (int) – The ID of the user to retrieve.

Raises:
Returns:

The user you requested.

Return type:

User

await fetch_voice_regions(guild_id=None)[source]

Retrieves a list of VoiceRegions.

Retrieves voice regions for the user, or a guild if provided.

New in version 2.5.

Parameters:

guild_id (Optional[int]) – The guild to get regions for, if provided.

Raises:

  • HTTPException – Retrieving voice regions failed.

  • NotFound – The provided guild_id could not be found.

await fetch_webhook(webhook_id, /)[source]

This function is a coroutine.

Retrieves a Webhook with the given ID.

Parameters:

webhook_id (int) – The ID of the webhook to retrieve.

Raises:
Returns:

The webhook you requested.

Return type:

Webhook

await fetch_widget(guild_id, /)[source]

This function is a coroutine.

Retrieves a Widget for the given guild ID.

Note

The guild must have the widget enabled to get this information.

Parameters:

guild_id (int) – The ID of the guild.

Raises:
Returns:

The guild’s widget.

Return type:

Widget

for ... in get_all_channels()[source]

A generator that retrieves every abc.GuildChannel the client can ‘access’.

This is equivalent to:

for guild in client.guilds:
    for channel in guild.channels:
        yield channel

Note

Just because you receive a abc.GuildChannel does not mean that you can communicate in said channel. abc.GuildChannel.permissions_for() should be used for that.

Yields:

abc.GuildChannel – A channel the client can ‘access’.

for ... in get_all_members()[source]

Returns a generator with every Member the client can see.

This is equivalent to:

for guild in client.guilds:
    for member in guild.members:
        yield member
Yields:

Member – A member the client can see.

get_channel(id, /)[source]

Returns a channel or thread with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The returned channel or None if not found.

Return type:

Optional[Union[abc.GuildChannel, Thread, abc.PrivateChannel]]

get_cog(name)[source]

Gets the cog instance requested.

If the cog is not found, None is returned instead.

Parameters:

name (str) – The name of the cog you are requesting. This is equivalent to the name passed via keyword argument in class creation or the class name if unspecified.

Returns:

The cog that was requested. If not found, returns None.

Return type:

Optional[Cog]

get_command(name)[source]

Get a Command from the internal list of commands.

This could also be used as a way to get aliases.

The name could be fully qualified (e.g. 'foo bar') will get the subcommand bar of the group command foo. If a subcommand is not found then None is returned just as usual.

Parameters:

name (str) – The name of the command to get.

Returns:

The command that was requested. If not found, returns None.

Return type:

Optional[Command]

await get_context(message, *, cls=<class 'disnake.ext.commands.context.Context'>)[source]

This function is a coroutine.

Returns the invocation context from the message.

This is a more low-level counter-part for process_commands() to allow users more fine grained control over the processing.

The returned context is not guaranteed to be a valid invocation context, Context.valid must be checked to make sure it is. If the context is not valid then it is not a valid candidate to be invoked under invoke().

Parameters:

  • message (disnake.Message) – The message to get the invocation context from.

  • cls – The factory class that will be used to create the context. By default, this is Context. Should a custom class be provided, it must be similar enough to Context’s interface.

Returns:

The invocation context. The type of this can change via the cls parameter.

Return type:

Context

get_emoji(id, /)[source]

Returns an emoji with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The custom emoji or None if not found.

Return type:

Optional[Emoji]

get_global_command(id)[source]

Returns a global application command with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The application command.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_global_command_named(name, cmd_type=None)[source]

Returns a global application command matching the given name.

Parameters:

  • name (str) – The name to look for.

  • cmd_type (ApplicationCommandType) – The type to look for. By default, no types are checked.

Returns:

The application command.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild(id, /)[source]

Returns a guild with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The guild or None if not found.

Return type:

Optional[Guild]

get_guild_application_commands(guild_id)[source]

Returns a list of all application commands in the guild with the given ID.

Parameters:

guild_id (int) – The ID to search for.

Returns:

The list of application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_command(guild_id, id)[source]

Returns a guild application command with the given guild ID and application command ID.

Parameters:

  • guild_id (int) – The guild ID to search for.

  • id (int) – The command ID to search for.

Returns:

The application command.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_command_named(guild_id, name, cmd_type=None)[source]

Returns a guild application command matching the given name.

Parameters:

  • guild_id (int) – The guild ID to search for.

  • name (str) – The command name to search for.

  • cmd_type (ApplicationCommandType) – The type to look for. By default, no types are checked.

Returns:

The application command.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_message_commands(guild_id)[source]

Returns a list of all message commands in the guild with the given ID.

Parameters:

guild_id (int) – The ID to search for.

Returns:

The list of message commands.

Return type:

List[APIMessageCommand]

get_guild_slash_commands(guild_id)[source]

Returns a list of all slash commands in the guild with the given ID.

Parameters:

guild_id (int) – The ID to search for.

Returns:

The list of slash commands.

Return type:

List[APISlashCommand]

get_guild_user_commands(guild_id)[source]

Returns a list of all user commands in the guild with the given ID.

Parameters:

guild_id (int) – The ID to search for.

Returns:

The list of user commands.

Return type:

List[APIUserCommand]

get_listeners()[source]

Mapping[str, List[Callable]]: A read-only mapping of event names to listeners.

Note

To add or remove a listener you should use add_listener() and remove_listener().

New in version 2.9.

get_message(id)[source]

Gets the message with the given ID from the bot’s message cache.

Parameters:

id (int) – The ID of the message to look for.

Returns:

The corresponding message.

Return type:

Optional[Message]

get_message_command(name)[source]

Gets an InvokableMessageCommand from the internal list of message commands.

Parameters:

name (str) – The name of the message command to get.

Returns:

The message command that was requested. If not found, returns None.

Return type:

Optional[InvokableMessageCommand]

await get_or_fetch_user(user_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the user from the cache. If fails, it tries to fetch the user from the API.

Parameters:

  • user_id (int) – The ID to search for.

  • strict (bool) – Whether to propagate exceptions from fetch_user() instead of returning None in case of failure (e.g. if the user wasn’t found). Defaults to False.

Returns:

The user with the given ID, or None if not found and strict is set to False.

Return type:

Optional[User]

get_partial_messageable(id, *, type=None)[source]

Returns a partial messageable with the given channel ID.

This is useful if you have a channel_id but don’t want to do an API call to send messages to it.

New in version 2.0.

Parameters:

  • id (int) – The channel ID to create a partial messageable for.

  • type (Optional[ChannelType]) – The underlying channel type for the partial messageable.

Returns:

The partial messageable

Return type:

PartialMessageable

await get_prefix(message)[source]

This function is a coroutine.

Retrieves the prefix the bot is listening to with the message as a context.

Parameters:

message (disnake.Message) – The message context to get the prefix of.

Returns:

A list of prefixes or a single prefix that the bot is listening for. None if the bot isn’t listening for prefixes.

Return type:

Optional[Union[List[str], str]]

get_slash_command(name)[source]

Works like Bot.get_command, but for slash commands.

If the name contains spaces, then it will assume that you are looking for a SubCommand or a SubCommandGroup. e.g: 'foo bar' will get the sub command group, or the sub command bar of the top-level slash command foo if found, otherwise None.

Parameters:

name (str) – The name of the slash command to get.

Raises:

TypeError – The name is not a string.

Returns:

The slash command that was requested. If not found, returns None.

Return type:

Optional[Union[InvokableSlashCommand, SubCommandGroup, SubCommand]]

get_stage_instance(id, /)[source]

Returns a stage instance with the given stage channel ID.

New in version 2.0.

Parameters:

id (int) – The ID to search for.

Returns:

The returns stage instance or None if not found.

Return type:

Optional[StageInstance]

get_sticker(id, /)[source]

Returns a guild sticker with the given ID.

New in version 2.0.

Note

To retrieve standard stickers, use fetch_sticker(). or fetch_premium_sticker_packs().

Returns:

The sticker or None if not found.

Return type:

Optional[GuildSticker]

get_user(id, /)[source]

Returns a user with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The user or None if not found.

Return type:

Optional[User]

get_user_command(name)[source]

Gets an InvokableUserCommand from the internal list of user commands.

Parameters:

name (str) – The name of the user command to get.

Returns:

The user command that was requested. If not found, returns None.

Return type:

Optional[InvokableUserCommand]

await getch_user(user_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the user from the cache. If fails, it tries to fetch the user from the API.

Parameters:

  • user_id (int) – The ID to search for.

  • strict (bool) – Whether to propagate exceptions from fetch_user() instead of returning None in case of failure (e.g. if the user wasn’t found). Defaults to False.

Returns:

The user with the given ID, or None if not found and strict is set to False.

Return type:

Optional[User]

property global_application_commands[source]

The client’s global application commands.

Type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]

property global_message_commands[source]

The client’s global message commands.

Type:

List[APIMessageCommand]

property global_slash_commands[source]

The client’s global slash commands.

Type:

List[APISlashCommand]

property global_user_commands[source]

The client’s global user commands.

Type:

List[APIUserCommand]

guild_builder(name)[source]

Creates a builder object that can be used to create more complex guilds.

This is a more comprehensive alternative to create_guild(). See GuildBuilder for details and examples.

Bot accounts in 10 or more guilds are not allowed to create guilds.

Note

Using this, you will not receive Guild.channels, Guild.members, Member.activity and Member.voice per Member.

New in version 2.8.

Parameters:

name (str) – The name of the guild.

Returns:

The guild builder object for configuring and creating a new guild.

Return type:

GuildBuilder

property guilds[source]

The guilds that the connected client is a member of.

Type:

List[Guild]

property intents[source]

The intents configured for this connection.

New in version 1.5.

Type:

Intents

await invoke(ctx)[source]

This function is a coroutine.

Invokes the command given under the invocation context and handles all the internal event dispatch mechanisms.

Parameters:

ctx (Context) – The invocation context to invoke.

is_closed()[source]

Whether the websocket connection is closed.

Return type:

bool

await is_owner(user)[source]

This function is a coroutine.

Checks if a User or Member is the owner of this bot.

If an owner_id is not set, it is fetched automatically through the use of application_info().

Changed in version 1.3: The function also checks if the application is team-owned if owner_ids is not set.

Parameters:

user (abc.User) – The user to check for.

Returns:

Whether the user is the owner.

Return type:

bool

is_ready()[source]

Whether the client’s internal cache is ready for use.

Return type:

bool

is_ws_ratelimited()[source]

Whether the websocket is currently rate limited.

This can be useful to know when deciding whether you should query members using HTTP or via the gateway.

New in version 1.6.

Return type:

bool

property latency[source]

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

This could be referred to as the Discord WebSocket protocol latency.

Type:

float

load_extension(name, *, package=None)[source]

Loads an extension.

An extension is a python module that contains commands, cogs, or listeners.

An extension must have a global function, setup defined as the entry point on what to do when the extension is loaded. This entry point must have a single argument, the bot.

Parameters:

  • name (str) – The extension name to load. It must be dot separated like regular Python imports if accessing a sub-module. e.g. foo.test if you want to import foo/test.py.

  • package (Optional[str]) –

    The package name to resolve relative imports with. This is required when loading an extension using a relative path, e.g .foo.test. Defaults to None.

    New in version 1.7.

Raises:

  • ExtensionNotFound – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided package parameter.

  • ExtensionAlreadyLoaded – The extension is already loaded.

  • NoEntryPointError – The extension does not have a setup function.

  • ExtensionFailed – The extension or its setup function had an execution error.

load_extensions(path)[source]

Loads all extensions in a directory.

New in version 2.4.

Parameters:

path (str) – The path to search for extensions

await login(token)[source]

This function is a coroutine.

Logs in the client with the specified credentials.

Parameters:

token (str) – The authentication token. Do not prefix this token with anything as the library will do it for you.

Raises:

  • LoginFailure – The wrong credentials are passed.

  • HTTPException – An unknown HTTP related error occurred, usually when it isn’t 200 or the known incorrect credentials passing status code.

message_command_check(func)[source]

Similar to check() but for message commands.

message_command_check_once(func)[source]

Similar to check_once() but for message commands.

property message_commands[source]

A set of all message commands the bot has.

Type:

Set[InvokableMessageCommand]

await on_command_error(context, exception)[source]

This function is a coroutine.

The default command error handler provided by the bot.

This is for text commands only, and doesn’t apply to application commands.

By default this prints to sys.stderr however it could be overridden to have a different implementation.

This only fires if you do not specify any listeners for command error.

await on_error(event_method, *args, **kwargs)[source]

This function is a coroutine.

The default error handler provided by the client.

By default this prints to sys.stderr however it could be overridden to have a different implementation. Check on_error() for more details.

await on_gateway_error(event, data, shard_id, exc, /)[source]

This function is a coroutine.

The default gateway error handler provided by the client.

By default this prints to sys.stderr however it could be overridden to have a different implementation. Check on_gateway_error() for more details.

New in version 2.6.

Note

Unlike on_error(), the exception is available as the exc parameter and cannot be obtained through sys.exc_info().

await on_message_command_error(interaction, exception)[source]

This function is a coroutine.

Similar to on_slash_command_error() but for message commands.

await on_slash_command_error(interaction, exception)[source]

This function is a coroutine.

The default slash command error handler provided by the bot.

By default this prints to sys.stderr however it could be overridden to have a different implementation.

This only fires if you do not specify any listeners for slash command error.

await on_user_command_error(interaction, exception)[source]

This function is a coroutine.

Similar to on_slash_command_error() but for user commands.

property persistent_views[source]

A sequence of persistent views added to the client.

New in version 2.0.

Type:

Sequence[View]

property private_channels[source]

The private channels that the connected client is participating on.

Note

This returns only up to 128 most recent private channels due to an internal working on how Discord deals with private channels.

Type:

List[abc.PrivateChannel]

await process_app_command_autocompletion(inter)[source]

This function is a coroutine.

This function processes the application command autocompletions. Without this coroutine, none of the autocompletions will be performed.

By default, this coroutine is called inside the on_application_command_autocomplete() event. If you choose to override the on_application_command_autocomplete() event, then you should invoke this coroutine as well.

Parameters:

inter (disnake.ApplicationCommandInteraction) – The interaction to process.

await process_application_commands(interaction)[source]

This function is a coroutine.

This function processes the application commands that have been registered to the bot and other groups. Without this coroutine, none of the application commands will be triggered.

By default, this coroutine is called inside the on_application_command() event. If you choose to override the on_application_command() event, then you should invoke this coroutine as well.

Parameters:

interaction (disnake.ApplicationCommandInteraction) – The interaction to process commands for.

await process_commands(message)[source]

This function is a coroutine.

This function processes the commands that have been registered to the bot and other groups. Without this coroutine, none of the commands will be triggered.

By default, this coroutine is called inside the on_message() event. If you choose to override the on_message() event, then you should invoke this coroutine as well.

This is built using other low level tools, and is equivalent to a call to get_context() followed by a call to invoke().

This also checks if the message’s author is a bot and doesn’t call get_context() or invoke() if so.

Parameters:

message (disnake.Message) – The message to process commands for.

reload_extension(name, *, package=None)[source]

Atomically reloads an extension.

This replaces the extension with the same extension, only refreshed. This is equivalent to a unload_extension() followed by a load_extension() except done in an atomic way. That is, if an operation fails mid-reload then the bot will roll-back to the prior working state.

Parameters:

  • name (str) – The extension name to reload. It must be dot separated like regular Python imports if accessing a sub-module. e.g. foo.test if you want to import foo/test.py.

  • package (Optional[str]) –

    The package name to resolve relative imports with. This is required when reloading an extension using a relative path, e.g .foo.test. Defaults to None.

    New in version 1.7.

Raises:

  • ExtensionNotLoaded – The extension was not loaded.

  • ExtensionNotFound – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided package parameter.

  • NoEntryPointError – The extension does not have a setup function.

  • ExtensionFailed – The extension setup function had an execution error.

remove_app_command_check(func, *, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

Removes a global application command check from the bot.

This function is idempotent and will not raise an exception if the function is not in the global checks.

You must specify at least one of the bool parameters, otherwise the check won’t be removed.

Parameters:

  • func – The function to remove from the global checks.

  • call_once (bool) – Whether the function was added with call_once=True in the Bot.add_check() call or using check_once().

  • slash_commands (bool) – Whether this check was for slash commands.

  • user_commands (bool) – Whether this check was for user commands.

  • message_commands (bool) – Whether this check was for message commands.

remove_check(func, *, call_once=False)[source]

Removes a global check from the bot.

This is for text commands only, and doesn’t apply to application commands.

This function is idempotent and will not raise an exception if the function is not in the global checks.

Parameters:

  • func – The function to remove from the global checks.

  • call_once (bool) – If the function was added with call_once=True in the Bot.add_check() call or using check_once().

remove_cog(name)[source]

Removes a cog from the bot and returns it.

All registered commands and event listeners that the cog has registered will be removed as well.

If no cog is found then this method has no effect.

Parameters:

name (str) – The name of the cog to remove.

Returns:

The cog that was removed. Returns None if not found.

Return type:

Optional[Cog]

remove_command(name)[source]

Remove a Command from the internal list of commands.

This could also be used as a way to remove aliases.

Parameters:

name (str) – The name of the command to remove.

Returns:

The command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[Command]

remove_listener(func, name=...)[source]

Removes a listener from the pool of listeners.

Parameters:

  • func – The function that was used as a listener to remove.

  • name (Union[str, Event]) – The name of the event we want to remove. Defaults to func.__name__.

Raises:

TypeError – The name passed was not a string or an Event.

remove_message_command(name)[source]

Removes an InvokableMessageCommand from the internal list of message commands.

Parameters:

name (str) – The name of the message command to remove.

Returns:

The message command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[InvokableMessageCommand]

remove_slash_command(name)[source]

Removes an InvokableSlashCommand from the internal list of slash commands.

Parameters:

name (str) – The name of the slash command to remove.

Returns:

The slash command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[InvokableSlashCommand]

remove_user_command(name)[source]

Removes an InvokableUserCommand from the internal list of user commands.

Parameters:

name (str) – The name of the user command to remove.

Returns:

The user command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[InvokableUserCommand]

run(*args, **kwargs)[source]

A blocking call that abstracts away the event loop initialisation from you.

If you want more control over the event loop then this function should not be used. Use start() coroutine or connect() + login().

Roughly Equivalent to:

try:
    loop.run_until_complete(start(*args, **kwargs))
except KeyboardInterrupt:
    loop.run_until_complete(close())
    # cancel all tasks lingering
finally:
    loop.close()

Warning

This function must be the last function to call due to the fact that it is blocking. That means that registration of events or anything being called after this function call will not execute until it returns.

slash_command_check(func)[source]

Similar to check() but for slash commands.

slash_command_check_once(func)[source]

Similar to check_once() but for slash commands.

property slash_commands[source]

A set of all slash commands the bot has.

Type:

Set[InvokableSlashCommand]

await start(token, *, reconnect=True, ignore_session_start_limit=False)[source]

This function is a coroutine.

A shorthand coroutine for login() + connect().

Raises:

TypeError – An unexpected keyword argument was received.

property status[source]

The status being used upon logging on to Discord.

New in version 2.0.

Type:

Status

property stickers[source]

The stickers that the connected client has.

New in version 2.0.

Type:

List[GuildSticker]

unload_extension(name, *, package=None)[source]

Unloads an extension.

When the extension is unloaded, all commands, listeners, and cogs are removed from the bot and the module is un-imported.

The extension can provide an optional global function, teardown, to do miscellaneous clean-up if necessary. This function takes a single parameter, the bot, similar to setup from load_extension().

Parameters:

  • name (str) – The extension name to unload. It must be dot separated like regular Python imports if accessing a sub-module. e.g. foo.test if you want to import foo/test.py.

  • package (Optional[str]) –

    The package name to resolve relative imports with. This is required when unloading an extension using a relative path, e.g .foo.test. Defaults to None.

    New in version 1.7.

Raises:
property user[source]

Represents the connected client. None if not logged in.

Type:

Optional[ClientUser]

user_command_check(func)[source]

Similar to check() but for user commands.

user_command_check_once(func)[source]

Similar to check_once() but for user commands.

property user_commands[source]

A set of all user commands the bot has.

Type:

Set[InvokableUserCommand]

property users[source]

Returns a list of all the users the bot can see.

Type:

List[User]

property voice_clients[source]

Represents a list of voice connections.

These are usually VoiceClient instances.

Type:

List[VoiceProtocol]

wait_for(event, *, check=None, timeout=None)[source]

This function is a coroutine.

Waits for a WebSocket event to be dispatched.

This could be used to wait for a user to reply to a message, or to react to a message, or to edit a message in a self-contained way.

The timeout parameter is passed onto asyncio.wait_for(). By default, it does not timeout. Note that this does propagate the asyncio.TimeoutError for you in case of timeout and is provided for ease of use.

In case the event returns multiple arguments, a tuple containing those arguments is returned instead. Please check the documentation for a list of events and their parameters.

This function returns the first event that meets the requirements.

Examples

Waiting for a user reply:

@client.event
async def on_message(message):
    if message.content.startswith('$greet'):
        channel = message.channel
        await channel.send('Say hello!')

        def check(m):
            return m.content == 'hello' and m.channel == channel

        msg = await client.wait_for('message', check=check)
        await channel.send(f'Hello {msg.author}!')

# using events enums:
@client.event
async def on_message(message):
    if message.content.startswith('$greet'):
        channel = message.channel
        await channel.send('Say hello!')

        def check(m):
            return m.content == 'hello' and m.channel == channel

        msg = await client.wait_for(Event.message, check=check)
        await channel.send(f'Hello {msg.author}!')

Waiting for a thumbs up reaction from the message author:

@client.event
async def on_message(message):
    if message.content.startswith('$thumb'):
        channel = message.channel
        await channel.send('Send me that 👍 reaction, mate')

        def check(reaction, user):
            return user == message.author and str(reaction.emoji) == '👍'

        try:
            reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
        except asyncio.TimeoutError:
            await channel.send('👎')
        else:
            await channel.send('👍')
Parameters:

  • event (Union[str, Event]) – The event name, similar to the event reference, but without the on_ prefix, to wait for. It’s recommended to use Event.

  • check (Optional[Callable[…, bool]]) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for.

  • timeout (Optional[float]) – The number of seconds to wait before timing out and raising asyncio.TimeoutError.

Raises:

asyncio.TimeoutError – If a timeout is provided and it was reached.

Returns:

Returns no arguments, a single argument, or a tuple of multiple arguments that mirrors the parameters passed in the event.

Return type:

Any

await wait_until_first_connect()[source]

This function is a coroutine.

Waits until the first connect.

await wait_until_ready()[source]

This function is a coroutine.

Waits until the client’s internal cache is all ready.

for ... in walk_commands()[source]

An iterator that recursively walks through all commands and subcommands.

Changed in version 1.4: Duplicates due to aliases are no longer returned

Yields:

Union[Command, Group] – A command or group from the internal list of commands.

AutoShardedBot

class disnake.ext.commands.AutoShardedBot(command_prefix=None, help_command=<default-help-command>, description=None, *, strip_after_prefix=False, **options)[source]

Similar to Bot, except that it is inherited from disnake.AutoShardedClient instead.

InteractionBot

Attributes
Methods
class disnake.ext.commands.InteractionBot(*, command_sync_flags=None, sync_commands=..., sync_commands_debug=..., sync_commands_on_cog_unload=..., test_guilds=None, **options)[source]

Represents a discord bot for application commands only.

This class is a subclass of disnake.Client and as a result anything that you can do with a disnake.Client you can do with this bot.

This class also subclasses InteractionBotBase to provide the functionality to manage application commands.

Parameters:

  • test_guilds (List[int]) –

    The list of IDs of the guilds where you’re going to test your application commands. Defaults to None, which means global registration of commands across all guilds.

    New in version 2.1.

  • command_sync_flags (CommandSyncFlags) –

    The command sync flags for the session. This is a way of controlling when and how application commands will be synced with the Discord API. If not given, defaults to CommandSyncFlags.default().

    New in version 2.7.

  • sync_commands (bool) –

    Whether to enable automatic synchronization of application commands in your code. Defaults to True, which means that commands in API are automatically synced with the commands in your code.

    New in version 2.1.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • sync_commands_on_cog_unload (bool) –

    Whether to sync the application commands on cog unload / reload. Defaults to True.

    New in version 2.1.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • sync_commands_debug (bool) –

    Whether to always show sync debug logs (uses INFO log level if it’s enabled, prints otherwise). If disabled, uses the default DEBUG log level which isn’t shown unless the log level is changed manually. Useful for tracking the commands being registered in the API. Defaults to False.

    New in version 2.1.

    Changed in version 2.4: Changes the log level of corresponding messages from DEBUG to INFO or prints them, instead of controlling whether they are enabled at all.

    Deprecated since version 2.7: Replaced with command_sync_flags.

  • localization_provider (LocalizationProtocol) –

    An implementation of LocalizationProtocol to use for localization of application commands. If not provided, the default LocalizationStore implementation is used.

    New in version 2.5.

  • strict_localization (bool) –

    Whether to raise an exception when localizations for a specific key couldn’t be found. This is mainly useful for testing/debugging, consider disabling this eventually as missing localized names will automatically fall back to the default/base name without it. Only applicable if the localization_provider parameter is not provided. Defaults to False.

    New in version 2.5.

owner_id

The user ID that owns the bot. If this is not set and is then queried via is_owner() then it is fetched automatically using application_info().

This can be provided as a parameter at creation.

Type:

Optional[int]

owner_ids

The user IDs that owns the bot. This is similar to owner_id. If this is not set and the application is team based, then it is fetched automatically using application_info(). For performance reasons it is recommended to use a set for the collection. You cannot set both owner_id and owner_ids.

This can be provided as a parameter at creation.

Type:

Optional[Collection[int]]

reload

Whether to enable automatic extension reloading on file modification for debugging. Whenever you save an extension with reloading enabled the file will be automatically reloaded for you so you do not have to reload the extension manually. Defaults to False

This can be provided as a parameter at creation.

New in version 2.1.

Type:

bool

i18n

An implementation of LocalizationProtocol used for localization of application commands.

New in version 2.5.

Type:

LocalizationProtocol

@after_slash_command_invoke[source]

Similar to Bot.after_invoke() but for slash commands, and it takes an ApplicationCommandInteraction as its only parameter.

@after_user_command_invoke[source]

Similar to Bot.after_slash_command_invoke() but for user commands.

@after_message_command_invoke[source]

Similar to Bot.after_slash_command_invoke() but for message commands.

@before_slash_command_invoke[source]

Similar to Bot.before_invoke() but for slash commands, and it takes an ApplicationCommandInteraction as its only parameter.

@before_user_command_invoke[source]

Similar to Bot.before_slash_command_invoke() but for user commands.

@before_message_command_invoke[source]

Similar to Bot.before_slash_command_invoke() but for message commands.

@application_command_check[source]

A decorator that adds a global application command check to the bot.

A global check is similar to a check() that is applied on a per command basis except it is run before any application command checks have been verified and applies to every application command the bot has.

Note

This function can either be a regular function or a coroutine.

Similar to a command check(), this takes a single parameter of type ApplicationCommandInteraction and can only raise exceptions inherited from CommandError.

Example

@bot.application_command_check()
def check_app_commands(inter):
    return inter.channel_id in whitelisted_channels
Parameters:

  • call_once (bool) – Whether the function should only be called once per invoke call.

  • slash_commands (bool) – Whether this check is for slash commands.

  • user_commands (bool) – Whether this check is for user commands.

  • message_commands (bool) – Whether this check is for message commands.

@slash_command_check[source]

Similar to check() but for slash commands.

@user_command_check[source]

Similar to check() but for user commands.

@message_command_check[source]

Similar to check() but for message commands.

@slash_command_check_once[source]

Similar to check_once() but for slash commands.

@user_command_check_once[source]

Similar to check_once() but for user commands.

@message_command_check_once[source]

Similar to check_once() but for message commands.

@slash_command(*args, **kwargs)[source]

A shortcut decorator that invokes slash_command() and adds it to the internal command list.

Parameters:

  • name (Optional[Union[str, Localized]]) –

    The name of the slash command (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • description (Optional[Union[str, Localized]]) –

    The description of the slash command. It will be visible in Discord.

    Changed in version 2.5: Added support for localizations.

  • options (List[Option]) – The list of slash command options. The options will be visible in Discord. This is the old way of specifying options. Consider using Parameters instead.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

    The default required permissions for this command. See ApplicationCommand.default_member_permissions for details.

    New in version 2.5.

  • nsfw (bool) –

    Whether this command is age-restricted. Defaults to False.

    New in version 2.8.

  • auto_sync (bool) – Whether to automatically register the command. Defaults to True

  • guild_ids (Sequence[int]) – If specified, the client will register the command in these guilds. Otherwise, this command will be registered globally.

  • connectors (Dict[str, str]) – Binds function names to option names. If the name of an option already matches the corresponding function param, you don’t have to specify the connectors. Connectors template: {"option-name": "param_name", ...}. If you’re using Parameters, you don’t need to specify this.

  • extras (Dict[str, Any]) –

    A dict of user provided extras to attach to the command.

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

A decorator that converts the provided method into an InvokableSlashCommand, adds it to the bot, then returns it.

Return type:

Callable[…, InvokableSlashCommand]

@user_command(*args, **kwargs)[source]

A shortcut decorator that invokes user_command() and adds it to the internal command list.

Parameters:

  • name (Optional[Union[str, Localized]]) –

    The name of the user command (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

    The default required permissions for this command. See ApplicationCommand.default_member_permissions for details.

    New in version 2.5.

  • nsfw (bool) –

    Whether this command is age-restricted. Defaults to False.

    New in version 2.8.

  • auto_sync (bool) – Whether to automatically register the command. Defaults to True.

  • guild_ids (Sequence[int]) – If specified, the client will register the command in these guilds. Otherwise, this command will be registered globally.

  • extras (Dict[str, Any]) –

    A dict of user provided extras to attach to the command.

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

A decorator that converts the provided method into an InvokableUserCommand, adds it to the bot, then returns it.

Return type:

Callable[…, InvokableUserCommand]

@message_command(*args, **kwargs)[source]

A shortcut decorator that invokes message_command() and adds it to the internal command list.

Parameters:

  • name (Optional[Union[str, Localized]]) –

    The name of the message command (defaults to function name).

    Changed in version 2.5: Added support for localizations.

  • dm_permission (bool) – Whether this command can be used in DMs. Defaults to True.

  • default_member_permissions (Optional[Union[Permissions, int]]) –

    The default required permissions for this command. See ApplicationCommand.default_member_permissions for details.

    New in version 2.5.

  • nsfw (bool) –

    Whether this command is age-restricted. Defaults to False.

    New in version 2.8.

  • auto_sync (bool) – Whether to automatically register the command. Defaults to True

  • guild_ids (Sequence[int]) – If specified, the client will register the command in these guilds. Otherwise, this command will be registered globally.

  • extras (Dict[str, Any]) –

    A dict of user provided extras to attach to the command.

    Note

    This object may be copied by the library.

    New in version 2.5.

Returns:

A decorator that converts the provided method into an InvokableMessageCommand, adds it to the bot, then returns it.

Return type:

Callable[…, InvokableMessageCommand]

@event[source]

A decorator that registers an event to listen to.

You can find more info about the events in the documentation.

The events must be a coroutine, if not, TypeError is raised.

Example

@client.event
async def on_ready():
    print('Ready!')
Raises:

TypeError – The coroutine passed is not actually a coroutine.

@listen(name=None)[source]

A decorator that registers another function as an external event listener. Basically this allows you to listen to multiple events from different places e.g. such as on_ready()

The functions being listened to must be a coroutine.

Example

@bot.listen()
async def on_message(message):
    print('one')

# in some other file...

@bot.listen('on_message')
async def my_message(message):
    print('two')

# in yet another file
@bot.listen(Event.message)
async def another_message(message):
    print('three')

Would print one, two and three in an unspecified order.

Raises:

TypeError – The function being listened to is not a coroutine or a string or an Event was not passed as the name.

property activity[source]

The activity being used upon logging in.

Type:

Optional[BaseActivity]

add_app_command_check(func, *, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

Adds a global application command check to the bot.

This is the non-decorator interface to check(), check_once(), slash_command_check() and etc.

You must specify at least one of the bool parameters, otherwise the check won’t be added.

Parameters:

  • func – The function that will be used as a global check.

  • call_once (bool) – Whether the function should only be called once per invoke call.

  • slash_commands (bool) – Whether this check is for slash commands.

  • user_commands (bool) – Whether this check is for user commands.

  • message_commands (bool) – Whether this check is for message commands.

add_cog(cog, *, override=False)[source]

Adds a “cog” to the bot.

A cog is a class that has its own event listeners and commands.

Changed in version 2.0: ClientException is raised when a cog with the same name is already loaded.

Parameters:

  • cog (Cog) – The cog to register to the bot.

  • override (bool) –

    If a previously loaded cog with the same name should be ejected instead of raising an error.

    New in version 2.0.

Raises:
add_listener(func, name=...)[source]

The non decorator alternative to listen().

Parameters:

  • func (coroutine) – The function to call.

  • name (Union[str, Event]) – The name of the event to listen for. Defaults to func.__name__.

Example

async def on_ready(): pass
async def my_message(message): pass
async def another_message(message): pass

bot.add_listener(on_ready)
bot.add_listener(my_message, 'on_message')
bot.add_listener(another_message, Event.message)
Raises:

TypeError – The function is not a coroutine or a string or an Event was not passed as the name.

add_message_command(message_command)[source]

Adds an InvokableMessageCommand into the internal list of message commands.

This is usually not called, instead the message_command() or shortcut decorators are used.

Parameters:

message_command (InvokableMessageCommand) – The message command to add.

Raises:
add_slash_command(slash_command)[source]

Adds an InvokableSlashCommand into the internal list of slash commands.

This is usually not called, instead the slash_command() or shortcut decorators are used.

Parameters:

slash_command (InvokableSlashCommand) – The slash command to add.

Raises:
add_user_command(user_command)[source]

Adds an InvokableUserCommand into the internal list of user commands.

This is usually not called, instead the user_command() or shortcut decorators are used.

Parameters:

user_command (InvokableUserCommand) – The user command to add.

Raises:
add_view(view, *, message_id=None)[source]

Registers a View for persistent listening.

This method should be used for when a view is comprised of components that last longer than the lifecycle of the program.

New in version 2.0.

Parameters:

  • view (disnake.ui.View) – The view to register for dispatching.

  • message_id (Optional[int]) – The message ID that the view is attached to. This is currently used to refresh the view’s state during message update events. If not given then message update events are not propagated for the view.

Raises:

  • TypeError – A view was not passed.

  • ValueError – The view is not persistent. A persistent view has no timeout and all their components have an explicitly provided custom_id.

property allowed_mentions[source]

The allowed mention configuration.

New in version 1.4.

Type:

Optional[AllowedMentions]

property application_commands[source]

A set of all application commands the bot has.

Type:

Set[InvokableApplicationCommand]

property application_flags[source]

The client’s application flags.

New in version 2.0.

Type:

ApplicationFlags

property application_id[source]

The client’s application ID.

If this is not passed via __init__ then this is retrieved through the gateway when an event contains the data. Usually after on_connect() is called.

New in version 2.0.

Type:

Optional[int]

await application_info()[source]

This function is a coroutine.

Retrieves the bot’s application information.

Raises:

HTTPException – Retrieving the information failed somehow.

Returns:

The bot’s application information.

Return type:

AppInfo

await before_identify_hook(shard_id, *, initial=False)[source]

This function is a coroutine.

A hook that is called before IDENTIFYing a session. This is useful if you wish to have more control over the synchronization of multiple IDENTIFYing clients.

The default implementation sleeps for 5 seconds.

New in version 1.4.

Parameters:

  • shard_id (int) – The shard ID that requested being IDENTIFY’d

  • initial (bool) – Whether this IDENTIFY is the first initial IDENTIFY.

await bulk_fetch_command_permissions(guild_id)[source]

This function is a coroutine.

Retrieves a list of GuildApplicationCommandPermissions configured for the guild with the given ID.

New in version 2.1.

Parameters:

guild_id (int) – The ID of the guild to inspect.

await bulk_overwrite_global_commands(application_commands)[source]

This function is a coroutine.

Overwrites several global application commands in one API request.

New in version 2.1.

Parameters:

application_commands (List[ApplicationCommand]) – A list of application commands to insert instead of the existing commands.

Returns:

A list of registered application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await bulk_overwrite_guild_commands(guild_id, application_commands)[source]

This function is a coroutine.

Overwrites several guild application commands in one API request.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild where the application commands should be overwritten.

  • application_commands (List[ApplicationCommand]) – A list of application commands to insert instead of the existing commands.

Returns:

A list of registered application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

property cached_messages[source]

Read-only list of messages the connected client has cached.

New in version 1.1.

Type:

Sequence[Message]

await change_presence(*, activity=None, status=None)[source]

This function is a coroutine.

Changes the client’s presence.

Changed in version 2.0: Removed the afk keyword-only parameter.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Example

game = disnake.Game("with the API")
await client.change_presence(status=disnake.Status.idle, activity=game)
Parameters:

  • activity (Optional[BaseActivity]) – The activity being done. None if no currently active activity is done.

  • status (Optional[Status]) – Indicates what status to change to. If None, then Status.online is used.

Raises:

TypeError – If the activity parameter is not the proper type.

clear()[source]

Clears the internal state of the bot.

After this, the bot can be considered “re-opened”, i.e. is_closed() and is_ready() both return False along with the bot’s internal cache cleared.

await close()[source]

This function is a coroutine.

Closes the connection to Discord.

property cogs[source]

A read-only mapping of cog name to cog.

Type:

Mapping[str, Cog]

property command_sync_flags[source]

The command sync flags configured for this bot.

New in version 2.7.

Type:

CommandSyncFlags

await connect(*, reconnect=True, ignore_session_start_limit=False)[source]

This function is a coroutine.

Creates a websocket connection and lets the websocket listen to messages from Discord. This is a loop that runs the entire event system and miscellaneous aspects of the library. Control is not resumed until the WebSocket connection is terminated.

Changed in version 2.6: Added usage of SessionStartLimit when connecting to the API. Added the ignore_session_start_limit parameter.

Parameters:

  • reconnect (bool) – Whether reconnecting should be attempted, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as invalid sharding payloads or bad tokens).

  • ignore_session_start_limit (bool) –

    Whether the API provided session start limit should be ignored when connecting to the API.

    New in version 2.6.

Raises:

  • GatewayNotFound – If the gateway to connect to Discord is not found. Usually if this is thrown then there is a Discord API outage.

  • ConnectionClosed – The websocket connection has been terminated.

  • SessionStartLimitReached – If the client doesn’t have enough connects remaining in the current 24-hour window and ignore_session_start_limit is False this will be raised rather than connecting to the gateawy and Discord resetting the token. However, if ignore_session_start_limit is True, the client will connect regardless and this exception will not be raised.

await create_dm(user)[source]

This function is a coroutine.

Creates a DMChannel with the given user.

This should be rarely called, as this is done transparently for most people.

New in version 2.0.

Parameters:

user (Snowflake) – The user to create a DM with.

Returns:

The channel that was created.

Return type:

DMChannel

await create_global_command(application_command)[source]

This function is a coroutine.

Creates a global application command.

New in version 2.1.

Parameters:

application_command (ApplicationCommand) – An object representing the application command to create.

Returns:

The application command that was created.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await create_guild(*, name, icon=..., code=...)[source]

This function is a coroutine.

Creates a Guild.

See guild_builder() for a more comprehensive alternative.

Bot accounts in 10 or more guilds are not allowed to create guilds.

Note

Using this, you will not receive Guild.channels, Guild.members, Member.activity and Member.voice per Member.

Changed in version 2.5: Removed the region parameter.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:
Raises:
Returns:

The created guild. This is not the same guild that is added to cache.

Return type:

Guild

await create_guild_command(guild_id, application_command)[source]

This function is a coroutine.

Creates a guild application command.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild where the application command should be created.

  • application_command (ApplicationCommand) – The application command.

Returns:

The newly created application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await delete_global_command(command_id)[source]

This function is a coroutine.

Deletes a global application command.

New in version 2.1.

Parameters:

command_id (int) – The ID of the application command to delete.

await delete_guild_command(guild_id, command_id)[source]

This function is a coroutine.

Deletes a guild application command.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild where the applcation command should be deleted.

  • command_id (int) – The ID of the application command to delete.

await delete_invite(invite)[source]

This function is a coroutine.

Revokes an Invite, URL, or ID to an invite.

You must have manage_channels permission in the associated guild to do this.

Parameters:

invite (Union[Invite, str]) – The invite to revoke.

Raises:

  • Forbidden – You do not have permissions to revoke invites.

  • NotFound – The invite is invalid or expired.

  • HTTPException – Revoking the invite failed.

await edit_global_command(command_id, new_command)[source]

This function is a coroutine.

Edits a global application command.

New in version 2.1.

Parameters:

  • command_id (int) – The ID of the application command to edit.

  • new_command (ApplicationCommand) – An object representing the edited application command.

Returns:

The edited application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await edit_guild_command(guild_id, command_id, new_command)[source]

This function is a coroutine.

Edits a guild application command.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild where the application command should be edited.

  • command_id (int) – The ID of the application command to edit.

  • new_command (ApplicationCommand) – An object representing the edited application command.

Returns:

The newly edited application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await edit_role_connection_metadata(records)[source]

This function is a coroutine.

Edits the ApplicationRoleConnectionMetadata records for the application.

An application can have up to 5 metadata records.

Warning

This will overwrite all existing metadata records. Consider fetching them first, and constructing the new list of metadata records based off of the returned list.

New in version 2.8.

Parameters:

records (Sequence[ApplicationRoleConnectionMetadata]) – The new metadata records.

Raises:

HTTPException – Editing the metadata records failed.

Returns:

The list of newly edited metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

property emojis[source]

The emojis that the connected client has.

Type:

List[Emoji]

property extensions[source]

A read-only mapping of extension name to extension.

Type:

Mapping[str, types.ModuleType]

await fetch_channel(channel_id, /)[source]

This function is a coroutine.

Retrieves a abc.GuildChannel, abc.PrivateChannel, or Thread with the specified ID.

Note

This method is an API call. For general usage, consider get_channel() instead.

New in version 1.2.

Parameters:

channel_id (int) – The ID of the channel to retrieve.

Raises:

  • InvalidData – An unknown channel type was received from Discord.

  • HTTPException – Retrieving the channel failed.

  • NotFound – Invalid Channel ID.

  • Forbidden – You do not have permission to fetch this channel.

Returns:

The channel from the ID.

Return type:

Union[abc.GuildChannel, abc.PrivateChannel, Thread]

await fetch_command_permissions(guild_id, command_id)[source]

This function is a coroutine.

Retrieves GuildApplicationCommandPermissions for a specific application command in the guild with the given ID.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild to inspect.

  • command_id (int) –

    The ID of the application command, or the application ID to fetch application-wide permissions.

    Changed in version 2.5: Can now also fetch application-wide permissions.

Returns:

The permissions configured for the specified application command.

Return type:

GuildApplicationCommandPermissions

await fetch_global_command(command_id)[source]

This function is a coroutine.

Retrieves a global application command.

New in version 2.1.

Parameters:

command_id (int) – The ID of the command to retrieve.

Returns:

The requested application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await fetch_global_commands(*, with_localizations=True)[source]

This function is a coroutine.

Retrieves a list of global application commands.

New in version 2.1.

Parameters:

with_localizations (bool) –

Whether to include localizations in the response. Defaults to True.

New in version 2.5.

Returns:

A list of application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await fetch_guild(guild_id, /)[source]

This function is a coroutine.

Retrieves a Guild from the given ID.

Note

Using this, you will not receive Guild.channels, Guild.members, Member.activity and Member.voice per Member.

Note

This method is an API call. For general usage, consider get_guild() instead.

Parameters:

guild_id (int) – The ID of the guild to retrieve.

Raises:
Returns:

The guild from the given ID.

Return type:

Guild

await fetch_guild_command(guild_id, command_id)[source]

This function is a coroutine.

Retrieves a guild application command.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild to fetch command from.

  • command_id (int) – The ID of the application command to retrieve.

Returns:

The requested application command.

Return type:

Union[APIUserCommand, APIMessageCommand, APISlashCommand]

await fetch_guild_commands(guild_id, *, with_localizations=True)[source]

This function is a coroutine.

Retrieves a list of guild application commands.

New in version 2.1.

Parameters:

  • guild_id (int) – The ID of the guild to fetch commands from.

  • with_localizations (bool) –

    Whether to include localizations in the response. Defaults to True.

    New in version 2.5.

Returns:

A list of application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

await fetch_guild_preview(guild_id, /)[source]

This function is a coroutine.

Retrieves a GuildPreview from the given ID. Your bot does not have to be in this guild.

Note

This method may fetch any guild that has DISCOVERABLE in Guild.features, but this information can not be known ahead of time.

This will work for any guild that you are in.

Parameters:

guild_id (int) – The ID of the guild to to retrieve a preview object.

Raises:

NotFound – Retrieving the guild preview failed.

Returns:

The guild preview from the given ID.

Return type:

GuildPreview

fetch_guilds(*, limit=100, before=None, after=None)[source]

Retrieves an AsyncIterator that enables receiving your guilds.

Note

Using this, you will only receive Guild.id, Guild.name, Guild.features, Guild.icon, and Guild.banner per Guild.

Note

This method is an API call. For general usage, consider guilds instead.

Examples

Usage

async for guild in client.fetch_guilds(limit=150):
    print(guild.name)

Flattening into a list

guilds = await client.fetch_guilds(limit=150).flatten()
# guilds is now a list of Guild...

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of guilds to retrieve. If None, it retrieves every guild you have access to. Note, however, that this would make it a slow operation. Defaults to 100.

  • before (Union[abc.Snowflake, datetime.datetime]) – Retrieves guilds before this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

  • after (Union[abc.Snowflake, datetime.datetime]) – Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

Raises:

HTTPException – Retrieving the guilds failed.

Yields:

Guild – The guild with the guild data parsed.

await fetch_invite(url, *, with_counts=True, with_expiration=True, guild_scheduled_event_id=None)[source]

This function is a coroutine.

Retrieves an Invite from a discord.gg URL or ID.

Note

If the invite is for a guild you have not joined, the guild and channel attributes of the returned Invite will be PartialInviteGuild and PartialInviteChannel respectively.

Parameters:

  • url (Union[Invite, str]) – The Discord invite ID or URL (must be a discord.gg URL).

  • with_counts (bool) – Whether to include count information in the invite. This fills the Invite.approximate_member_count and Invite.approximate_presence_count fields.

  • with_expiration (bool) –

    Whether to include the expiration date of the invite. This fills the Invite.expires_at field.

    New in version 2.0.

  • guild_scheduled_event_id (int) –

    The ID of the scheduled event to include in the invite. If not provided, defaults to the event parameter in the URL if it exists, or the ID of the scheduled event contained in the provided invite object.

    New in version 2.3.

Raises:
Returns:

The invite from the URL/ID.

Return type:

Invite

await fetch_premium_sticker_packs()[source]

This function is a coroutine.

Retrieves all available premium sticker packs.

New in version 2.0.

Raises:

HTTPException – Retrieving the sticker packs failed.

Returns:

All available premium sticker packs.

Return type:

List[StickerPack]

await fetch_role_connection_metadata()[source]

This function is a coroutine.

Retrieves the ApplicationRoleConnectionMetadata records for the application.

New in version 2.8.

Raises:

HTTPException – Retrieving the metadata records failed.

Returns:

The list of metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

await fetch_stage_instance(channel_id, /)[source]

This function is a coroutine.

Retrieves a StageInstance with the given ID.

Note

This method is an API call. For general usage, consider get_stage_instance() instead.

New in version 2.0.

Parameters:

channel_id (int) – The stage channel ID.

Raises:

  • NotFound – The stage instance or channel could not be found.

  • HTTPException – Retrieving the stage instance failed.

Returns:

The stage instance from the given ID.

Return type:

StageInstance

await fetch_sticker(sticker_id, /)[source]

This function is a coroutine.

Retrieves a Sticker with the given ID.

New in version 2.0.

Parameters:

sticker_id (int) – The ID of the sticker to retrieve.

Raises:
Returns:

The sticker you requested.

Return type:

Union[StandardSticker, GuildSticker]

await fetch_template(code)[source]

This function is a coroutine.

Retrieves a Template from a discord.new URL or code.

Parameters:

code (Union[Template, str]) – The Discord Template Code or URL (must be a discord.new URL).

Raises:
Returns:

The template from the URL/code.

Return type:

Template

await fetch_user(user_id, /)[source]

This function is a coroutine.

Retrieves a User based on their ID. You do not have to share any guilds with the user to get this information, however many operations do require that you do.

Note

This method is an API call. If you have disnake.Intents.members and member cache enabled, consider get_user() instead.

Parameters:

user_id (int) – The ID of the user to retrieve.

Raises:
Returns:

The user you requested.

Return type:

User

await fetch_voice_regions(guild_id=None)[source]

Retrieves a list of VoiceRegions.

Retrieves voice regions for the user, or a guild if provided.

New in version 2.5.

Parameters:

guild_id (Optional[int]) – The guild to get regions for, if provided.

Raises:

  • HTTPException – Retrieving voice regions failed.

  • NotFound – The provided guild_id could not be found.

await fetch_webhook(webhook_id, /)[source]

This function is a coroutine.

Retrieves a Webhook with the given ID.

Parameters:

webhook_id (int) – The ID of the webhook to retrieve.

Raises:
Returns:

The webhook you requested.

Return type:

Webhook

await fetch_widget(guild_id, /)[source]

This function is a coroutine.

Retrieves a Widget for the given guild ID.

Note

The guild must have the widget enabled to get this information.

Parameters:

guild_id (int) – The ID of the guild.

Raises:
Returns:

The guild’s widget.

Return type:

Widget

for ... in get_all_channels()[source]

A generator that retrieves every abc.GuildChannel the client can ‘access’.

This is equivalent to:

for guild in client.guilds:
    for channel in guild.channels:
        yield channel

Note

Just because you receive a abc.GuildChannel does not mean that you can communicate in said channel. abc.GuildChannel.permissions_for() should be used for that.

Yields:

abc.GuildChannel – A channel the client can ‘access’.

for ... in get_all_members()[source]

Returns a generator with every Member the client can see.

This is equivalent to:

for guild in client.guilds:
    for member in guild.members:
        yield member
Yields:

Member – A member the client can see.

get_channel(id, /)[source]

Returns a channel or thread with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The returned channel or None if not found.

Return type:

Optional[Union[abc.GuildChannel, Thread, abc.PrivateChannel]]

get_cog(name)[source]

Gets the cog instance requested.

If the cog is not found, None is returned instead.

Parameters:

name (str) – The name of the cog you are requesting. This is equivalent to the name passed via keyword argument in class creation or the class name if unspecified.

Returns:

The cog that was requested. If not found, returns None.

Return type:

Optional[Cog]

get_emoji(id, /)[source]

Returns an emoji with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The custom emoji or None if not found.

Return type:

Optional[Emoji]

get_global_command(id)[source]

Returns a global application command with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The application command.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_global_command_named(name, cmd_type=None)[source]

Returns a global application command matching the given name.

Parameters:

  • name (str) – The name to look for.

  • cmd_type (ApplicationCommandType) – The type to look for. By default, no types are checked.

Returns:

The application command.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild(id, /)[source]

Returns a guild with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The guild or None if not found.

Return type:

Optional[Guild]

get_guild_application_commands(guild_id)[source]

Returns a list of all application commands in the guild with the given ID.

Parameters:

guild_id (int) – The ID to search for.

Returns:

The list of application commands.

Return type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_command(guild_id, id)[source]

Returns a guild application command with the given guild ID and application command ID.

Parameters:

  • guild_id (int) – The guild ID to search for.

  • id (int) – The command ID to search for.

Returns:

The application command.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_command_named(guild_id, name, cmd_type=None)[source]

Returns a guild application command matching the given name.

Parameters:

  • guild_id (int) – The guild ID to search for.

  • name (str) – The command name to search for.

  • cmd_type (ApplicationCommandType) – The type to look for. By default, no types are checked.

Returns:

The application command.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_guild_message_commands(guild_id)[source]

Returns a list of all message commands in the guild with the given ID.

Parameters:

guild_id (int) – The ID to search for.

Returns:

The list of message commands.

Return type:

List[APIMessageCommand]

get_guild_slash_commands(guild_id)[source]

Returns a list of all slash commands in the guild with the given ID.

Parameters:

guild_id (int) – The ID to search for.

Returns:

The list of slash commands.

Return type:

List[APISlashCommand]

get_guild_user_commands(guild_id)[source]

Returns a list of all user commands in the guild with the given ID.

Parameters:

guild_id (int) – The ID to search for.

Returns:

The list of user commands.

Return type:

List[APIUserCommand]

get_listeners()[source]

Mapping[str, List[Callable]]: A read-only mapping of event names to listeners.

Note

To add or remove a listener you should use add_listener() and remove_listener().

New in version 2.9.

get_message(id)[source]

Gets the message with the given ID from the bot’s message cache.

Parameters:

id (int) – The ID of the message to look for.

Returns:

The corresponding message.

Return type:

Optional[Message]

get_message_command(name)[source]

Gets an InvokableMessageCommand from the internal list of message commands.

Parameters:

name (str) – The name of the message command to get.

Returns:

The message command that was requested. If not found, returns None.

Return type:

Optional[InvokableMessageCommand]

await get_or_fetch_user(user_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the user from the cache. If fails, it tries to fetch the user from the API.

Parameters:

  • user_id (int) – The ID to search for.

  • strict (bool) – Whether to propagate exceptions from fetch_user() instead of returning None in case of failure (e.g. if the user wasn’t found). Defaults to False.

Returns:

The user with the given ID, or None if not found and strict is set to False.

Return type:

Optional[User]

get_partial_messageable(id, *, type=None)[source]

Returns a partial messageable with the given channel ID.

This is useful if you have a channel_id but don’t want to do an API call to send messages to it.

New in version 2.0.

Parameters:

  • id (int) – The channel ID to create a partial messageable for.

  • type (Optional[ChannelType]) – The underlying channel type for the partial messageable.

Returns:

The partial messageable

Return type:

PartialMessageable

get_slash_command(name)[source]

Works like Bot.get_command, but for slash commands.

If the name contains spaces, then it will assume that you are looking for a SubCommand or a SubCommandGroup. e.g: 'foo bar' will get the sub command group, or the sub command bar of the top-level slash command foo if found, otherwise None.

Parameters:

name (str) – The name of the slash command to get.

Raises:

TypeError – The name is not a string.

Returns:

The slash command that was requested. If not found, returns None.

Return type:

Optional[Union[InvokableSlashCommand, SubCommandGroup, SubCommand]]

get_stage_instance(id, /)[source]

Returns a stage instance with the given stage channel ID.

New in version 2.0.

Parameters:

id (int) – The ID to search for.

Returns:

The returns stage instance or None if not found.

Return type:

Optional[StageInstance]

get_sticker(id, /)[source]

Returns a guild sticker with the given ID.

New in version 2.0.

Note

To retrieve standard stickers, use fetch_sticker(). or fetch_premium_sticker_packs().

Returns:

The sticker or None if not found.

Return type:

Optional[GuildSticker]

get_user(id, /)[source]

Returns a user with the given ID.

Parameters:

id (int) – The ID to search for.

Returns:

The user or None if not found.

Return type:

Optional[User]

get_user_command(name)[source]

Gets an InvokableUserCommand from the internal list of user commands.

Parameters:

name (str) – The name of the user command to get.

Returns:

The user command that was requested. If not found, returns None.

Return type:

Optional[InvokableUserCommand]

await getch_user(user_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the user from the cache. If fails, it tries to fetch the user from the API.

Parameters:

  • user_id (int) – The ID to search for.

  • strict (bool) – Whether to propagate exceptions from fetch_user() instead of returning None in case of failure (e.g. if the user wasn’t found). Defaults to False.

Returns:

The user with the given ID, or None if not found and strict is set to False.

Return type:

Optional[User]

property global_application_commands[source]

The client’s global application commands.

Type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]

property global_message_commands[source]

The client’s global message commands.

Type:

List[APIMessageCommand]

property global_slash_commands[source]

The client’s global slash commands.

Type:

List[APISlashCommand]

property global_user_commands[source]

The client’s global user commands.

Type:

List[APIUserCommand]

guild_builder(name)[source]

Creates a builder object that can be used to create more complex guilds.

This is a more comprehensive alternative to create_guild(). See GuildBuilder for details and examples.

Bot accounts in 10 or more guilds are not allowed to create guilds.

Note

Using this, you will not receive Guild.channels, Guild.members, Member.activity and Member.voice per Member.

New in version 2.8.

Parameters:

name (str) – The name of the guild.

Returns:

The guild builder object for configuring and creating a new guild.

Return type:

GuildBuilder

property guilds[source]

The guilds that the connected client is a member of.

Type:

List[Guild]

property intents[source]

The intents configured for this connection.

New in version 1.5.

Type:

Intents

is_closed()[source]

Whether the websocket connection is closed.

Return type:

bool

await is_owner(user)[source]

This function is a coroutine.

Checks if a User or Member is the owner of this bot.

If an owner_id is not set, it is fetched automatically through the use of application_info().

Changed in version 1.3: The function also checks if the application is team-owned if owner_ids is not set.

Parameters:

user (abc.User) – The user to check for.

Returns:

Whether the user is the owner.

Return type:

bool

is_ready()[source]

Whether the client’s internal cache is ready for use.

Return type:

bool

is_ws_ratelimited()[source]

Whether the websocket is currently rate limited.

This can be useful to know when deciding whether you should query members using HTTP or via the gateway.

New in version 1.6.

Return type:

bool

property latency[source]

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

This could be referred to as the Discord WebSocket protocol latency.

Type:

float

load_extension(name, *, package=None)[source]

Loads an extension.

An extension is a python module that contains commands, cogs, or listeners.

An extension must have a global function, setup defined as the entry point on what to do when the extension is loaded. This entry point must have a single argument, the bot.

Parameters:

  • name (str) – The extension name to load. It must be dot separated like regular Python imports if accessing a sub-module. e.g. foo.test if you want to import foo/test.py.

  • package (Optional[str]) –

    The package name to resolve relative imports with. This is required when loading an extension using a relative path, e.g .foo.test. Defaults to None.

    New in version 1.7.

Raises:

  • ExtensionNotFound – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided package parameter.

  • ExtensionAlreadyLoaded – The extension is already loaded.

  • NoEntryPointError – The extension does not have a setup function.

  • ExtensionFailed – The extension or its setup function had an execution error.

load_extensions(path)[source]

Loads all extensions in a directory.

New in version 2.4.

Parameters:

path (str) – The path to search for extensions

await login(token)[source]

This function is a coroutine.

Logs in the client with the specified credentials.

Parameters:

token (str) – The authentication token. Do not prefix this token with anything as the library will do it for you.

Raises:

  • LoginFailure – The wrong credentials are passed.

  • HTTPException – An unknown HTTP related error occurred, usually when it isn’t 200 or the known incorrect credentials passing status code.

property message_commands[source]

A set of all message commands the bot has.

Type:

Set[InvokableMessageCommand]

await on_error(event_method, *args, **kwargs)[source]

This function is a coroutine.

The default error handler provided by the client.

By default this prints to sys.stderr however it could be overridden to have a different implementation. Check on_error() for more details.

await on_gateway_error(event, data, shard_id, exc, /)[source]

This function is a coroutine.

The default gateway error handler provided by the client.

By default this prints to sys.stderr however it could be overridden to have a different implementation. Check on_gateway_error() for more details.

New in version 2.6.

Note

Unlike on_error(), the exception is available as the exc parameter and cannot be obtained through sys.exc_info().

await on_message_command_error(interaction, exception)[source]

This function is a coroutine.

Similar to on_slash_command_error() but for message commands.

await on_slash_command_error(interaction, exception)[source]

This function is a coroutine.

The default slash command error handler provided by the bot.

By default this prints to sys.stderr however it could be overridden to have a different implementation.

This only fires if you do not specify any listeners for slash command error.

await on_user_command_error(interaction, exception)[source]

This function is a coroutine.

Similar to on_slash_command_error() but for user commands.

property persistent_views[source]

A sequence of persistent views added to the client.

New in version 2.0.

Type:

Sequence[View]

property private_channels[source]

The private channels that the connected client is participating on.

Note

This returns only up to 128 most recent private channels due to an internal working on how Discord deals with private channels.

Type:

List[abc.PrivateChannel]

await process_app_command_autocompletion(inter)[source]

This function is a coroutine.

This function processes the application command autocompletions. Without this coroutine, none of the autocompletions will be performed.

By default, this coroutine is called inside the on_application_command_autocomplete() event. If you choose to override the on_application_command_autocomplete() event, then you should invoke this coroutine as well.

Parameters:

inter (disnake.ApplicationCommandInteraction) – The interaction to process.

await process_application_commands(interaction)[source]

This function is a coroutine.

This function processes the application commands that have been registered to the bot and other groups. Without this coroutine, none of the application commands will be triggered.

By default, this coroutine is called inside the on_application_command() event. If you choose to override the on_application_command() event, then you should invoke this coroutine as well.

Parameters:

interaction (disnake.ApplicationCommandInteraction) – The interaction to process commands for.

reload_extension(name, *, package=None)[source]

Atomically reloads an extension.

This replaces the extension with the same extension, only refreshed. This is equivalent to a unload_extension() followed by a load_extension() except done in an atomic way. That is, if an operation fails mid-reload then the bot will roll-back to the prior working state.

Parameters:

  • name (str) – The extension name to reload. It must be dot separated like regular Python imports if accessing a sub-module. e.g. foo.test if you want to import foo/test.py.

  • package (Optional[str]) –

    The package name to resolve relative imports with. This is required when reloading an extension using a relative path, e.g .foo.test. Defaults to None.

    New in version 1.7.

Raises:

  • ExtensionNotLoaded – The extension was not loaded.

  • ExtensionNotFound – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided package parameter.

  • NoEntryPointError – The extension does not have a setup function.

  • ExtensionFailed – The extension setup function had an execution error.

remove_app_command_check(func, *, call_once=False, slash_commands=False, user_commands=False, message_commands=False)[source]

Removes a global application command check from the bot.

This function is idempotent and will not raise an exception if the function is not in the global checks.

You must specify at least one of the bool parameters, otherwise the check won’t be removed.

Parameters:

  • func – The function to remove from the global checks.

  • call_once (bool) – Whether the function was added with call_once=True in the Bot.add_check() call or using check_once().

  • slash_commands (bool) – Whether this check was for slash commands.

  • user_commands (bool) – Whether this check was for user commands.

  • message_commands (bool) – Whether this check was for message commands.

remove_cog(name)[source]

Removes a cog from the bot and returns it.

All registered commands and event listeners that the cog has registered will be removed as well.

If no cog is found then this method has no effect.

Parameters:

name (str) – The name of the cog to remove.

Returns:

The cog that was removed. Returns None if not found.

Return type:

Optional[Cog]

remove_listener(func, name=...)[source]

Removes a listener from the pool of listeners.

Parameters:

  • func – The function that was used as a listener to remove.

  • name (Union[str, Event]) – The name of the event we want to remove. Defaults to func.__name__.

Raises:

TypeError – The name passed was not a string or an Event.

remove_message_command(name)[source]

Removes an InvokableMessageCommand from the internal list of message commands.

Parameters:

name (str) – The name of the message command to remove.

Returns:

The message command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[InvokableMessageCommand]

remove_slash_command(name)[source]

Removes an InvokableSlashCommand from the internal list of slash commands.

Parameters:

name (str) – The name of the slash command to remove.

Returns:

The slash command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[InvokableSlashCommand]

remove_user_command(name)[source]

Removes an InvokableUserCommand from the internal list of user commands.

Parameters:

name (str) – The name of the user command to remove.

Returns:

The user command that was removed. If the name is not valid then None is returned instead.

Return type:

Optional[InvokableUserCommand]

run(*args, **kwargs)[source]

A blocking call that abstracts away the event loop initialisation from you.

If you want more control over the event loop then this function should not be used. Use start() coroutine or connect() + login().

Roughly Equivalent to:

try:
    loop.run_until_complete(start(*args, **kwargs))
except KeyboardInterrupt:
    loop.run_until_complete(close())
    # cancel all tasks lingering
finally:
    loop.close()

Warning

This function must be the last function to call due to the fact that it is blocking. That means that registration of events or anything being called after this function call will not execute until it returns.

property slash_commands[source]

A set of all slash commands the bot has.

Type:

Set[InvokableSlashCommand]

await start(token, *, reconnect=True, ignore_session_start_limit=False)[source]

This function is a coroutine.

A shorthand coroutine for login() + connect().

Raises:

TypeError – An unexpected keyword argument was received.

property status[source]

The status being used upon logging on to Discord.

New in version 2.0.

Type:

Status

property stickers[source]

The stickers that the connected client has.

New in version 2.0.

Type:

List[GuildSticker]

unload_extension(name, *, package=None)[source]

Unloads an extension.

When the extension is unloaded, all commands, listeners, and cogs are removed from the bot and the module is un-imported.

The extension can provide an optional global function, teardown, to do miscellaneous clean-up if necessary. This function takes a single parameter, the bot, similar to setup from load_extension().

Parameters:

  • name (str) – The extension name to unload. It must be dot separated like regular Python imports if accessing a sub-module. e.g. foo.test if you want to import foo/test.py.

  • package (Optional[str]) –

    The package name to resolve relative imports with. This is required when unloading an extension using a relative path, e.g .foo.test. Defaults to None.

    New in version 1.7.

Raises:
property user[source]

Represents the connected client. None if not logged in.

Type:

Optional[ClientUser]

property user_commands[source]

A set of all user commands the bot has.

Type:

Set[InvokableUserCommand]

property users[source]

Returns a list of all the users the bot can see.

Type:

List[User]

property voice_clients[source]

Represents a list of voice connections.

These are usually VoiceClient instances.

Type:

List[VoiceProtocol]

wait_for(event, *, check=None, timeout=None)[source]

This function is a coroutine.

Waits for a WebSocket event to be dispatched.

This could be used to wait for a user to reply to a message, or to react to a message, or to edit a message in a self-contained way.

The timeout parameter is passed onto asyncio.wait_for(). By default, it does not timeout. Note that this does propagate the asyncio.TimeoutError for you in case of timeout and is provided for ease of use.

In case the event returns multiple arguments, a tuple containing those arguments is returned instead. Please check the documentation for a list of events and their parameters.

This function returns the first event that meets the requirements.

Examples

Waiting for a user reply:

@client.event
async def on_message(message):
    if message.content.startswith('$greet'):
        channel = message.channel
        await channel.send('Say hello!')

        def check(m):
            return m.content == 'hello' and m.channel == channel

        msg = await client.wait_for('message', check=check)
        await channel.send(f'Hello {msg.author}!')

# using events enums:
@client.event
async def on_message(message):
    if message.content.startswith('$greet'):
        channel = message.channel
        await channel.send('Say hello!')

        def check(m):
            return m.content == 'hello' and m.channel == channel

        msg = await client.wait_for(Event.message, check=check)
        await channel.send(f'Hello {msg.author}!')

Waiting for a thumbs up reaction from the message author:

@client.event
async def on_message(message):
    if message.content.startswith('$thumb'):
        channel = message.channel
        await channel.send('Send me that 👍 reaction, mate')

        def check(reaction, user):
            return user == message.author and str(reaction.emoji) == '👍'

        try:
            reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
        except asyncio.TimeoutError:
            await channel.send('👎')
        else:
            await channel.send('👍')
Parameters:

  • event (Union[str, Event]) – The event name, similar to the event reference, but without the on_ prefix, to wait for. It’s recommended to use Event.

  • check (Optional[Callable[…, bool]]) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for.

  • timeout (Optional[float]) – The number of seconds to wait before timing out and raising asyncio.TimeoutError.

Raises:

asyncio.TimeoutError – If a timeout is provided and it was reached.

Returns:

Returns no arguments, a single argument, or a tuple of multiple arguments that mirrors the parameters passed in the event.

Return type:

Any

await wait_until_first_connect()[source]

This function is a coroutine.

Waits until the first connect.

await wait_until_ready()[source]

This function is a coroutine.

Waits until the client’s internal cache is all ready.

AutoShardedInteractionBot

class disnake.ext.commands.AutoShardedInteractionBot(*, command_sync_flags=None, sync_commands=..., sync_commands_debug=..., sync_commands_on_cog_unload=..., test_guilds=None, **options)[source]

Similar to InteractionBot, except that it is inherited from disnake.AutoShardedClient instead.