Client Objects#

Bots#

Attributes
Methods
class discord.Bot(description=None, *args, **options)[source]#

Represents a discord bot.

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

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

New in version 2.0.

description#

The content prefixed into the default help message.

Type:

str

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().

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.

New in version 1.3.

Type:

Optional[Collection[int]]

debug_guilds#

Guild IDs of guilds to use for testing commands. The bot will not create any global commands if debug guild IDs are passed.

New in version 2.0.

Type:

Optional[List[int]]

auto_sync_commands#

Whether to automatically sync slash commands. This will call sync_commands() in discord.on_connect(), and in process_application_commands if the command is not found. Defaults to True.

New in version 2.0.

Type:

bool

@command(**kwargs)#

An alias for application_command().

Note

This decorator is overridden by discord.ext.commands.Bot.

New in version 2.0.

Returns:

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

Return type:

Callable[…, ApplicationCommand]

@event(coro)#

A decorator that registers an event to listen to.

You can find more info about the events on the documentation below.

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

Note

This replaces any default handlers. Developers are encouraged to use listen() for adding additional handlers instead of event() unless default method replacement is intended.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

Example

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

coro (TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])) –

Return type:

TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])

@message_command(**kwargs)#

A shortcut decorator that invokes command() and adds it to the internal command list via add_application_command(). This shortcut is made specifically for MessageCommand.

New in version 2.0.

Returns:

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

Return type:

Callable[…, MessageCommand]

@slash_command(**kwargs)#

A shortcut decorator that invokes command() and adds it to the internal command list via add_application_command(). This shortcut is made specifically for SlashCommand.

New in version 2.0.

Returns:

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

Return type:

Callable[…, SlashCommand]

@user_command(**kwargs)#

A shortcut decorator that invokes command() and adds it to the internal command list via add_application_command(). This shortcut is made specifically for UserCommand.

New in version 2.0.

Returns:

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

Return type:

Callable[…, UserCommand]

@listen(name=..., once=False)#

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.

Raises:

  • TypeError – The function being listened to is not a coroutine.

  • ValueError – The name (event name) does not start with ‘on_’

Example

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

# in some other file...

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

# listen to the first event only
@client.listen('on_ready', once=True)
async def on_ready():
    print('ready!')

Would print one and two in an unspecified order.

Parameters:
Return type:

Callable[[TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])], TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])]

property activity#

The activity being used upon logging in.

Return type:

Optional[BaseActivity]

add_application_command(command)#

Adds a ApplicationCommand into the internal list of commands.

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

New in version 2.0.

Parameters:

command (ApplicationCommand) – The command to add.

Return type:

None

add_check(func, *, call_once=False)#

Adds a global check to the bot. 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 Bot.invoke() call.

Return type:

None

add_cog(cog, *, override=False)#

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:
Return type:

None

add_listener(func, name=...)#

The non decorator alternative to listen().

Parameters:

  • func (coroutine) – The function to call.

  • name (str) – The name of the event to listen for. Defaults to func.__name__.

Raises:

  • TypeError – The func parameter is not a coroutine function.

  • ValueError – The name (event name) does not start with ‘on_’

Return type:

None

Example

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

client.add_listener(on_ready)
client.add_listener(my_message, 'on_message')
add_view(view, *, message_id=None)#

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 (discord.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.

Return type:

None

after_invoke(coro)#

A decorator that registers a coroutine as a post-invoke hook. A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required. This post-invoke hook takes a sole parameter, 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.

property allowed_mentions#

The allowed mention configuration.

New in version 1.4.

application_command(**kwargs)#

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

New in version 2.0.

Returns:

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

Return type:

Callable[…, ApplicationCommand]

property application_flags#

The client’s application flags.

New in version 2.0.

property application_id#

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.

await application_info()#

This function is a coroutine.

Retrieves the bot’s application information.

Returns:

The bot’s application information.

Return type:

AppInfo

Raises:

HTTPException – Retrieving the information failed somehow.

await before_identify_hook(shard_id, *, initial=False)#

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.

Return type:

None

before_invoke(coro)#

A decorator that registers a coroutine as a pre-invoke hook. A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required. This pre-invoke hook takes a sole parameter, 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.

property cached_messages#

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

New in version 1.1.

await change_presence(*, activity=None, status=None)#

This function is a coroutine.

Changes the client’s presence.

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:

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

Example

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

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

check(func)#

A decorator that adds a global 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 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 ApplicationCommandError.

Example

@bot.check
def check_commands(ctx):
    return ctx.command.qualified_name in allowed_commands
check_once(func)#

A decorator that adds a “call once” global check to the bot. Unlike regular global checks, this one is called only once per Bot.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 ApplicationCommandError.

Example

@bot.check_once
def whitelist(ctx):
    return ctx.message.author.id in my_whitelist
clear()#

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.

Return type:

None

await close()#

This function is a coroutine.

Closes the connection to Discord.

Return type:

None

property cogs#

A read-only mapping of cog name to cog.

await connect(*, reconnect=True)#

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.

Parameters:

reconnect (bool) – If we should attempt reconnecting, 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).

