Members

This sections documents everything related to guild members.

Discord Models

Member

Attributes
Methods
class disnake.Member[source]

Represents a Discord member to a Guild.

This implements a lot of the functionality of User.

x == y

Checks if two members are equal. Note that this works with User instances too.

x != y

Checks if two members are not equal. Note that this works with User instances too.

hash(x)

Returns the member’s hash.

str(x)

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

joined_at

An aware datetime object that specifies the date and time in UTC that the member joined the guild. If the member left and rejoined the guild, this will be the latest date. In certain cases, this can be None.

Type:

Optional[datetime.datetime]

activities

The activities that the user is currently doing.

Note

Due to a Discord API limitation, a user’s Spotify activity may not appear if they are listening to a song with a title longer than 128 characters. See #1738 for more information.

Type:

Tuple[Union[BaseActivity, Spotify]]

guild

The guild that the member belongs to.

Type:

Guild

nick

The guild specific nickname of the user. This takes precedence over global_name and name when shown.

Type:

Optional[str]

pending

Whether the member is pending member verification.

New in version 1.6.

Type:

bool

premium_since

An aware datetime object that specifies the date and time in UTC when the member used their “Nitro boost” on the guild, if available. This could be None.

Type:

Optional[datetime.datetime]

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 name

Equivalent to User.name

property id

Equivalent to User.id

property discriminator

Equivalent to User.discriminator

property global_name

Equivalent to User.global_name

property bot

Equivalent to User.bot

property system

Equivalent to User.system

property created_at

Equivalent to User.created_at

property default_avatar

Equivalent to User.default_avatar

property avatar

Equivalent to User.avatar

property dm_channel

Equivalent to User.dm_channel

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 mutual_guilds

Equivalent to User.mutual_guilds

property public_flags

Equivalent to User.public_flags

property banner

Equivalent to User.banner

property accent_color

Equivalent to User.accent_color

property accent_colour

Equivalent to User.accent_colour

property raw_status[source]

The member’s overall status as a string value.

New in version 1.5.

Type:

str

property status[source]

The member’s overall status. If the value is unknown, then it will be a str instead.

Type:

Status

property tag[source]

An alias of discriminator.

Type:

str

property mobile_status[source]

The member’s status on a mobile device, if applicable.

Type:

Status

property desktop_status[source]

The member’s status on the desktop client, if applicable.

Type:

Status

property web_status[source]

The member’s status on the web client, if applicable.

Type:

Status

is_on_mobile()[source]

Whether the member is active on a mobile device.

Return type:

bool

property colour[source]

A property that returns a colour denoting the rendered colour for the member. If the default colour is the one rendered then an instance of Colour.default() is returned.

There is an alias for this named color.

Type:

Colour

property color[source]

A property that returns a color denoting the rendered color for the member. If the default color is the one rendered then an instance of Colour.default() is returned.

There is an alias for this named colour.

Type:

Colour

property roles[source]

A list of Role that the member belongs to. Note that the first element of this list is always the default ‘@everyone’ role.

These roles are sorted by their position in the role hierarchy.

Type:

List[Role]

property mention[source]

Returns a string that allows you to mention the member.

Type:

str

property display_name[source]

Returns the user’s display name.

If they have a guild-specific nickname, then that is returned. If not, this is their global name if set, or their username otherwise.

Changed in version 2.9: Added global_name.

Type:

str

property display_avatar[source]

Returns the member’s display avatar.

For regular members this is just their avatar, but if they have a guild specific avatar then that is returned instead.

New in version 2.0.

Type:

Asset

property guild_avatar[source]

Returns an Asset for the guild avatar the member has. If unavailable, None is returned.

New in version 2.0.

Type:

Optional[Asset]

property guild_banner[source]

Returns an Asset for the guild banner the member has. If unavailable, None is returned.

New in version 2.10.

Type:

Optional[Asset]

property activity[source]

Returns the primary activity the user is currently doing. Could be None if no activity is being done.

Note

Due to a Discord API limitation, this may be None if the user is listening to a song on Spotify with a title longer than 128 characters. See #1738 for more information.

Note

A user may have multiple activities, these can be accessed under activities.

Type:

