Clients

This section documents everything related to Client and it’s connectivity to Discord.

If this is your first time working with disnake, it is highly recommended to read Getting Started articles first.

Classes

Client

Attributes
Methods
class disnake.Client(*, asyncio_debug=False, loop=None, shard_id=None, shard_count=None, enable_debug_events=False, enable_gateway_error_handler=True, localization_provider=None, strict_localization=False, gateway_params=None, connector=None, proxy=None, proxy_auth=None, assume_unsync_clock=True, max_messages=1000, application_id=None, heartbeat_timeout=60.0, guild_ready_timeout=2.0, allowed_mentions=None, activity=None, status=None, intents=None, chunk_guilds_at_startup=None, member_cache_flags=None)[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().

  • asyncio_debug (bool) – Whether to enable asyncio debugging when the client starts. Defaults to False.

  • 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 (Optional[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[Union[class:str, 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.

  • enable_gateway_error_handler (bool) –

    Whether to enable the disnake.on_gateway_error() event. Defaults to True.

    If this is disabled, exceptions that occur while parsing (known) gateway events won’t be handled and the pre-v2.6 behavior of letting the exception propagate up to the connect()/start()/run() call is used instead.

    New in version 2.6.

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

    Changed in version 2.6: Can no longer be provided together with strict_localization, as it does not apply to the custom localization provider entered in this parameter.

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

    Changed in version 2.6: Can no longer be provided together with localization_provider, as this parameter is ignored for custom localization providers.

  • gateway_params (GatewayParams) –

    Allows configuring parameters used for establishing gateway connections, notably enabling/disabling compression (enabled by default). Encodings other than JSON are not supported.

    New in version 2.6.

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

session_start_limit

Information about the current session start limit. Only available after initiating the connection.

New in version 2.5.

Type:

Optional[SessionStartLimit]

i18n

An implementation of LocalizationProtocol used for localization of application commands.

New in version 2.5.

Type:

LocalizationProtocol

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

async for ... in fetch_guilds(*, limit=100, before=None, after=None, with_counts=True)[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.

  • with_counts (bool) –

    Whether to include approximate member and presence counts for the guilds. Defaults to True.

    New in version 2.10.

Raises:

HTTPException – Retrieving the guilds failed.

Yields:

Guild – The guild with the guild data parsed.

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

Changed in version 2.10: The definition of this method was moved from ext.commands.Bot to the Client class.

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

# in yet another file
@client.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 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

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 user[source]

Represents the connected client. None if not logged in.

Type:

Optional[ClientUser]

property guilds[source]

The guilds that the connected client is a member of.

Type:

List[Guild]

property emojis[source]

The emojis that the connected client has.

Type:

List[Emoji]

property stickers[source]

The stickers that the connected client has.

New in version 2.0.

Type:

List[GuildSticker]

property cached_messages[source]

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

New in version 1.1.

Type:

Sequence[Message]

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]

property voice_clients[source]

Represents a list of voice connections.

These are usually VoiceClient instances.

Type:

List[VoiceProtocol]

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]

property application_flags[source]

The client’s application flags.

New in version 2.0.

Type:

ApplicationFlags

property global_application_commands[source]

The client’s global application commands.

Type:

List[Union[APIUserCommand, APIMessageCommand, APISlashCommand]

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]

property global_message_commands[source]

The client’s global message commands.

Type:

List[APIMessageCommand]

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]

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

This function is a coroutine.

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

This only propagates exceptions when the strict parameter is enabled.

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]

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

This function is a coroutine.

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

This only propagates exceptions when the strict parameter is enabled.

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]

is_ready()[source]

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

Return type:

bool

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

The non decorator alternative to listen().

Changed in version 2.10: The definition of this method was moved from ext.commands.Bot to the Client class.

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

client.add_listener(on_ready)
client.add_listener(my_message, 'on_message')
client.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.

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

Removes a listener from the pool of listeners.

Changed in version 2.10: The definition of this method was moved from ext.commands.Bot to the Client class.

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.

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

Changed in version 2.10: The definition of this method was moved from ext.commands.Bot to the Client class.

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

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 close()[source]

This function is a coroutine.

Closes the connection to Discord.

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

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:

token (str) – The discord token of the bot that is being ran.

is_closed()[source]

Whether the websocket connection is closed.

Return type:

bool

property activity[source]

The activity being used upon logging in.

Type:

Optional[BaseActivity]

property status[source]

The status being used upon logging on to Discord.

New in version 2.0.

Type:

Status

property allowed_mentions[source]

The allowed mention configuration.

New in version 1.4.

Type:

Optional[AllowedMentions]

property intents[source]

The intents configured for this connection.

New in version 1.5.

Type:

Intents

property users[source]

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

Type:

List[User]

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_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 returns 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_sticker_packs().

Returns:

The sticker or None if not found.

Return type:

Optional[GuildSticker]

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

await wait_until_ready()[source]

This function is a coroutine.

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

await wait_until_first_connect()[source]

This function is a coroutine.

Waits until the first connect.

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

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_guild(guild_id, /, *, with_counts=True)[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.

  • with_counts (bool) –

    Whether to include approximate member and presence counts for the guild. Defaults to True.

    New in version 2.10.

Raises:
Returns:

The guild from the given ID.

Return type:

Guild

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

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

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

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

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 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_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_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_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_sticker_pack(pack_id, /)[source]

This function is a coroutine.

Retrieves a StickerPack with the given ID.

New in version 2.10.

Parameters:

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

Raises:
Returns:

The sticker pack you requested.

Return type:

StickerPack

await fetch_sticker_packs()[source]

This function is a coroutine.

Retrieves all available sticker packs.

New in version 2.0.

Changed in version 2.10: Renamed from fetch_premium_sticker_packs.

Raises:

HTTPException – Retrieving the sticker packs failed.

Returns:

All available sticker packs.

Return type:

List[StickerPack]

await fetch_premium_sticker_packs()[source]

An alias of fetch_sticker_packs().

Deprecated since version 2.10.

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

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 persistent_views[source]

A sequence of persistent views added to the client.

New in version 2.0.

Type:

Sequence[View]

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

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

await skus()[source]

This function is a coroutine.

Retrieves the SKUs for the application.

To manage application subscription entitlements, you should use the SKU with SKUType.subscription (not the subscription_group one).

New in version 2.10.

Raises:

HTTPException – Retrieving the SKUs failed.

Returns:

The list of SKUs.

Return type:

List[SKU]

entitlements(*, limit=100, before=None, after=None, user=None, guild=None, skus=None, exclude_ended=False, exclude_deleted=True, oldest_first=False)[source]

Retrieves an AsyncIterator that enables receiving entitlements for the application.

Note

This method is an API call. To get the entitlements of the invoking user/guild in interactions, consider using Interaction.entitlements.

Entries are returned in order from newest to oldest by default; pass oldest_first=True to reverse the iteration order.

All parameters are optional.

New in version 2.10.

Parameters:

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

  • before (Union[abc.Snowflake, datetime.datetime]) – Retrieves entitlements created 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 entitlements created 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.

  • user (Optional[abc.Snowflake]) – The user to retrieve entitlements for.

  • guild (Optional[abc.Snowflake]) – The guild to retrieve entitlements for.

  • skus (Optional[Sequence[abc.Snowflake]]) – The SKUs for which entitlements are retrieved.

  • exclude_ended (bool) – Whether to exclude ended/expired entitlements. Defaults to False.

  • exclude_deleted (bool) – Whether to exclude deleted entitlements. Defaults to True.

  • oldest_first (bool) – If set to True, return entries in oldest->newest order. Defaults to False.

Raises:

HTTPException – Retrieving the entitlements failed.

Yields:

Entitlement – The entitlements for the given parameters.

await fetch_entitlement(entitlement_id, /)[source]

This function is a coroutine.

Retrieves a Entitlement for the given ID.

Note

This method is an API call. To get the entitlements of the invoking user/guild in interactions, consider using Interaction.entitlements.

New in version 2.10.

Parameters:

entitlement_id (int) – The ID of the entitlement to retrieve.

Raises:

HTTPException – Retrieving the entitlement failed.

Returns:

The retrieved entitlement.

Return type:

Entitlement

await create_entitlement(sku, owner)[source]

This function is a coroutine.

Creates a new test Entitlement for the given user or guild, with no expiry.

Parameters:

  • sku (abc.Snowflake) – The SKU to grant the entitlement for.

  • owner (Union[abc.User, Guild]) – The user or guild to grant the entitlement to.

Raises:

HTTPException – Creating the entitlement failed.

Returns:

The newly created entitlement.

Return type:

Entitlement

AutoShardedClient

Attributes
Methods
class disnake.AutoShardedClient(*args, shard_ids=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]]

property latency[source]

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.

Type:

float

property latencies[source]

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

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

Type:

List[Tuple[int, float]]

get_shard(shard_id)[source]

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

Return type:

Optional[ShardInfo]

property shards[source]

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

Type:

Mapping[int, ShardInfo]

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 close()[source]

This function is a coroutine.

Closes the connection to Discord.

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

This function is a coroutine.

Changes the client’s presence.

Example:

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

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

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

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:

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

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

New in version 1.6.

Return type:

bool

Discord Models

ClientUser

Attributes
Methods
class disnake.ClientUser[source]

Represents your Discord user.

x == y

Checks if two users are equal.

x != y

Checks if two users are not equal.

hash(x)

Return the user’s hash.

str(x)

Returns the user’s username (with discriminator, if not migrated to new system yet).

name

The user’s username.

Type:

str

id

The user’s unique ID.

Type:

int

discriminator

The user’s discriminator.

Type:

str

global_name

The user’s global display name, if set. This takes precedence over name when shown.

New in version 2.9.

Type:

Optional[str]

bot

Specifies if the user is a bot account.

Type:

bool

system

Specifies if the user is a system user (i.e. represents Discord officially).

New in version 1.3.

Type:

bool

verified

Specifies if the user’s email is verified.

Type:

bool

locale

The IETF language tag used to identify the language the user is using.

Changed in version 2.5: Changed to Locale instead of str.

Type:

Optional[Locale]

mfa_enabled

Specifies if the user has MFA turned on and working.

Type:

bool

await edit(*, username=..., avatar=..., banner=...)[source]

This function is a coroutine.

Edits the current profile of the client.

Changed in version 2.0: The edit is no longer in-place, instead the newly edited client user is returned.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:

  • username (str) – The new username you wish to change to.

  • avatar (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    A bytes-like object or asset representing the image to upload. Could be None to denote no avatar.

    Only JPG, PNG, WEBP (static), and GIF (static/animated) images are supported.

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • banner (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    A bytes-like object or asset representing the image to upload. Could be None to denote no banner.

    Only JPG, PNG, WEBP (static), and GIF (static/animated) images are supported.

    New in version 2.10.

Raises:
Returns:

The newly edited client user.

Return type:

ClientUser

property accent_color[source]

Returns the user’s accent color, if applicable.

There is an alias for this named accent_colour.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type:

Optional[Colour]

property accent_colour[source]

Returns the user’s accent colour, if applicable.

There is an alias for this named accent_color.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type:

Optional[Colour]

property avatar[source]

Returns an Asset for the avatar the user has.

If the user does not have a traditional avatar, None is returned. If you want the avatar that a user has displayed, consider display_avatar.

Type:

Optional[Asset]

property avatar_decoration[source]

Returns the user’s avatar decoration asset, if available.

New in version 2.10.

Note

Since Discord always sends an animated PNG for animated avatar decorations, the following methods will not work as expected:

Type:

Optional[Asset]

property banner[source]

Returns the user’s banner asset, if available.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type:

Optional[Asset]

property color[source]

A property that returns a color denoting the rendered color for the user. This always returns Colour.default().

There is an alias for this named colour.

Type:

Colour

property colour[source]

A property that returns a colour denoting the rendered colour for the user. This always returns Colour.default().

There is an alias for this named color.

Type:

Colour

property created_at[source]

Returns the user’s creation time in UTC.

This is when the user’s Discord account was created.

Type:

datetime.datetime

property default_avatar[source]

Returns the default avatar for a given user.

Changed in version 2.9: Added handling for users migrated to the new username system without discriminators.

Type:

Asset

property display_avatar[source]

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type:

Asset

property display_name[source]

Returns the user’s display name.

This is their global name if set, or their username otherwise.

Changed in version 2.9: Added global_name.

Type:

str

property mention[source]

Returns a string that allows you to mention the given user.

Type:

str

mentioned_in(message)[source]

Checks if the user is mentioned in the specified message.

Parameters:

message (Message) – The message to check.

Returns:

Indicates if the user is mentioned in the message.

Return type:

bool

property public_flags[source]

The publicly available flags the user has.

Type:

PublicUserFlags

SessionStartLimit

Attributes
class disnake.SessionStartLimit[source]

A class that contains information about the current session start limit, at the time when the client connected for the first time.

New in version 2.5.

total

The total number of allowed session starts.

Type:

int

remaining

The remaining number of allowed session starts.

Type:

int

reset_after

The number of milliseconds after which the remaining limit resets, relative to when the client connected. See also reset_time.

Type:

int

max_concurrency

The number of allowed IDENTIFY requests per 5 seconds.

Type:

int

reset_time

The approximate time at which which the remaining limit resets.

Type:

datetime.datetime

Data Classes

ShardInfo

Attributes
Methods
class disnake.ShardInfo[source]

A class that gives information and control over a specific shard.

You can retrieve this object via AutoShardedClient.get_shard() or AutoShardedClient.shards.

New in version 1.4.

id

The shard ID for this shard.

Type:

int

shard_count

The shard count for this cluster. If this is None then the bot has not started yet.

Type:

Optional[int]

is_closed()[source]

Whether the shard connection is currently closed.

Return type:

bool

await disconnect()[source]

This function is a coroutine.

Disconnects a shard. When this is called, the shard connection will no longer be open.

If the shard is already disconnected this does nothing.

await reconnect()[source]

This function is a coroutine.

Disconnects and then connects the shard again.

await connect()[source]

This function is a coroutine.

Connects a shard. If the shard is already connected this does nothing.

property latency[source]

Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds for this shard.

Type:

float

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

GatewayParams

class disnake.GatewayParams[source]

Container type for configuring gateway connections.

New in version 2.6.

Parameters:

  • encoding (str) – The payload encoding (json is currently the only supported encoding). Defaults to "json".

  • zlib (bool) – Whether to enable transport compression. Defaults to True.

Intents

Attributes
Methods
class disnake.Intents(value=None, **kwargs)[source]

Wraps up a Discord gateway intent flag.

Similar to Permissions, the properties provided are two way. You can set and retrieve individual bits using the properties as if they were regular bools.

To construct an object you can pass keyword arguments denoting the flags to enable or disable. Arguments are applied in order, similar to Permissions.

This is used to disable certain gateway features that are unnecessary to run your bot. To make use of this, it is passed to the intents keyword argument of Client.

New in version 1.5.

x == y

Checks if two Intents instances are equal.

x != y

Checks if two Intents instances are not equal.

x <= y

Checks if an Intents instance is a subset of another Intents instance.

New in version 2.6.

x >= y

Checks if an Intents instance is a superset of another Intents instance.

New in version 2.6.

x < y

Checks if an Intents instance is a strict subset of another Intents instance.

New in version 2.6.

x > y

Checks if an Intents instance is a strict superset of another Intents instance.

New in version 2.6.

x | y, x |= y

Returns a new Intents instance with all enabled intents from both x and y. (Using |= will update in place).

New in version 2.6.

x & y, x &= y

Returns a new Intents instance with only intents enabled on both x and y. (Using &= will update in place).

New in version 2.6.

x ^ y, x ^= y

Returns a new Intents instance with only intents enabled on one of x or y, but not both. (Using ^= will update in place).

New in version 2.6.

~x

Returns a new Intents instance with all intents inverted from x.

New in version 2.6.

hash(x)

Return the flag’s hash.

iter(x)

Returns an iterator of (name, value) pairs. This allows it to be, for example, constructed as a dict or a list of pairs.

Additionally supported are a few operations on class attributes.

Intents.y | Intents.z, Intents(y=True) | Intents.z

Returns a Intents instance with all provided flags enabled.

New in version 2.6.

~Intents.y

Returns a Intents instance with all flags except y inverted from their default value.

New in version 2.6.

value

The raw value. You should query flags via the properties rather than using this raw value.

Changed in version 2.6: This can be now be provided on initialisation.

Type:

int

classmethod all()[source]

A factory method that creates a Intents with everything enabled.

classmethod none()[source]

A factory method that creates a Intents with everything disabled.

classmethod default()[source]

A factory method that creates a Intents with everything enabled except presences, members, and message_content.

guilds

Whether guild related events are enabled.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

It is highly advisable to leave this intent enabled for your bot to function.

Type:

bool

members

Whether guild member related events are enabled.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

For more information go to the member intent documentation.

Note

Currently, this requires opting in explicitly via the developer portal as well. Bots in over 100 guilds will need to apply to Discord for verification.

Type:

bool

moderation

Whether guild moderation related events are enabled.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

bans

Alias of moderation.

Changed in version 2.8: Changed to an alias.

Type:

bool

emojis

Alias of emojis_and_stickers.

Changed in version 2.0: Changed to an alias.

Type:

bool

emojis_and_stickers

Whether guild emoji and sticker related events are enabled.

New in version 2.0.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Type:

bool

integrations

Whether guild integration related events are enabled.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

webhooks

Whether guild webhook related events are enabled.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

invites

Whether guild invite related events are enabled.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

voice_states

Whether guild voice state related events are enabled.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Note

This intent is required to connect to voice.

Type:

bool

presences

Whether guild presence related events are enabled.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

For more information go to the presence intent documentation.

Note

Currently, this requires opting in explicitly via the developer portal as well. Bots in over 100 guilds will need to apply to Discord for verification.

Type:

bool

messages

Whether guild and direct message related events are enabled.

This is a shortcut to set or get both guild_messages and dm_messages.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Note that due to an implicit relationship this also corresponds to the following events:

Note

Intents.message_content is required to receive the content of messages.

Type:

bool

guild_messages

Whether guild message related events are enabled.

See also dm_messages for DMs or messages for both.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Note that due to an implicit relationship this also corresponds to the following events:

Type:

bool

dm_messages

Whether direct message related events are enabled.

See also guild_messages for guilds or messages for both.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Note that due to an implicit relationship this also corresponds to the following events:

Type:

bool

message_content

Whether messages will have access to message content.

New in version 2.5.

This applies to the following fields on Message instances:

The following cases will always have the above fields:

  • Messages the bot sends

  • Messages the bot receives as a direct message

  • Messages in which the bot is mentioned

  • Messages received from an interaction payload, these will typically be attributes on MessageInteraction instances.

In addition, this also corresponds to the following fields:

For more information go to the message content intent documentation.

Note

Currently, this requires opting in explicitly via the developer portal as well. Bots in over 100 guilds will need to apply to Discord for verification.

Type:

bool

reactions

Whether guild and direct message reaction related events are enabled.

This is a shortcut to set or get both guild_reactions and dm_reactions.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Type:

bool

guild_reactions

Whether guild reaction related events are enabled.

See also dm_reactions for DMs or reactions for both.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Type:

bool

dm_reactions

Whether direct message reaction related events are enabled.

See also guild_reactions for guilds or reactions for both.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Type:

bool

typing

Whether guild and direct message typing related events are enabled.

This is a shortcut to set or get both guild_typing and dm_typing.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

guild_typing

Whether guild typing related events are enabled.

See also dm_typing for DMs or typing for both.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

dm_typing

Whether direct message typing related events are enabled.

See also guild_typing for guilds or typing for both.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

guild_scheduled_events

Whether guild scheduled event related events are enabled.

New in version 2.3.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Type:

bool

automod_configuration

Whether auto moderation configuration related events are enabled.

New in version 2.6.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

automod_execution

Whether auto moderation execution related events are enabled.

New in version 2.6.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

automod

Whether auto moderation related events are enabled.

New in version 2.6.

This is a shortcut to set or get both automod_configuration and automod_execution.

This corresponds to the following events:

This does not correspond to any attributes or classes in the library in terms of cache.

Type:

bool

polls

Whether guild and direct message polls related events are enabled.

This is a shortcut to set or get both guild_polls and dm_polls.

This corresponds to the following events:

Type:

bool

guild_polls

Whether guild polls related events are enabled.

New in version 2.10.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Type:

bool

dm_polls

Whether direct message polls related events are enabled.

New in version 2.10.

This corresponds to the following events:

This also corresponds to the following attributes and classes in terms of cache:

Type:

bool

MemberCacheFlags

Attributes
Methods
class disnake.MemberCacheFlags(**kwargs)[source]

Controls the library’s cache policy when it comes to members.

This allows for finer grained control over what members are cached. Note that the bot’s own member is always cached. This class is passed to the member_cache_flags parameter in Client.

Due to a quirk in how Discord works, in order to ensure proper cleanup of cache resources it is recommended to have Intents.members enabled. Otherwise the library cannot know when a member leaves a guild and is thus unable to cleanup after itself.

To construct an object you can pass keyword arguments denoting the flags to enable or disable. Arguments are applied in order, similar to Permissions.

The default value is all flags enabled.

New in version 1.5.

x == y

Checks if two MemberCacheFlags instances are equal.

x != y

Checks if two MemberCacheFlags instances are not equal.

x <= y

Checks if a MemberCacheFlags instance is a subset of another MemberCacheFlags instance.

New in version 2.6.

x >= y

Checks if a MemberCacheFlags instance is a superset of another MemberCacheFlags instance.

New in version 2.6.

x < y

Checks if a MemberCacheFlags instance is a strict subset of another MemberCacheFlags instance.

New in version 2.6.

x > y

Checks if a MemberCacheFlags instance is a strict superset of another MemberCacheFlags instance.

New in version 2.6.

x | y, x |= y

Returns a new MemberCacheFlags instance with all enabled flags from both x and y. (Using |= will update in place).

New in version 2.6.

x & y, x &= y

Returns a new MemberCacheFlags instance with only flags enabled on both x and y. (Using &= will update in place).

New in version 2.6.

x ^ y, x ^= y

Returns a new MemberCacheFlags instance with only flags enabled on one of x or y, but not both. (Using ^= will update in place).

New in version 2.6.

~x

Returns a new MemberCacheFlags instance with all flags from x inverted.

New in version 2.6.

hash(x)

Return the flag’s hash.

iter(x)

Returns an iterator of (name, value) pairs. This allows it to be, for example, constructed as a dict or a list of pairs.

Additionally supported are a few operations on class attributes.

MemberCacheFlags.y | MemberCacheFlags.z, MemberCacheFlags(y=True) | MemberCacheFlags.z

Returns a MemberCacheFlags instance with all provided flags enabled.

New in version 2.6.

~MemberCacheFlags.y

Returns a MemberCacheFlags instance with all flags except y inverted from their default value.

New in version 2.6.

value

The raw value. You should query flags via the properties rather than using this raw value.

Type:

int

classmethod all()[source]

A factory method that creates a MemberCacheFlags with everything enabled.

classmethod none()[source]

A factory method that creates a MemberCacheFlags with everything disabled.

voice

Whether to cache members that are in voice.

This requires Intents.voice_states.

Members that leave voice are no longer cached.

Type:

bool

joined

Whether to cache members that joined the guild or are chunked as part of the initial log in flow.

This requires Intents.members.

Members that leave the guild are no longer cached.

Type:

bool

classmethod from_intents(intents)[source]

A factory method that creates a MemberCacheFlags based on the currently selected Intents.

Parameters:

intents (Intents) – The intents to select from.

Returns:

The resulting member cache flags.

Return type:

MemberCacheFlags

Events