Raises:

  • GatewayNotFound – 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.

Return type:

None

await create_dm(user)#

This function is a coroutine.

Creates a DMChannel with this 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

create_group(name, description=None, guild_ids=None, **kwargs)#

A shortcut method that creates a slash command group with no subcommands and adds it to the internal command list via add_application_command().

New in version 2.0.

Parameters:

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

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

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

  • kwargs – Any additional keyword arguments to pass to SlashCommandGroup.

Returns:

The slash command group that was created.

Return type:

SlashCommandGroup

await create_guild(*, name, icon=..., code=...)#

This function is a coroutine.

Creates a Guild.

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

Parameters:

  • name (str) – The name of the guild.

  • icon (Optional[bytes]) – The bytes-like object representing the icon. See ClientUser.edit() for more details on what is expected.

  • code (str) –

    The code for a template to create the guild with.

    New in version 1.4.

Returns:

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

Return type:

Guild

Raises:
await delete_invite(invite)#

This function is a coroutine.

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

You must have the 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.

Return type:

None

property emojis#

The emojis that the connected client has.

property extensions#

A read-only mapping of extension name to extension.

await fetch_application(application_id, /)#

This function is a coroutine. Retrieves a PartialAppInfo from an application ID.

Parameters:

application_id (int) – The application ID to retrieve information from.

Returns:

The application information.

Return type:

PartialAppInfo

Raises:

  • NotFound – An application with this ID does not exist.

  • HTTPException – Retrieving the application failed.

await fetch_channel(channel_id, /)#

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.

Returns:

The channel from the ID.

Return type:

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

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.

Parameters:

channel_id (int) –

await fetch_entitlements()#

This function is a coroutine.

Fetches the bot’s entitlements.

New in version 2.5.

Returns:

The bot’s entitlements.

Return type:

List[Entitlement]

await fetch_guild(guild_id, /, *, with_counts=True)#

This function is a coroutine.

Retrieves a Guild from an 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:
Returns:

The guild from the ID.

Return type:

Guild

Raises:
fetch_guilds(*, limit=100, before=None, after=None)#

Retrieves an AsyncIterator that enables receiving your guilds.

Note

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

Note

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

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.

Yields:

Guild – The guild with the guild data parsed.

Raises:

HTTPException – Getting the guilds failed.

Return type:

GuildIterator

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.

await fetch_invite(url, *, with_counts=True, with_expiration=True, event_id=None)#

This function is a coroutine.

Gets 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:
Returns:

The invite from the URL/ID.

Return type:

Invite

Raises:
await fetch_premium_sticker_packs()#

This function is a coroutine.

Retrieves all available premium sticker packs.

New in version 2.0.

Returns:

All available premium sticker packs.

Return type:

List[StickerPack]

Raises:

HTTPException – Retrieving the sticker packs failed.

await fetch_role_connection_metadata_records()#

This function is a coroutine.

Fetches the bot’s role connection metadata records.

New in version 2.4.

Returns:

The bot’s role connection metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

await fetch_skus()#

This function is a coroutine.

Fetches the bot’s SKUs.

New in version 2.5.

Returns:

The bot’s SKUs.

Return type:

List[SKU]

await fetch_stage_instance(channel_id, /)#

This function is a coroutine.

Gets a StageInstance for a stage channel id.

New in version 2.0.

Parameters:

channel_id (int) – The stage channel ID.

Returns:

The stage instance from the stage channel ID.

Return type:

StageInstance

Raises:

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

  • HTTPException – Getting the stage instance failed.

await fetch_sticker(sticker_id, /)#

This function is a coroutine.

Retrieves a Sticker with the specified ID.

New in version 2.0.

Returns:

The sticker you requested.

Return type:

Union[StandardSticker, GuildSticker]

Raises:
Parameters:

sticker_id (int) –

await fetch_template(code)#

This function is a coroutine.

Gets 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).

Returns:

The template from the URL/code.

Return type:

Template

Raises:
await fetch_user(user_id, /)#

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 discord.Intents.members and member cache enabled, consider get_user() instead.

Parameters:

user_id (int) – The user’s ID to fetch from.

Returns:

The user you requested.

Return type:

User

Raises:
await fetch_webhook(webhook_id, /)#

This function is a coroutine.

Retrieves a Webhook with the specified ID.

Returns:

The webhook you requested.

Return type:

Webhook

Raises:
Parameters:

webhook_id (int) –

await fetch_widget(guild_id, /)#

This function is a coroutine.

Gets a Widget from a guild ID.

