Users¶

This section documents everything related to users.

Discord Models¶

User¶

Attributes

accent_color
accent_colour
avatar
banner
bot
color
colour
created_at
default_avatar
discriminator
display_avatar
display_name
dm_channel
id
mention
mutual_guilds
name
public_flags
system

Methods

asynccreate_dm
asyncfetch_message
defhistory
defmentioned_in
asyncpins
asyncsend
asynctrigger_typing
deftyping

class disnake.User[source]¶

This class is a Discord Model.

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 name with discriminator.

name¶

The user’s username.

Type:: str

id¶

The user’s unique ID.

Type:: int

discriminator¶

The user’s discriminator. This is given when the username has conflicts.

Type:: 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. This is calculated by the user’s discriminator.

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.

For regular users this is just their username, but if they have a guild specific nickname then that is returned instead.

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=False, 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, 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 embeds from the UI if set to True.

New in version 2.5.

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.

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¶

Attributes

bug_hunter
bug_hunter_level_2
discord_certified_moderator
early_supporter
early_verified_bot_developer
http_interactions_bot
hypesquad
hypesquad_balance
hypesquad_bravery
hypesquad_brilliance
partner
spammer
staff
system
team_user
value
verified_bot
verified_bot_developer

Methods

defall

class disnake.PublicUserFlags[source]¶

This class is a Data Class.

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

discord_certified_moderator¶

Returns True if the user is a Discord Certified Moderator.

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

all()[source]¶: List[UserFlags]: Returns all public flags the user has.

Enumerations¶

UserFlags¶

class disnake.UserFlags[source]¶

This class is an Enumeration.

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.

DefaultAvatar¶

class disnake.DefaultAvatar[source]¶

This class is an Enumeration.

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

Events¶

on_user_update(before, after)

See all related events!