Users

This section documents everything related to users.

Discord Models

User

class disnake.User[source]

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

Note

This is being phased out by Discord; the username system is moving away from username#discriminator to users having a globally unique username. The value of a single zero ("0") indicates that the user has been migrated to the new system. See the help article for details.

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

Type:

bool

async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)[source]

Returns an AsyncIterator that enables receiving the destination’s message history.

You must have Permissions.read_message_history permission to use this.

Examples

Usage

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

Flattening into a list:

messages = await channel.history(limit=123).flatten()
# messages is now a list of Message...

All parameters are optional.

Parameters:
  • limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the channel. Note, however, that this would make it a slow operation.

  • before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages before this date or message. 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 (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages after this date or message. 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.

  • around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve messages around this date or message. 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. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages.

  • oldest_first (Optional[bool]) – If set to True, return messages in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises:
  • Forbidden – You do not have permissions to get channel message history.

  • HTTPException – The request to get message history failed.

Yields:

Message – The message with the message data parsed.

async with typing()[source]

Returns a context manager that allows you to type for an indefinite period of time.

This is useful for denoting long computations in your bot.

Note

This is both a regular context manager and an async context manager. This means that both with and async with work with this.

Example Usage:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(10)

await channel.send('done!')
property dm_channel[source]

Returns the channel associated with this user if it exists.

If this returns None, you can create a DM channel by calling the create_dm() coroutine function.

Type:

Optional[DMChannel]

property mutual_guilds[source]

The guilds that the user shares with the client.

Note

This will only return mutual guilds within the client’s internal cache.

New in version 1.7.

Type:

List[Guild]

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

await create_dm()[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.

Returns:

The channel that was created.

Return type:

DMChannel

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

await fetch_message(id, /)[source]

This function is a coroutine.

Retrieves a single Message from the destination.

Parameters:

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

Raises:
  • NotFound – The specified message was not found.

  • Forbidden – You do not have the permissions required to get a message.

  • HTTPException – Retrieving the message failed.

Returns:

The message asked for.

Return type:

Message

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

await pins()[source]

This function is a coroutine.

Retrieves all messages that are currently pinned in the channel.

Note

Due to a limitation with the Discord API, the Message objects returned by this method do not contain complete Message.reactions data.

Raises:

HTTPException – Retrieving the pinned messages failed.

Returns:

The messages that are currently pinned.

Return type:

List[Message]

property public_flags[source]

The publicly available flags the user has.

Type:

PublicUserFlags

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, suppress_embeds=None, flags=None, allowed_mentions=None, reference=None, mention_author=None, view=None, components=None)[source]

This function is a coroutine.

Sends a message to the destination with the content given.

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

At least one of content, embed/embeds, file/files, stickers, components, or view must be provided.

To upload a single file, the file parameter should be used with a single File object. To upload multiple files, the files parameter should be used with a list of File objects. Specifying both parameters will lead to an exception.

To upload a single embed, the embed parameter should be used with a single Embed object. To upload multiple embeds, the embeds parameter should be used with a list of Embed objects. Specifying both parameters will lead to an exception.

Changed in version 2.6: Raises TypeError or ValueError instead of InvalidArgument.

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

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

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

  • embeds (List[Embed]) –

    A list of embeds to send with the content. Must be a maximum of 10. This cannot be mixed with the embed parameter.

    New in version 2.0.

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

  • files (List[File]) – A list of files to upload. Must be a maximum of 10. This cannot be mixed with the file parameter.

  • stickers (Sequence[Union[GuildSticker, StandardSticker, StickerItem]]) –

    A list of stickers to upload. Must be a maximum of 3.

    New in version 2.0.

  • nonce (Union[str, int]) – The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value.

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

  • allowed_mentions (AllowedMentions) –

    Controls the mentions being processed in this message. If this is passed, then the object is merged with Client.allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in Client.allowed_mentions. If no object is passed at all then the defaults given by Client.allowed_mentions are used instead.

    New in version 1.4.

  • reference (Union[Message, MessageReference, PartialMessage]) –

    A reference to the Message to which you are replying, this can be created using Message.to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the AllowedMentions.replied_user attribute of allowed_mentions or by setting mention_author.

    New in version 1.6.

  • mention_author (Optional[bool]) –

    If set, overrides the AllowedMentions.replied_user attribute of allowed_mentions.

    New in version 1.6.

  • view (ui.View) –

    A Discord UI View to add to the message. This cannot be mixed with components.

    New in version 2.0.

  • components (Union[disnake.ui.ActionRow, disnake.ui.WrappedComponent, List[Union[disnake.ui.ActionRow, disnake.ui.WrappedComponent, List[disnake.ui.WrappedComponent]]]]) –

    A list of components to include in the message. This cannot be mixed with view.

    New in version 2.4.

  • suppress_embeds (bool) –

    Whether to suppress embeds for the message. This hides all the embeds from the UI if set to True.

    New in version 2.5.

  • flags (MessageFlags) –

    The flags to set for this message. Only suppress_embeds and suppress_notifications are supported.

    If parameter suppress_embeds is provided, that will override the setting of MessageFlags.suppress_embeds.

    New in version 2.9.

Raises:
Returns:

The message that was sent.

Return type:

Message

await trigger_typing()[source]

This function is a coroutine.

Triggers a typing indicator to the destination.

Typing indicator will go away after 10 seconds, or after a message is sent.

Data Classes

PublicUserFlags

class disnake.PublicUserFlags[source]

Wraps up the Discord User Public flags.

x == y

Checks if two PublicUserFlags instances are equal.

x != y

Checks if two PublicUserFlags instances are not equal.

x <= y

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

New in version 2.6.

x >= y

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

New in version 2.6.

x < y

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

New in version 2.6.

x > y

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

New in version 2.6.

x | y, x |= y

Returns a new PublicUserFlags 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 PublicUserFlags 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 PublicUserFlags 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 PublicUserFlags 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. Note that aliases are not shown.

Additionally supported are a few operations on class attributes.

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

Returns a PublicUserFlags instance with all provided flags enabled.

New in version 2.6.

~PublicUserFlags.y

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

New in version 2.6.

New in version 1.4.

value

The raw value. This value is a bit array field of a 53-bit integer representing the currently available flags. You should query flags via the properties rather than using this raw value.

Type:

int

staff

Returns True if the user is a Discord Employee.

Type:

bool

partner

Returns True if the user is a Discord Partner.

Type:

bool

hypesquad

Returns True if the user is a HypeSquad Events member.

Type:

bool

bug_hunter

Returns True if the user is a Bug Hunter

Type:

bool

hypesquad_bravery

Returns True if the user is a HypeSquad Bravery member.

Type:

bool

hypesquad_brilliance

Returns True if the user is a HypeSquad Brilliance member.

Type:

bool

hypesquad_balance

Returns True if the user is a HypeSquad Balance member.

Type:

bool

early_supporter

Returns True if the user is an Early Supporter.

Type:

bool

team_user

Returns True if the user is a Team User.

Type:

bool

system

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

Type:

bool

bug_hunter_level_2

Returns True if the user is a Bug Hunter Level 2

Type:

bool

verified_bot

Returns True if the user is a Verified Bot.

Type:

bool

verified_bot_developer

Returns True if the user is an Early Verified Bot Developer.

Type:

bool

early_verified_bot_developer

An alias for verified_bot_developer.

New in version 1.5.

Type:

bool

moderator_programs_alumni

Returns True if the user is a Discord Moderator Programs Alumni.

New in version 2.8.

Type:

bool

discord_certified_moderator

An alias for moderator_programs_alumni.

New in version 2.0.

Type:

bool

http_interactions_bot

Returns True if the user is a bot that only uses HTTP interactions.

New in version 2.3.

Type:

bool

spammer

Returns True if the user is marked as a spammer.

New in version 2.3.

Type:

bool

active_developer

Returns True if the user is an Active Developer.

New in version 2.8.

Type:

bool

all()[source]

List[UserFlags]: Returns all public flags the user has.

MemberFlags

class disnake.MemberFlags[source]

Wraps up Discord Member flags.

x == y

Checks if two MemberFlags instances are equal.

x != y

Checks if two MemberFlags instances are not equal.

x <= y

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

x >= y

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

x < y

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

x > y

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

x | y, x |= y

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

x & y, x &= y

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

x ^ y, x ^= y

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

~x

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

hash(x)

Returns 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. Note that aliases are not shown.

Additionally supported are a few operations on class attributes.

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

Returns a MemberFlags instance with all provided flags enabled.

~MemberFlags.y

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

New in version 2.8.

value

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

Type:

int

did_rejoin

Returns True if the member has left and rejoined the guild.

Type:

bool

completed_onboarding

Returns True if the member has completed onboarding.

Type:

bool

bypasses_verification

Returns True if the member is able to bypass guild verification requirements.

Type:

bool

started_onboarding

Returns True if the member has started onboarding.

Type:

bool

Enumerations

UserFlags

class disnake.UserFlags[source]

Represents Discord User flags.

staff

The user is a Discord Employee.

partner

The user is a Discord Partner.

hypesquad

The user is a HypeSquad Events member.

bug_hunter

The user is a Bug Hunter.

mfa_sms

The user has SMS recovery for Multi Factor Authentication enabled.

premium_promo_dismissed

The user has dismissed the Discord Nitro promotion.

hypesquad_bravery

The user is a HypeSquad Bravery member.

hypesquad_brilliance

The user is a HypeSquad Brilliance member.

hypesquad_balance

The user is a HypeSquad Balance member.

early_supporter

The user is an Early Supporter.

team_user

The user is a Team User.

system

The user is a system user (i.e. represents Discord officially).

has_unread_urgent_messages

The user has an unread system message.

bug_hunter_level_2

The user is a Bug Hunter Level 2.

verified_bot

The user is a Verified Bot.

verified_bot_developer

The user is an Early Verified Bot Developer.

discord_certified_moderator

The user is a Discord Certified Moderator.

http_interactions_bot

The user is a bot that only uses HTTP interactions.

New in version 2.3.

spammer

The user is marked as a spammer.

New in version 2.3.

active_developer

The user is an Active Developer.

New in version 2.8.

DefaultAvatar

class disnake.DefaultAvatar[source]

Represents the default avatar of a Discord User.

blurple

Represents the default avatar with the color blurple. See also Colour.blurple

grey

Represents the default avatar with the color grey. See also Colour.greyple

gray

An alias for grey.

green

Represents the default avatar with the color green. See also Colour.green

orange

Represents the default avatar with the color orange. See also Colour.orange

red

Represents the default avatar with the color red. See also Colour.red

fuchsia

Represents the default avatar with the color fuchsia. See also Colour.fuchsia

New in version 2.9.

Events