Note

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

Parameters:

guild_id (int) – The ID of the guild.

Returns:

The guild’s widget.

Return type:

Widget

Raises:
for ... in get_all_channels()#

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
Return type:

Generator[GuildChannel, None, None]

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()#

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.

Return type:

Generator[Member, None, None]

get_application_command(name, guild_ids=None, type=<class 'discord.commands.core.ApplicationCommand'>)#

Get a ApplicationCommand from the internal list of commands.

New in version 2.0.

Parameters:

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

  • guild_ids (List[int]) – The guild ids associated to the command to get.

  • type (Type[ApplicationCommand]) – The type of the command to get. Defaults to ApplicationCommand.

Returns:

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

Return type:

Optional[ApplicationCommand]

await get_application_context(interaction, cls=<class 'discord.commands.context.ApplicationContext'>)#

This function is a coroutine.

Returns the invocation context from the interaction.

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

Parameters:

  • interaction (discord.Interaction) – The interaction to get the invocation context from.

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

Returns:

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

Return type:

ApplicationContext

await get_autocomplete_context(interaction, cls=<class 'discord.commands.context.AutocompleteContext'>)#

This function is a coroutine.

Returns the autocomplete context from the interaction.

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

Parameters:

  • interaction (discord.Interaction) – The interaction to get the invocation context from.

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

Returns:

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

Return type:

AutocompleteContext

get_channel(id, /)#

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)#

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]

property get_command#

Shortcut for get_application_command().

Note

Overridden in ext.commands.Bot.

New in version 2.0.

await get_desynced_commands(guild_id=None, prefetched=None)#

This function is a coroutine.

Gets the list of commands that are desynced from discord. If guild_id is specified, it will only return guild commands that are desynced from said guild, else it will return global commands.

Note

This function is meant to be used internally, and should only be used if you want to override the default command registration behavior.

New in version 2.0.

Parameters:

  • guild_id (Optional[int]) – The guild id to get the desynced commands for, else global commands if unspecified.

  • prefetched (Optional[List[ApplicationCommand]]) – If you already fetched the commands, you can pass them here to be used. Not recommended for typical usage.

Returns:

A list of the desynced commands. Each will come with at least the cmd and action keys, which respectively contain the command and the action to perform. Other keys may also be present depending on the action, including id.

Return type:

List[Dict[str, Any]]

get_emoji(id, /)#

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_guild(id, /)#

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_message(id, /)#

Returns a message the given ID.

This is useful if you have a message_id but don’t want to do an API call to access the message.

Parameters:

id (int) – The ID to search for.

Returns:

The returned message or None if not found.

Return type:

Optional[Message]

await get_or_fetch_user(id, /)#

This function is a coroutine.

Looks up a user in the user cache or fetches if not found.

Parameters:

id (int) – The ID to search for.

Returns:

The user or None if not found.

Return type:

Optional[User]

get_partial_messageable(id, *, type=None)#

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_stage_instance(id, /)#

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 stage instance or None if not found.

Return type:

Optional[StageInstance]

get_sticker(id, /)#

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]

Parameters:

id (int) –

get_user(id, /)#

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]

group(name=None, description=None, guild_ids=None)#

A shortcut decorator that initializes the provided subclass of SlashCommandGroup and adds it to the internal command list via add_application_command().

New in version 2.0.

Parameters:

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

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

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

Returns:

The slash command group that was created.

Return type:

Callable[[Type[SlashCommandGroup]], SlashCommandGroup]

property guilds#

The guilds that the connected client is a member of.

property intents#

The intents configured for this connection.

New in version 1.5.

await invoke_application_command(ctx)#

This function is a coroutine.

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

Parameters:

ctx (ApplicationCommand) – The invocation context to invoke.

Return type:

None

is_closed()#

Indicates if the WebSocket connection is closed.

Return type:

bool

await is_owner(user)#

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()#

Specifies if the client’s internal cache is ready for use.

Return type:

bool

is_ws_ratelimited()#

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. :rtype: bool

New in version 1.6.

property latency#

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

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

load_extension(name, *, package=None, recursive=False, store=False)#

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.

The extension passed can either be the direct name of a file within the current working directory or a folder that contains multiple extensions.

Parameters:

  • name (str) – The extension or folder name to load. It must be dot separated like regular Python imports if accessing a submodule. 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.

  • recursive (Optional[bool]) –

    If subdirectories under the given head directory should be recursively loaded. Defaults to False.

    New in version 2.0.

  • store (Optional[bool]) –

    If exceptions should be stored or raised. If set to True, all exceptions encountered will be stored in a returned dictionary as a load status. If set to False, if any exceptions are encountered they will be raised and the bot will be closed. If no exceptions are encountered, a list of loaded extension names will be returned. Defaults to False.

    New in version 2.0.