Optional[Union[BaseActivity, Spotify]]

mentioned_in(message)[source]

Whether the member is mentioned in the specified message.

Parameters:

message (Message) – The message to check.

Returns:

Indicates if the member is mentioned in the message.

Return type:

bool

property top_role[source]

Returns the member’s highest role.

This is useful for figuring where a member stands in the role hierarchy chain.

Type:

Role

property role_icon[source]

Returns the member’s displayed role icon, if any.

New in version 2.5.

Type:

Optional[Union[Asset, PartialEmoji]]

property guild_permissions[source]

Returns the member’s guild permissions.

This only takes into consideration the guild permissions and not most of the implied permissions or any of the channel permission overwrites. For 100% accurate permission calculation, please use abc.GuildChannel.permissions_for().

This does take into consideration guild ownership and the administrator implication.

Type:

Permissions

property voice[source]

Returns the member’s current voice state.

Type:

Optional[VoiceState]

property current_timeout[source]

Returns the datetime when the timeout expires.

If the member is not timed out or the timeout has already expired, returns None.

New in version 2.3.

Type:

Optional[datetime.datetime]

property flags[source]

Returns the member’s flags.

New in version 2.8.

Type:

MemberFlags

property display_avatar_decoration[source]

Returns the member’s display avatar decoration.

For regular members this is just their avatar decoration, but if they have a guild specific avatar decoration then that is returned instead.

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

Returns an Asset for the guild avatar decoration the member has. If unavailable, None is returned.

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]

await ban(*, clean_history_duration=..., delete_message_days=..., reason=None)[source]

This function is a coroutine.

Bans this member. Equivalent to Guild.ban().

await unban(*, reason=None)[source]

This function is a coroutine.

Unbans this member. Equivalent to Guild.unban().

await kick(*, reason=None)[source]

This function is a coroutine.

Kicks this member. Equivalent to Guild.kick().

await edit(*, nick=..., mute=..., deafen=..., suppress=..., roles=..., voice_channel=..., timeout=..., flags=..., bypasses_verification=..., reason=None)[source]

This function is a coroutine.

Edits the member’s data.

Depending on the parameter passed, this requires different permissions listed below:

Parameter

Permission

nick

Permissions.manage_nicknames

mute

Permissions.mute_members

deafen

Permissions.deafen_members

roles

Permissions.manage_roles

voice_channel

Permissions.move_members

timeout

Permissions.moderate_members

flags

Permissions.manage_guild or Permissions.manage_roles or (Permissions.moderate_members + Permissions.kick_members + Permissions.ban_members)

bypasses_verification

(same as flags)

All parameters are optional.

Changed in version 1.1: Can now pass None to voice_channel to kick a member from voice.

Changed in version 2.0: The newly member is now optionally returned, if applicable.

Parameters:

  • nick (Optional[str]) – The member’s new nickname. Use None to remove the nickname.

  • mute (bool) – Whether the member should be guild muted or un-muted.

  • deafen (bool) – Whether the member should be guild deafened or un-deafened.

  • suppress (bool) –

    Whether the member should be suppressed in stage channels.

    New in version 1.7.

  • roles (Sequence[Role]) – The member’s new list of roles. This replaces the roles.

  • voice_channel (Optional[VoiceChannel]) – The voice channel to move the member to. Pass None to kick them from voice.

  • timeout (Optional[Union[float, datetime.timedelta, datetime.datetime]]) –

    The duration (seconds or timedelta) or the expiry (datetime) of the timeout; until then, the member will not be able to interact with the guild. Set to None to remove the timeout. Supports up to 28 days in the future.

    New in version 2.3.

  • flags (MemberFlags) –

    The member’s new flags. To know what flags are editable, see the documentation.

    If parameter bypasses_verification is provided, that will override the setting of MemberFlags.bypasses_verification.

    New in version 2.8.

  • bypasses_verification (bool) –

    Whether the member bypasses guild verification requirements.

    New in version 2.8.

  • reason (Optional[str]) – The reason for editing this member. Shows up on the audit log.

Raises:

  • Forbidden – You do not have the proper permissions to the action requested.

  • HTTPException – The operation failed.

Returns:

The newly updated member, if applicable. This is only returned when certain fields are updated.

Return type:

Optional[Member]

await request_to_speak()[source]

This function is a coroutine.

Requests to speak in the connected channel.

Only applies to stage channels.

Note

Requesting members that are not the client is equivalent to edit providing suppress as False.

New in version 1.7.

Raises:

  • Forbidden – You do not have the proper permissions to the action requested.

  • HTTPException – The operation failed.

property avatar_decoration

Equivalent to User.avatar_decoration

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

await move_to(channel, *, reason=None)[source]

This function is a coroutine.

Moves a member to a new voice channel (they must be connected first).

You must have move_members permission to use this.

This raises the same exceptions as edit().

Changed in version 1.1: Can now pass None to kick a member from voice.

Parameters:

  • channel (Optional[VoiceChannel]) – The new voice channel to move the member to. Pass None to kick them from voice.

  • reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

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]

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

  • poll (Poll) –

    The poll to send with the message.

    New in version 2.10.

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.

await add_roles(*roles, reason=None, atomic=True)[source]

This function is a coroutine.

Gives the member a number of Roles.

You must have manage_roles permission to use this, and the added Roles must appear lower in the list of roles than the highest role of the member.

Parameters:

  • *roles (abc.Snowflake) – An argument list of abc.Snowflake representing a Role to give to the member.

  • reason (Optional[str]) – The reason for adding these roles. Shows up on the audit log.

  • atomic (bool) – Whether to atomically add roles. This will ensure that multiple operations will always be applied regardless of the current state of the cache.

Raises:
await remove_roles(*roles, reason=None, atomic=True)[source]

This function is a coroutine.

Removes Roles from this member.

You must have manage_roles permission to use this, and the removed Roles must appear lower in the list of roles than the highest role of the member.

Parameters:

  • *roles (abc.Snowflake) – An argument list of abc.Snowflake representing a Role to remove from the member.

  • reason (Optional[str]) – The reason for removing these roles. Shows up on the audit log.

  • atomic (bool) – Whether to atomically remove roles. This will ensure that multiple operations will always be applied regardless of the current state of the cache.

Raises:

  • Forbidden – You do not have permissions to remove these roles.

  • HTTPException – Removing the roles failed.

get_role(role_id, /)[source]

Returns a role with the given ID from roles which the member has.

New in version 2.0.

Parameters:

role_id (int) – The role ID to search for.

Returns:

The role or None if not found in the member’s roles.

Return type:

Optional[Role]

await timeout(*, duration=..., until=..., reason=None)[source]

This function is a coroutine.

Times out the member from the guild; until then, the member will not be able to interact with the guild.

Exactly one of duration or until must be provided. To remove a timeout, set one of the parameters to None.

You must have the Permissions.moderate_members permission to do this.

New in version 2.3.

Parameters:

  • duration (Optional[Union[float, datetime.timedelta]]) – The duration (seconds or timedelta) of the member’s timeout. Set to None to remove the timeout. Supports up to 28 days in the future. May not be used in combination with the until parameter.

  • until (Optional[datetime.datetime]) – The expiry date/time of the member’s timeout. Set to None to remove the timeout. Supports up to 28 days in the future. May not be used in combination with the duration parameter.

  • reason (Optional[str]) – The reason for this timeout. Appears on the audit log.

Raises:

  • Forbidden – You do not have permissions to timeout this member.

  • HTTPException – Timing out the member failed.

Returns:

The newly updated member.

Return type:

Member

RawGuildMemberRemoveEvent

Attributes
class disnake.RawGuildMemberRemoveEvent[source]

Represents the event payload for an on_raw_member_remove() event.

New in version 2.6.

guild_id

The ID of the guild where the member was removed from.

Type:

int

user

The user object of the member that was removed.

Type:

Union[User, Member]

RawPresenceUpdateEvent

Attributes
class disnake.RawPresenceUpdateEvent[source]

Represents the event payload for an on_raw_presence_update() event.

New in version 2.10.

user_id

The ID of the user whose presence was updated.

Type:

int

guild_id

The ID of the guild where the user’s presence changed.

Type:

int

data

The raw data given by the gateway.

Type:

dict

Events