Users

This section documents everything related to users.

Discord Models

User

Attributes
Methods
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]

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

Returns the user’s collectibles.

New in version 2.11.

Type:

Collectibles

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

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

pins(*, limit=50, before=None)[source]

Returns an AsyncIterator that enables receiving the destination’s pinned messages.

You must have the Permissions.read_message_history and Permissions.view_channel permissions to use this.

Note

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

Changed in version 2.11: Now returns an AsyncIterator to support changes in Discord’s API. awaiting the result of this method remains supported, but only returns the last 50 pins and is deprecated in favor of async for msg in channel.pins().

Examples

Usage

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

Flattening to a list

pinned_messages = await channel.pins(limit=100).flatten()
# pinned_messages is now a list of Message...

All parameters are optional.

Parameters:

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

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

Raises:

HTTPException – Retrieving the pinned messages failed.

Yields:

Message – The pinned message from the parsed message data.

property primary_guild[source]

Returns the user’s primary guild, if any.

New in version 2.11.

Type:

Optional[PrimaryGuild]

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, poll=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, poll 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.

    Note

    Passing a Message or PartialMessage will only allow replies. To forward a message you must explicitly transform the message to a MessageReference using Message.to_reference() and specify the MessageReferenceType, or use Message.forward().

  • 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[UIComponent, List[Union[UIComponent, List[WrappedComponent]]]]) –

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

    New in version 2.4.

    Note

    Passing v2 components here automatically sets the is_components_v2 flag. Setting this flag cannot be reverted. Note that this also disables the content, embeds, stickers, and poll fields.

  • 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, suppress_notifications, and is_components_v2 are supported.

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

    New in version 2.9.

  • poll (Poll) –

    The poll to send with the message.

    New in version 2.10.

Raises:

  • HTTPException – Sending the message failed.

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

  • TypeError – Specified both file and files, or you specified both embed and embeds, or you specified both view and components, or the reference object is not a Message, MessageReference or PartialMessage.

  • ValueError – The files or embeds list is too large, or you tried to send v2 components together with content, embeds, stickers, or poll.

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.

Collectibles

Attributes
class disnake.Collectibles[source]

Represents the collectibles the user has, excluding Avatar Decorations and Profile Effects.

New in version 2.11.

nameplate

The nameplate of the user, if available.

Type:

Optional[Nameplate]

Nameplate

Attributes
class disnake.Nameplate[source]

Represents the decoration behind the name of a user that appears in the server, DM and DM group members list.

New in version 2.11.

sku_id

The ID of the nameplate SKU.

Type:

int

label

The label of this nameplate.

Type:

str

palette

The background color of the nameplate.

Type:

NameplatePalette

property animated_asset[source]

Returns the animated nameplate for the user.

New in version 2.11.

Note

Since Discord always sends a WEBM for animated nameplates, the following methods will not work as expected:

Type:

Asset

property static_asset[source]

Returns the static nameplate for the user.

New in version 2.11.

Type:

Asset

Data Classes

PublicUserFlags

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

Attributes
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 a MemberFlags instance is a subset of another MemberFlags instance.

x >= y

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

x < y

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

x > y

Checks if a 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

is_guest

Returns True if the member is a guest and can only access the voice channel they were invited to.

New in version 2.10.

Type:

bool

started_home_actions

Returns True if the member has started the Server Guide actions.

New in version 2.10.

Type:

bool

completed_home_actions

Returns True if the member has completed the Server Guide actions.

New in version 2.10.

Type:

bool

automod_quarantined_username

Returns True if the member’s username, display name, or nickname is blocked by AutoMod.

New in version 2.10.

Type:

bool

dm_settings_upsell_acknowledged

Returns True if the member has dismissed the DM settings upsell.

New in version 2.10.

Type:

bool

automod_quarantined_guild_tag

Returns True if the member’s guild tag is blocked by AutoMod.

New in version 2.11.

Type:

bool

PrimaryGuild

Attributes
class disnake.PrimaryGuild[source]

Represents a user’s primary guild.

New in version 2.11.

guild_id

The ID of the user’s primary guild.

Type:

Optional[int]

identity_enabled

Whether the user is displaying the primary guild’s server tag. This can be None if the system clears the identity, e.g. the server no longer supports tags. This will be False if the user manually removes their tag.

Type:

Optional[bool]

tag

The text of the user’s server tag, up to 4 characters.

Type:

Optional[str]

property badge[source]

Returns the server tag badge, if any.

Type:

Optional[Asset]

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.

NameplatePalette

class disnake.NameplatePalette[source]

Specifies the palette of a Nameplate.

New in version 2.11.

crimson

Crimson color palette.

berry

Berry color palette.

sky

Sky color palette.

teal

Teal color palette.

forest

Forest color palette.

bubble_gum

Bubble gum color palette.

violet

Violet color palette.

cobalt

Cobalt color palette.

clover

Clover color palette.

lemon

Lemon color palette.

white

White color palette.

Events