Returns:

If the store parameter is set to True, a dictionary will be returned that contains keys to represent the loaded extension names. The values bound to each key can either be an exception that occurred when loading that extension or a True boolean representing a successful load. If the store parameter is set to False, either a list containing a list of loaded extensions or nothing due to an encountered exception.

Return type:

Optional[Union[Dict[str, Union[errors.ExtensionError, bool]], List[str]]]

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(*names, package=None, recursive=False, store=False)#

Loads multiple extensions at once.

This method simplifies the process of loading multiple extensions by handling the looping of load_extension.

Parameters:

  • names (str) – The extension or folder names to load. It must be dot separated like regular Python imports if accessing a submodule. 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.

  • recursive (Optional[bool]) –

    If subdirectories under the given head directory should be recursively loaded. Defaults to False.

    New in version 2.0.

  • store (Optional[bool]) –

    If exceptions should be stored or raised. If set to True, all exceptions encountered will be stored in a returned dictionary as a load status. If set to False, if any exceptions are encountered they will be raised and the bot will be closed. If no exceptions are encountered, a list of loaded extension names will be returned. Defaults to False.

    New in version 2.0.

Returns:

If the store parameter is set to True, a dictionary will be returned that contains keys to represent the loaded extension names. The values bound to each key can either be an exception that occurred when loading that extension or a True boolean representing a successful load. If the store parameter is set to False, either a list containing names of loaded extensions or nothing due to an encountered exception.

Return type:

Optional[Union[Dict[str, Union[errors.ExtensionError, bool]], List[str]]]

Raises:

  • ExtensionNotFound – A given 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 – A given extension is already loaded.

  • NoEntryPointError – A given extension does not have a setup function.

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

await login(token)#

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:

  • TypeError – The token was in invalid type.

  • 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.

Return type:

None

await on_application_command_error(context, exception)#

This function is a coroutine.

The default 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 command error.

Parameters:
Return type:

None

await on_error(event_method, *args, **kwargs)#

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.

Parameters:

  • event_method (str) –

  • args (Any) –

  • kwargs (Any) –

Return type:

None

property persistent_views#

A sequence of persistent views added to the client.

New in version 2.0.

property private_channels#

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.

await process_application_commands(interaction, auto_sync=None)#

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_interaction() event. If you choose to override the on_interaction() event, then you should invoke this coroutine as well.

This function finds a registered command matching the interaction id from application commands and invokes it. If no matching command was found, it replies to the interaction with a default message.

New in version 2.0.

Parameters:

  • interaction (discord.Interaction) – The interaction to process

  • auto_sync (Optional[bool]) – Whether to automatically sync and unregister the command if it is not found in the internal cache. This will invoke the sync_commands() method on the context of the command, either globally or per-guild, based on the type of the command, respectively. Defaults to Bot.auto_sync_commands.

Return type:

None

await register_command(command, force=True, guild_ids=None)#

This function is a coroutine.

Registers a command. If the command has guild_ids set, or if the guild_ids parameter is passed, the command will be registered as a guild command for those guilds.

Parameters:

  • command (ApplicationCommand) – The command to register.

  • force (bool) – Whether to force the command to be registered. If this is set to False, the command will only be registered if it seems to already be registered and up to date with our internal cache. Defaults to True.

  • guild_ids (list) – A list of guild ids to register the command for. If this is not set, the command’s ApplicationCommand.guild_ids attribute will be used.

Returns:

The command that was registered

Return type:

ApplicationCommand

await register_commands(commands=None, guild_id=None, method='bulk', force=False, delete_existing=True)#

This function is a coroutine.

Register a list of commands.

New in version 2.0.

Parameters:

  • commands (Optional[List[ApplicationCommand]]) – A list of commands to register. If this is not set (None), then all commands will be registered.

  • guild_id (Optional[int]) – If this is set, the commands will be registered as a guild command for the respective guild. If it is not set, the commands will be registered according to their ApplicationCommand.guild_ids attribute.

  • method (Literal['individual', 'bulk', 'auto']) – The method to use when registering the commands. If this is set to “individual”, then each command will be registered individually. If this is set to “bulk”, then all commands will be registered in bulk. If this is set to “auto”, then the method will be determined automatically. Defaults to “bulk”.

  • force (bool) – Registers the commands regardless of the state of the command on Discord. This uses one less API call, but can result in hitting rate limits more often. Defaults to False.

  • delete_existing (bool) – Whether to delete existing commands that are not in the list of commands to register. Defaults to True.

reload_extension(name, *, package=None)#

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 submodule. 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.

Return type:

None

remove_application_command(command)#

Remove a ApplicationCommand from the internal list of commands.

New in version 2.0.

Parameters:

command (ApplicationCommand) – The command to remove.

Returns:

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

Return type:

Optional[ApplicationCommand]

remove_check(func, *, call_once=False)#

Removes a global check from the bot. 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().

Return type:

None

remove_cog(name)#

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. None if not found.

Return type:

Optional[Cog]

remove_listener(func, name=...)#

Removes a listener from the pool of listeners.

Parameters:

  • func (TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])) – The function that was used as a listener to remove.

  • name (str) – The name of the event we want to remove. Defaults to func.__name__.

Return type:

None

run(*args, **kwargs)#

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.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

None

slash_group(name=None, description=None, guild_ids=None)#

A shortcut decorator that initializes the provided subclass of SlashCommandGroup and adds it to the internal command list via add_application_command().

New in version 2.0.

Parameters:

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

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

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

Returns:

The slash command group that was created.

Return type:

Callable[[Type[SlashCommandGroup]], SlashCommandGroup]

await start(token, *, reconnect=True)#

This function is a coroutine.

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

Raises:

TypeError – An unexpected keyword argument was received.

Parameters:

  • token (str) –

  • reconnect (bool) –

Return type:

None

property status#

The status being used upon logging on to Discord.

property stickers#

The stickers that the connected client has.

New in version 2.0.

await sync_commands(commands=None, method='bulk', force=False, guild_ids=None, register_guild_commands=True, check_guilds=[], delete_existing=True)#

This function is a coroutine.

Registers all commands that have been added through add_application_command(). This method cleans up all commands over the API and should sync them with the internal cache of commands. It attempts to register the commands in the most efficient way possible, unless force is set to True, in which case it will always register all commands.

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

@bot.event
async def on_connect():
    if bot.auto_sync_commands:
        await bot.sync_commands()
    print(f"{bot.user.name} connected.")

Note

If you remove all guild commands from a particular guild, the library may not be able to detect and update the commands accordingly, as it would have to individually check for each guild. To force the library to unregister a guild’s commands, call this function with commands=[] and guild_ids=[guild_id].

New in version 2.0.

Parameters:

  • commands (Optional[List[ApplicationCommand]]) – A list of commands to register. If this is not set (None), then all commands will be registered.

  • method (Literal['individual', 'bulk', 'auto']) – The method to use when registering the commands. If this is set to “individual”, then each command will be registered individually. If this is set to “bulk”, then all commands will be registered in bulk. If this is set to “auto”, then the method will be determined automatically. Defaults to “bulk”.

  • force (bool) – Registers the commands regardless of the state of the command on Discord. This uses one less API call, but can result in hitting rate limits more often. Defaults to False.

  • guild_ids (Optional[List[int]]) – A list of guild ids to register the commands for. If this is not set, the commands’ guild_ids attribute will be used.

  • register_guild_commands (bool) – Whether to register guild commands. Defaults to True.

  • check_guilds (Optional[List[int]]) – A list of guilds ids to check for commands to unregister, since the bot would otherwise have to check all guilds. Unlike guild_ids, this does not alter the commands’ guild_ids attribute, instead it adds the guild ids to a list of guilds to sync commands for. If register_guild_commands is set to False, then this parameter is ignored.

  • delete_existing (bool) – Whether to delete existing commands that are not in the list of commands to register. Defaults to True.

unload_extension(name, *, package=None)#

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 submodule. 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:
Return type:

None

await update_role_connection_metadata_records(*role_connection_metadata)#

This function is a coroutine.

Updates the bot’s role connection metadata records.

New in version 2.4.

Parameters:

*role_connection_metadata (ApplicationRoleConnectionMetadata) – The new metadata records to send to Discord.

Returns:

The updated role connection metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

property user#

Represents the connected client. None if not logged in.

property users#

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

property voice_clients#

Represents a list of voice connections.

These are usually VoiceClient instances.

wait_for(event, *, check=None, timeout=None)#

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.

Parameters:

  • event (str) – The event name, similar to the event reference, but without the on_ prefix, to wait for.

  • 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.

Returns:

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

Return type:

Any

Raises:

asyncio.TimeoutError – Raised if a timeout is provided and reached.

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}!')

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('👍')
await wait_until_ready()#

This function is a coroutine.

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

Return type:

None

for ... in walk_application_commands()#

An iterator that recursively walks through all application commands and subcommands.

Yields:

ApplicationCommand – An application command from the internal list of application commands.

Return type:

Generator[ApplicationCommand, None, None]

class discord.AutoShardedBot(description=None, *args, **options)[source]#

This is similar to Bot except that it is inherited from discord.AutoShardedClient instead.

New in version 2.0.

Clients#

Attributes
Methods
class discord.Client(*, loop=None, **options)[source]#

Represents a client connection that connects to Discord. This class is used to interact with the Discord WebSocket and API.

A number of options can be passed to the Client.

Parameters:

  • max_messages (Optional[int]) –

    The maximum number of messages to store in the internal message cache. This defaults to 1000. Passing in None disables the message cache.

    Changed in version 1.3: Allow disabling the message cache and change the default size to 1000.

  • loop (Optional[asyncio.AbstractEventLoop]) – The asyncio.AbstractEventLoop to use for asynchronous operations. Defaults to None, in which case the default event loop is used via asyncio.get_event_loop().

  • connector (Optional[aiohttp.BaseConnector]) – The connector to use for connection pooling.

  • proxy (Optional[str]) – Proxy URL.

  • proxy_auth (Optional[aiohttp.BasicAuth]) – An object that represents proxy HTTP Basic Authorization.

  • shard_id (Optional[int]) – Integer starting at 0 and less than shard_count.

  • shard_count (Optional[int]) – The total number of shards.

  • application_id (int) – The client’s application ID.

  • intents (Intents) –

    The intents that you want to enable for the session. This is a way of disabling and enabling certain gateway events from triggering and being sent. If not given, defaults to a regularly constructed Intents class.

    New in version 1.5.

  • member_cache_flags (MemberCacheFlags) –

    Allows for finer control over how the library caches members. If not given, defaults to cache as much as possible with the currently selected intents.

    New in version 1.5.

  • chunk_guilds_at_startup (bool) –

    Indicates if on_ready() should be delayed to chunk all guilds at start-up if necessary. This operation is incredibly slow for large amounts of guilds. The default is True if Intents.members is True.

    New in version 1.5.

  • status (Optional[Status]) – A status to start your presence with upon logging on to Discord.

  • activity (Optional[BaseActivity]) – An activity to start your presence with upon logging on to Discord.

  • allowed_mentions (Optional[AllowedMentions]) –

    Control how the client handles mentions by default on every message sent.

    New in version 1.4.

  • heartbeat_timeout (float) – The maximum numbers of seconds before timing out and restarting the WebSocket in the case of not receiving a HEARTBEAT_ACK. Useful if processing the initial packets take too long to the point of disconnecting you. The default timeout is 60 seconds.

  • guild_ready_timeout (float) –

    The maximum number of seconds to wait for the GUILD_CREATE stream to end before preparing the member cache and firing READY. The default timeout is 2 seconds.

    New in version 1.4.

  • assume_unsync_clock (bool) –

    Whether to assume the system clock is unsynced. This applies to the ratelimit handling code. If this is set to True, the default, then the library uses the time to reset a rate limit bucket given by Discord. If this is False then your system clock is used to calculate how long to sleep for. If this is set to False it is recommended to sync your system clock to Google’s NTP server.

    New in version 1.3.

  • enable_debug_events (bool) –

    Whether to enable events that are useful only for debugging gateway related information.

    Right now this involves on_socket_raw_receive() and on_socket_raw_send(). If this is False then those events will not be dispatched (due to performance considerations). To enable these events, this must be set to True. Defaults to False.

    New in version 2.0.

ws#

The WebSocket gateway the client is currently connected to. Could be None.

loop#

The event loop that the client uses for asynchronous operations.

Type:

asyncio.AbstractEventLoop

Parameters:

options (Any) –

@event(coro)[source]#

A decorator that registers an event to listen to.

You can find more info about the events on the documentation below.

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

Note

This replaces any default handlers. Developers are encouraged to use listen() for adding additional handlers instead of event() unless default method replacement is intended.

Raises:

TypeError – The coroutine passed is not actually a coroutine.

Example

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

coro (TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])) –

Return type:

TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])

async for ... in 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.owner, Guild.icon, Guild.id, and Guild.name per Guild.

Note

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

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.

Yields:

Guild – The guild with the guild data parsed.

Raises:

HTTPException – Getting the guilds failed.

Return type:

GuildIterator

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.

@listen(name=..., once=False)[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.

Raises:

  • TypeError – The function being listened to is not a coroutine.

  • ValueError – The name (event name) does not start with ‘on_’

Example

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

# in some other file...

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

# listen to the first event only
@client.listen('on_ready', once=True)
async def on_ready():
    print('ready!')

Would print one and two in an unspecified order.

Parameters:
Return type:

Callable[[TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])], TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])]

property latency#

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

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

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. :rtype: bool

New in version 1.6.

property user#

Represents the connected client. None if not logged in.

property guilds#

The guilds that the connected client is a member of.

property emojis#

The emojis that the connected client has.

property stickers#

The stickers that the connected client has.

New in version 2.0.

property cached_messages#

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

New in version 1.1.

property private_channels#

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.

property voice_clients#

Represents a list of voice connections.

These are usually VoiceClient instances.

property application_id#

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.

property application_flags#

The client’s application flags.

New in version 2.0.

is_ready()[source]#

Specifies if the client’s internal cache is ready for use.

Return type:

bool

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.

Parameters:

  • event_method (str) –

  • args (Any) –

  • kwargs (Any) –

Return type:

None

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.

Return type:

None

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:

  • TypeError – The token was in invalid type.

  • 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.

Return type:

None

await connect(*, reconnect=True)[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.

Parameters:

reconnect (bool) – If we should attempt reconnecting, 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).

Raises:

  • GatewayNotFound – 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.

Return type:

None

await close()[source]#

This function is a coroutine.

Closes the connection to Discord.

Return type:

None

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.

Return type:

None

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

This function is a coroutine.

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

Raises:

TypeError – An unexpected keyword argument was received.

Parameters:

  • token (str) –

  • reconnect (bool) –

Return type:

None

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.

Parameters:

  • args (Any) –

  • kwargs (Any) –

Return type:

None

is_closed()[source]#

Indicates if the WebSocket connection is closed.

Return type:

bool

property activity#

The activity being used upon logging in.

Return type:

Optional[BaseActivity]

property status#

The status being used upon logging on to Discord.

property allowed_mentions#

The allowed mention configuration.

New in version 1.4.

property intents#

The intents configured for this connection.

New in version 1.5.

property users#

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

await fetch_application(application_id, /)[source]#

This function is a coroutine. Retrieves a PartialAppInfo from an application ID.

Parameters:

application_id (int) – The application ID to retrieve information from.

Returns:

The application information.

Return type:

PartialAppInfo

Raises:

  • NotFound – An application with this ID does not exist.

  • HTTPException – Retrieving the application failed.

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_message(id, /)[source]#

Returns a message the given ID.

This is useful if you have a message_id but don’t want to do an API call to access the message.

Parameters:

id (int) – The ID to search for.

Returns:

The returned message or None if not found.

Return type:

Optional[Message]

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_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 stage instance or None if not found.

Return type:

Optional[StageInstance]

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_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_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_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]

Parameters:

id (int) –

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
Return type:

Generator[GuildChannel, None, None]

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.

Return type:

Generator[Member, None, None]

await get_or_fetch_user(id, /)[source]#

This function is a coroutine.

Looks up a user in the user cache or fetches if not found.

Parameters:

id (int) – The ID to search for.

Returns:

The user or None if not found.

Return type:

Optional[User]

await wait_until_ready()[source]#

This function is a coroutine.

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

Return type:

None

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.

Parameters:

  • event (str) – The event name, similar to the event reference, but without the on_ prefix, to wait for.

  • 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.

Returns:

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

Return type:

Any

Raises:

asyncio.TimeoutError – Raised if a timeout is provided and reached.

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}!')

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('👍')
add_listener(func, name=...)[source]#

The non decorator alternative to listen().

Parameters:

  • func (coroutine) – The function to call.

  • name (str) – The name of the event to listen for. Defaults to func.__name__.

Raises:

  • TypeError – The func parameter is not a coroutine function.

  • ValueError – The name (event name) does not start with ‘on_’

Return type:

None

Example

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

client.add_listener(on_ready)
client.add_listener(my_message, 'on_message')
remove_listener(func, name=...)[source]#

Removes a listener from the pool of listeners.

Parameters:

  • func (TypeVar(Coro, bound= Callable[..., Coroutine[Any, Any, Any]])) – The function that was used as a listener to remove.

  • name (str) – The name of the event we want to remove. Defaults to func.__name__.

Return type:

None

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

This function is a coroutine.

Changes the client’s presence.

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:

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

Example

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

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

await fetch_template(code)[source]#

This function is a coroutine.

Gets 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).

Returns:

The template from the URL/code.

Return type:

Template

Raises:
await fetch_guild(guild_id, /, *, with_counts=True)[source]#

This function is a coroutine.

Retrieves a Guild from an 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:
Returns:

The guild from the ID.

Return type:

Guild

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

This function is a coroutine.

Creates a Guild.

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

Parameters:

  • name (str) – The name of the guild.

  • icon (Optional[bytes]) – The bytes-like object representing the icon. See ClientUser.edit() for more details on what is expected.

  • code (str) –

    The code for a template to create the guild with.

    New in version 1.4.

Returns:

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

Return type:

Guild

Raises:
await fetch_stage_instance(channel_id, /)[source]#

This function is a coroutine.

Gets a StageInstance for a stage channel id.

New in version 2.0.

Parameters:

channel_id (int) – The stage channel ID.

Returns:

The stage instance from the stage channel ID.

Return type:

StageInstance

Raises:

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

  • HTTPException – Getting the stage instance failed.

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

This function is a coroutine.

Gets 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:
Returns:

The invite from the URL/ID.

Return type:

Invite

Raises:
await delete_invite(invite)[source]#

This function is a coroutine.

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

You must have the 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.

Return type:

None

await fetch_widget(guild_id, /)[source]#

This function is a coroutine.

Gets a Widget from a guild ID.

Note

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

Parameters:

guild_id (int) – The ID of the guild.

Returns:

The guild’s widget.

Return type:

Widget

Raises:
await application_info()[source]#

This function is a coroutine.

Retrieves the bot’s application information.

Returns:

The bot’s application information.

Return type:

AppInfo

Raises:

HTTPException – Retrieving the information failed somehow.

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 discord.Intents.members and member cache enabled, consider get_user() instead.

Parameters:

user_id (int) – The user’s ID to fetch from.

Returns:

The user you requested.

Return type:

User

Raises:
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.

Returns:

The channel from the ID.

Return type:

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

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.

Parameters:

channel_id (int) –

await fetch_webhook(webhook_id, /)[source]#

This function is a coroutine.

Retrieves a Webhook with the specified ID.

Returns:

The webhook you requested.

Return type:

Webhook

Raises:
Parameters:

webhook_id (int) –

await fetch_sticker(sticker_id, /)[source]#

This function is a coroutine.

Retrieves a Sticker with the specified ID.

New in version 2.0.

Returns:

The sticker you requested.

Return type:

Union[StandardSticker, GuildSticker]

Raises:
Parameters:

sticker_id (int) –

await fetch_premium_sticker_packs()[source]#

This function is a coroutine.

Retrieves all available premium sticker packs.

New in version 2.0.

Returns:

All available premium sticker packs.

Return type:

List[StickerPack]

Raises:

HTTPException – Retrieving the sticker packs failed.

await create_dm(user)[source]#

This function is a coroutine.

Creates a DMChannel with this 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

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 (discord.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.

Return type:

None

property persistent_views#

A sequence of persistent views added to the client.

New in version 2.0.

await fetch_role_connection_metadata_records()[source]#

This function is a coroutine.

Fetches the bot’s role connection metadata records.

New in version 2.4.

Returns:

The bot’s role connection metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

await update_role_connection_metadata_records(*role_connection_metadata)[source]#

This function is a coroutine.

Updates the bot’s role connection metadata records.

New in version 2.4.

Parameters:

*role_connection_metadata (ApplicationRoleConnectionMetadata) – The new metadata records to send to Discord.

Returns:

The updated role connection metadata records.

Return type:

List[ApplicationRoleConnectionMetadata]

await fetch_skus()[source]#

This function is a coroutine.

Fetches the bot’s SKUs.

New in version 2.5.

Returns:

The bot’s SKUs.

Return type:

List[SKU]

await fetch_entitlements()[source]#

This function is a coroutine.

Fetches the bot’s entitlements.

New in version 2.5.

Returns:

The bot’s entitlements.

Return type:

List[Entitlement]

Attributes
Methods
class discord.AutoShardedClient(*args, loop=None, **kwargs)[source]#

A client similar to Client except it handles the complications of sharding for the user into a more manageable and transparent single process bot.

When using this client, you will be able to use it as-if it was a regular Client with a single shard when implementation wise internally it is split up into multiple shards. This allows you to not have to deal with IPC or other complicated infrastructure.

It is recommended to use this client only if you have surpassed at least 1000 guilds.

If no shard_count is provided, then the library will use the Bot Gateway endpoint call to figure out how many shards to use.

If a shard_ids parameter is given, then those shard IDs will be used to launch the internal shards. Note that shard_count must be provided if this is used. By default, when omitted, the client will launch shards from 0 to shard_count - 1.

shard_ids#

An optional list of shard_ids to launch the shards with.

Type:

Optional[List[int]]

Parameters:
property latency#

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

This operates similarly to Client.latency() except it uses the average latency of every shard’s latency. To get a list of shard latency, check the latencies property. Returns nan if there are no shards ready.

property latencies#

A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

This returns a list of tuples with elements (shard_id, latency).

get_shard(shard_id)[source]#

Gets the shard information at a given shard ID or None if not found.

Parameters:

shard_id (int) –

Return type:

ShardInfo | None

property shards#

Returns a mapping of shard IDs to their respective info object.

await connect(*, reconnect=True)[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.

Parameters:

reconnect (bool) – If we should attempt reconnecting, 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).

Raises:

  • GatewayNotFound – 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.

Return type:

None

await close()[source]#

This function is a coroutine.

Closes the connection to Discord.

Return type:

None

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

This function is a coroutine.

Changes the client’s presence.

Example:

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

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

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.

  • shard_id (Optional[int]) – The shard_id to change the presence to. If not specified or None, then it will change the presence of every shard the bot can see.

Raises:

InvalidArgument – If the activity parameter is not of proper type.

Return type:

None

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.

This implementation checks if any of the shards are rate limited. For more granular control, consider ShardInfo.is_ws_ratelimited(). :rtype: bool

New in version 1.6.