Data Classes

Some classes are just there to be data containers, this lists them.

Unlike models you are allowed to create most of these yourself, even if they can also be used to hold attributes.

Nearly all classes here have __slots__ defined which means that it is impossible to have dynamic attributes to the data classes.

The only exception to this rule is abc.Snowflake, which is made with dynamic attributes in mind.

Object

Attributes
class discord.Object(id, type=MISSING, *, state=MISSING)

Bases: Hashable

Represents a generic Discord object.

The purpose of this class is to allow you to create ‘miniature’ versions of data classes if you want to pass in just an ID. Most functions that take in a specific data class with an ID can also take in this class as a substitute instead. Note that even though this is the case, not all objects (if any) actually inherit from this class.

There are also some cases where some websocket events are received in strange order and when such events happened you would receive this class rather than the actual data class. These cases are extremely rare.

x == y

Checks if two objects are equal.

x != y

Checks if two objects are not equal.

hash(x)

Returns the object’s hash.

id

The ID of the object.

Type:

int

type

The object this should represent if any.

Type:

object

property created_at

Returns the snowflake’s creation time in UTC.

Type:

datetime.datetime

Embed

Attributes
Methods
class discord.Embed(*, title=Embed.Empty, description=Embed.Empty, color=Embed.Empty, timestamp=Embed.Empty, url=Embed.Empty, type='rich', colour=Embed.Empty)

Bases: object

Represents a Discord embed.

len(x)

Returns the total size of the embed. Useful for checking if it’s within the 6000-character limit.

Certain properties return an EmbedProxy, a type that acts similar to a regular dict except using dotted access, e.g. embed.author.icon_url. If the attribute is invalid or empty, then a special sentinel value is returned, Embed.Empty.

For ease of use, all parameters that expect a str are implicitly cast to str for you.

title

The title of the embed. This can be set during initialisation.

Type:

str

type

The type of embed. Usually “rich”. This can be set during initialisation. Possible strings for embed types can be found on discord’s api docs

Type:

str

description

The description of the embed. This can be set during initialisation.

Type:

str

url

The URL of the embed. This can be set during initialisation.

Type:

str

timestamp

The timestamp of the embed content. This could be a naive or aware datetime.

Type:

datetime.datetime

colour

The colour code of the embed. Aliased to color as well. This can be set during initialisation.

Type:

Union[Colour, int]

Empty

A special sentinel value used by EmbedProxy and this class to denote that the value or attribute is empty.

classmethod from_dict(data)

Converts a dict to a Embed provided it is in the format that Discord expects it to be in.

You can find out about this format in the official Discord documentation.

Parameters:

data (dict) – The dictionary to convert into an embed.

copy()

Returns a shallow copy of the embed.

property footer

Returns an EmbedProxy denoting the footer contents.

See set_footer() for possible values you can access.

If the attribute has no value then Empty is returned.

Type:

Union[EmbedProxy, Empty]

Sets the footer for the embed content.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

  • text (str) – The footer text.

  • icon_url (str) – The URL of the footer icon. Only HTTP(S) is supported.

property image

Returns an EmbedProxy denoting the image contents.

Possible attributes you can access are:

  • url

  • proxy_url

  • width

  • height

If the attribute has no value then Empty is returned.

Type:

Union[EmbedProxy, Empty]

set_image(*, url)

Sets the image for the embed content.

This function returns the class instance to allow for fluent-style chaining.

Changed in version 1.4: Passing Empty removes the image.

Parameters:

url (str) – The source URL for the image. Only HTTP(S) and discords attachment:// protocol is supported.

property thumbnail

Returns an EmbedProxy denoting the thumbnail contents.

Possible attributes you can access are:

  • url

  • proxy_url

  • width

  • height

If the attribute has no value then Empty is returned.

Type:

Union[EmbedProxy, Empty]

set_thumbnail(*, url)

Sets the thumbnail for the embed content.

This function returns the class instance to allow for fluent-style chaining.

Changed in version 1.4: Passing Empty removes the thumbnail.

Parameters:

url (str) – The source URL for the thumbnail. Only HTTP(S) and discords attachment:// protocol is supported.

property video

Returns an EmbedProxy denoting the video contents.

Possible attributes include:

  • url for the video URL.

  • height for the video height.

  • width for the video width.

If the attribute has no value then Empty is returned.

Type:

Union[EmbedProxy, Empty]

property provider

Returns an EmbedProxy denoting the provider contents.

The only attributes that might be accessed are name and url.

If the attribute has no value then Empty is returned.

Type:

Union[EmbedProxy, Empty]

property author

Returns an EmbedProxy denoting the author contents.

See set_author() for possible values you can access.

If the attribute has no value then Empty is returned.

Type:

Union[EmbedProxy, Empty]

set_author(*, name, url=Embed.Empty, icon_url=Embed.Empty)

Sets the author for the embed content.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

  • name (str) – The name of the author.

  • url (str) – The URL for the author.

  • icon_url (str) – The URL of the author icon. Only HTTP(S) is supported.

remove_author()

Clears embed’s author information.

This function returns the class instance to allow for fluent-style chaining.

Added in version 1.4.

property fields

Returns a list of EmbedProxy denoting the field contents.

See add_field() for possible values you can access.

If the attribute has no value then Empty is returned.

Type:

List[Union[EmbedProxy, Empty]]

add_field(*, name, value, inline=True)

Adds a field to the embed object.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

  • name (str) – The name of the field.

  • value (str) – The value of the field.

  • inline (bool) – Whether the field should be displayed inline.

insert_field_at(index, *, name, value, inline=True)

Inserts a field before a specified index to the embed.

This function returns the class instance to allow for fluent-style chaining.

Added in version 1.2.

Parameters:

  • index (int) – The index of where to insert the field.

  • name (str) – The name of the field.

  • value (str) – The value of the field.

  • inline (bool) – Whether the field should be displayed inline.

clear_fields()

Removes all fields from this embed.

remove_field(index)

Removes a field at a specified index.

If the index is invalid or out of bounds then the error is silently swallowed.

Note

When deleting a field by index, the index of the other fields shift to fill the gap just like a regular list.

Parameters:

index (int) – The index of the field to remove.

set_field_at(index, *, name, value, inline=True)

Modifies a field to the embed object.

The index must point to a valid pre-existing field.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

  • index (int) – The index of the field to modify.

  • name (str) – The name of the field.

  • value (str) – The value of the field.

  • inline (bool) – Whether the field should be displayed inline.

Raises:

IndexError – An invalid index was provided.

to_dict()

Converts this embed object into a dict.

AllowedMentions

Attributes
Methods
class discord.AllowedMentions(*, everyone=True, users=True, roles=True, replied_user=True)

Bases: object

A class that represents what mentions are allowed in a message.

This class can be set during Client initialisation to apply to every message sent. It can also be applied on a per message basis via abc.Messageable.send() for more fine-grained control.

everyone

Whether to allow everyone and here mentions. Defaults to True.

Type:

bool

users

Controls the users being mentioned. If True (the default) then users are mentioned based on the message content. If False then users are not mentioned at all. If a list of abc.Snowflake is given then only the users provided will be mentioned, provided those users are in the message content.

Type:

Union[bool, List[abc.Snowflake]]

roles

Controls the roles being mentioned. If True (the default) then roles are mentioned based on the message content. If False then roles are not mentioned at all. If a list of abc.Snowflake is given then only the roles provided will be mentioned, provided those roles are in the message content.

Type:

Union[bool, List[abc.Snowflake]]

replied_user

Whether to mention the author of the message being replied to. Defaults to True.

Added in version 1.6.

Type:

bool

classmethod all()

A factory method that returns a AllowedMentions with all fields explicitly set to True

Added in version 1.5.

classmethod none()

A factory method that returns a AllowedMentions with all fields set to False

Added in version 1.5.

MessageReference

Attributes
Methods
class discord.MessageReference(*, message_id, channel_id, guild_id=None, fail_if_not_exists=True)

Bases: object

Represents a reference to a Message.

Added in version 1.5.

Changed in version 1.6: This class can now be constructed by users.

message_id

The id of the message referenced.

Type:

Optional[int]

channel_id

The channel id of the message referenced.

Type:

int

guild_id

The guild id of the message referenced.

Type:

Optional[int]

fail_if_not_exists

Whether replying to the referenced message should raise HTTPException if the message no longer exists or Discord could not fetch the message.

Added in version 1.7.

Type:

bool

resolved

The message that this reference resolved to. If this is None then the original message was not fetched either due to the Discord API not attempting to resolve it or it not being available at the time of creation. If the message was resolved at a prior point but has since been deleted then this will be of type DeletedReferencedMessage.

Currently, this is mainly the replied to message when a user replies to a message.

Added in version 1.6.

Type:

Optional[Union[Message, DeletedReferencedMessage]]

classmethod from_message(message, *, fail_if_not_exists=True)

Creates a MessageReference from an existing Message.

Added in version 1.6.

Parameters:

  • message (Message) – The message to be converted into a reference.

  • fail_if_not_exists (bool) –

    Whether replying to the referenced message should raise HTTPException if the message no longer exists or Discord could not fetch the message.

    Added in version 1.7.

Returns:

A reference to the message.

Return type:

MessageReference

property cached_message

The cached message, if found in the internal message cache.

Type:

Optional[Message]

property jump_url

Returns a URL that allows the client to jump to the referenced message.

Added in version 1.7.

Type:

str

PartialMessage

Attributes
Methods
class discord.PartialMessage(*, channel, id)

Bases: Hashable, Generic[_MCH]

Represents a partial message to aid with working messages when only a message and channel ID are present.

There are two ways to construct this class. The first one is through the constructor itself, and the second is via TextChannel.get_partial_message() or DMChannel.get_partial_message().

Note that this class is trimmed down and has no rich attributes.

Added in version 1.6.

x == y

Checks if two partial messages are equal.

x != y

Checks if two partial messages are not equal.

hash(x)

Returns the partial message’s hash.

channel

The channel associated with this partial message.

Type:

Union[TextChannel, ThreadChannel, DMChannel]

id

The message ID.

Type:

int

guild

The guild associated with this partial message, if applicable.

Type:

Optional[Guild]

property jump_url

Returns a URL that allows the client to jump to this message.

Type:

str

await delete(*, delay=None, reason=None)

This function is a coroutine.

Deletes the message.

Your own messages could be deleted without any proper permissions. However, to delete other people’s messages, you need the manage_messages permission.

Changed in version 1.1: Added the new delay keyword-only parameter.

Parameters:

  • delay (Optional[float]) – If provided, the number of seconds to wait in the background before deleting the message. If the deletion fails then it is silently ignored.

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

Raises:

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

  • NotFound – The message was deleted already

  • HTTPException – Deleting the message failed.

await publish()

This function is a coroutine.

Publishes this message to your announcement channel.

If the message is not your own then the manage_messages permission is needed.

Raises:

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

  • HTTPException – Publishing the message failed.

await pin(*, suppress_system_message=False, reason=None)

This function is a coroutine.

Pins the message.

You must have the manage_messages permission to do this in a non-private channel context.

Parameters:

  • suppress_system_message (bool) –

    When set to True, the function will wait 5 seconds for the system message and delete it. Defaults to False.

    Added in version 2.0.

  • reason (Optional[str]) –

    The reason for pinning the message. Shows up on the audit log.

    Added in version 1.4.

Raises:

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

  • NotFound – The message or channel was not found or deleted.

  • HTTPException – Pinning the message failed, probably due to the channel having more than 50 pinned messages.

  • TimeoutError – Waiting for the system message timed out.

await unpin(*, reason=None)

This function is a coroutine.

Unpins the message.

You must have the manage_messages permission to do this in a non-private channel context.

Parameters:

reason (Optional[str]) –

The reason for unpinning the message. Shows up on the audit log.

Added in version 1.4.

Raises:

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

  • NotFound – The message or channel was not found or deleted.

  • HTTPException – Unpinning the message failed.

await add_reaction(emoji)

This function is a coroutine.

Add a reaction to the message.

The emoji may be a unicode emoji or a custom guild Emoji.

You must have the read_message_history permission to use this. If nobody else has reacted to the message using this emoji, the add_reactions permission is required.

Parameters:

emoji (Union[Emoji, Reaction, PartialEmoji, str]) – The emoji to react with.

Raises:

  • HTTPException – Adding the reaction failed.

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

  • NotFound – The emoji you specified was not found.

  • InvalidArgument – The emoji parameter is invalid.

await remove_reaction(emoji, member)

This function is a coroutine.

Remove a reaction by the member from the message.

The emoji may be a unicode emoji or a custom guild Emoji.

If the reaction is not your own (i.e. member parameter is not you) then the manage_messages permission is needed.

The member parameter must represent a member and meet the abc.Snowflake abc.

Parameters:
Raises:

  • HTTPException – Removing the reaction failed.

  • Forbidden – You do not have the proper permissions to remove the reaction.

  • NotFound – The member or emoji you specified was not found.

  • InvalidArgument – The emoji parameter is invalid.

await clear_reaction(emoji)

This function is a coroutine.

Clears a specific reaction from the message.

The emoji may be a unicode emoji or a custom guild Emoji.

You need the manage_messages permission to use this.

Added in version 1.3.

Parameters:

emoji (Union[Emoji, Reaction, PartialEmoji, str]) – The emoji to clear.

Raises:

  • HTTPException – Clearing the reaction failed.

  • Forbidden – You do not have the proper permissions to clear the reaction.

  • NotFound – The emoji you specified was not found.

  • InvalidArgument – The emoji parameter is invalid.

await clear_reactions()

This function is a coroutine.

Removes all the reactions from the message.

You need the manage_messages permission to use this.

Raises:

  • HTTPException – Removing the reactions failed.

  • Forbidden – You do not have the proper permissions to remove all the reactions.

await reply(content=None, tts=False, embed=None, embeds=None, components=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, mention_author=None, suppress_embeds=False, suppress_notifications=False)

This function is a coroutine.

A shortcut method to abc.Messageable.send() to reply to the Message.

Added in version 1.6.

Raises:

  • HTTPException – Sending the message failed.

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

  • InvalidArgument – The files list is not of the appropriate size or you specified both file and files.

Returns:

The message that was sent.

Return type:

Message

await create_thread(name, auto_archive_duration=None, slowmode_delay=0, reason=None)

This function is a coroutine.

Creates a new thread in the channel of the message with this message as the starter_message.

Parameters:

  • name (str) – The name of the thread.

  • auto_archive_duration (Optional[AutoArchiveDuration]) – Amount of time after that the thread will auto-hide from the channel list

  • slowmode_delay (int) – Amount of seconds a user has to wait before sending another message (0-21600)

  • reason (Optional[str]) – The reason for creating the thread. Shows up in the audit log.

Raises:

  • TypeError – The channel of the message is not a text or news channel, or the message has already a thread, or auto_archive_duration is not a valid member of AutoArchiveDuration

  • ValueError – The name is of invalid length

  • Forbidden – The bot is missing permissions to create threads in this channel

  • HTTPException – Creating the thread failed

Returns:

The created thread on success

Return type:

ThreadChannel

to_reference(*, fail_if_not_exists=True)

Creates a MessageReference from the current message.

Added in version 1.6.

Parameters:

fail_if_not_exists (bool) –

Whether replying using the message reference should raise HTTPException if the message no longer exists or Discord could not fetch the message.

Added in version 1.7.

Returns:

The reference to this message.

Return type:

MessageReference

property created_at

The partial message’s creation time in UTC.

Type:

datetime.datetime

await fetch()

This function is a coroutine.

Fetches the partial message to a full Message.

Raises:

  • NotFound – The message was not found.

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

  • HTTPException – Retrieving the message failed.

Returns:

The full message.

Return type:

Message

await edit(*, content=MISSING, embed=MISSING, embeds=MISSING, components=MISSING, attachments=MISSING, delete_after=None, allowed_mentions=MISSING, suppress_embeds=MISSING)

This function is a coroutine.

Edits the message.

The content must be able to be transformed into a string via str(content).

Changed in version 1.3: The suppress keyword-only parameter was added.

Changed in version 2.0: The components and attachments parameters were added.

Changed in version 2.0: The suppress keyword-only parameter was renamed to suppress_embeds.

Warning

Since API v10, the attachments (when passed) must contain all attachments that should be present after edit, including retained and new attachments.

As this requires to know the current attachments consider either storing the attachments that were sent with a message or using a fetched version of the message to edit it.

Parameters:

  • content (Optional[str]) – The new content to replace the message with. Could be None to remove the content.

  • embed (Optional[Embed]) – The new embed to replace the original with. Could be None to remove all embeds.

  • embeds (Optional[List[Embed]]) –

    A list containing up to 10 embeds to send. If None or empty, all embeds will be removed.

    If passed, embed does also count towards the limit of 10 embeds.

  • components (List[Union[ActionRow, List[Union[Button, Select]]]]) – A list of up to five ActionRow`s or :class:`list, each containing up to five Button or one Select like object.

  • attachments (List[Union[Attachment, File]]) –

    A list containing previous attachments to keep as well as new files to upload.

    When None or empty, all attachment will be removed.

    Note

    New files will always appear under existing ones.

  • suppress_embeds (bool) – Whether to suppress embeds for the message. This removes all the embeds if set to True. If set to False this brings the embeds back if they were suppressed. Requires manage_messages for messages that aren’t from the bot.

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

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

Raises:

  • NotFound – The message was not found.

  • HTTPException – Editing the message failed.

  • Forbidden – Tried to suppress the embeds a message without permissions or edited a message’s content or embed that isn’t yours.

Returns:

The message that was edited.

Return type:

Optional[Message]

Intents

Attributes
Methods
class discord.Intents(**kwargs)

Bases: BaseFlags

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.

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.

Added in version 1.5.

x == y

Checks if two flags are equal.

x != y

Checks if two flags are not equal.

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.

value

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

Type:

int

classmethod all()

A factory method that creates a Intents with everything enabled.

classmethod none()

A factory method that creates a Intents with everything disabled.

classmethod default()

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

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

bans

Whether guild ban 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

emojis

Whether guild emoji related events are enabled.

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:

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:

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

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 message 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 and direct message 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 guild and 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

message_content

Whether to receive the content, embeds, attachments and components of a message.

Note

The bot will still receive these fields when the message is in a privat chat with the bot, or the bot is mentioned in the message.

This corresponds to the following events:

This also corresponds to the following attributes and classes:

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

scheduled_events

Whether to receive events related to creating, updating and deleting scheduled events. Also, whether to receive events when a user is added or removed (interested).

This corresponds to the following events:

Type:

bool

auto_moderation_configurations

Whether to receive events related to creating, updating and deleting auto moderation rules.

This corresponds to the following events:

  • on_auto_moderation_rule_create()

  • on_auto_moderation_rule_update()

  • on_auto_moderation_rule_delete()

Type:

bool

auto_moderation_actions

Whether to receive events when auto moderation actions are taken.

This corresponds to the following event:

  • on_auto_moderation_action()

Type:

bool

MemberCacheFlags

Attributes
Methods
class discord.MemberCacheFlags(**kwargs)

Bases: BaseFlags

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.

The default value is all flags enabled.

Added in version 1.5.

x == y

Checks if two flags are equal.

x != y

Checks if two flags are not equal.

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.

value

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

Type:

int

classmethod all()

A factory method that creates a MemberCacheFlags with everything enabled.

classmethod none()

A factory method that creates a MemberCacheFlags with everything disabled.

online

Whether to cache members with a status.

For example, members that are part of the initial GUILD_CREATE or become online at a later point. This requires Intents.presences.

Members that go offline are no longer cached.

Type:

bool

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)

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

File

Attributes
class discord.File(fp, filename=None, description=None, *, spoiler=False, duration=None, waveform=None)

Bases: object

A parameter object used for abc.Messageable.send() for sending file objects.

Note

File objects are single use and are not meant to be reused in multiple abc.Messageable.send()s.

fp

A file-like object opened in binary mode and read mode or a filename representing a file in the hard drive to open.

Note

If the file-like object passed is opened via open then the modes ‘rb’ should be used.

To pass binary data, consider usage of io.BytesIO.

Type:

Union[str, io.BufferedIOBase]

filename

The filename to display when uploading to Discord. If this is not given then it defaults to fp.name or if fp is a string then the filename will default to the string given.

Type:

Optional[str]

spoiler

Whether the attachment is a spoiler.

Type:

bool

description

The file description can be set to attached images to show a alternative text.

Type:

Optional[str:]

ForumTag

Attributes
class discord.ForumTag

Bases: Hashable

Represents a tag in a ForumChannel.

Note

The id and guild attributes are only available if the instance is not self created.

id

The ID of the tag

Type:

int

guild

The guild the tag belongs to.

Type:

Guild

name

The name of the tag.

Type:

str

emoji_id

The ID of the custom-emoji the tag uses if any.

Type:

int

emoji_name

The default-emoji the tag uses if any.

Type:

str

moderated

Whether only moderators can apply this tag to a post.

Type:

bool

property emoji

The emoji that is set for this post, if any

Type:

Optional[PartialEmoji]

Colour

Attributes
Methods
class discord.Colour(value)

Bases: object

Represents a Discord role colour. This class is similar to a (red, green, blue) tuple.

There is an alias for this called Color.

x == y

Checks if two colours are equal.

x != y

Checks if two colours are not equal.

hash(x)

Return the colour’s hash.

str(x)

Returns the hex format for the colour.

value

The raw integer colour value.

Type:

int

property r

Returns the red component of the colour.

Type:

int

property g

Returns the green component of the colour.

Type:

int

property b

Returns the blue component of the colour.

Type:

int

to_rgb()

Tuple[int, int, int]: Returns an (r, g, b) tuple representing the colour.

classmethod from_rgb(r, g, b)

Constructs a Colour from an RGB tuple.

classmethod from_hsv(h, s, v)

Constructs a Colour from an HSV tuple.

classmethod default()

A factory method that returns a Colour with a value of 0.

classmethod random(*, seed=None)

A factory method that returns a Colour with a random hue.

Note

The random algorithm works by choosing a colour with a random hue but with maxed out saturation and value.

Added in version 1.6.

Parameters:

seed (Optional[Union[int, str, float, bytes, bytearray]]) –

The seed to initialize the RNG with. If None is passed the default RNG is used.

Added in version 1.7.

classmethod teal()

A factory method that returns a Colour with a value of 0x1abc9c.

classmethod dark_teal()

A factory method that returns a Colour with a value of 0x11806a.

classmethod green()

A factory method that returns a Colour with a value of 0x2ecc71.

classmethod dark_green()

A factory method that returns a Colour with a value of 0x1f8b4c.

classmethod blue()

A factory method that returns a Colour with a value of 0x3498db.

classmethod dark_blue()

A factory method that returns a Colour with a value of 0x206694.

classmethod purple()

A factory method that returns a Colour with a value of 0x9b59b6.

classmethod dark_purple()

A factory method that returns a Colour with a value of 0x71368a.

classmethod magenta()

A factory method that returns a Colour with a value of 0xe91e63.

classmethod dark_magenta()

A factory method that returns a Colour with a value of 0xad1457.

classmethod gold()

A factory method that returns a Colour with a value of 0xf1c40f.

classmethod dark_gold()

A factory method that returns a Colour with a value of 0xc27c0e.

classmethod orange()

A factory method that returns a Colour with a value of 0xe67e22.

classmethod dark_orange()

A factory method that returns a Colour with a value of 0xa84300.

classmethod red()

A factory method that returns a Colour with a value of 0xe74c3c.

classmethod dark_red()

A factory method that returns a Colour with a value of 0x992d22.

classmethod lighter_grey()

A factory method that returns a Colour with a value of 0x95a5a6.

classmethod lighter_gray()

A factory method that returns a Colour with a value of 0x95a5a6.

classmethod dark_grey()

A factory method that returns a Colour with a value of 0x607d8b.

classmethod dark_gray()

A factory method that returns a Colour with a value of 0x607d8b.

classmethod light_grey()

A factory method that returns a Colour with a value of 0x979c9f.

classmethod light_gray()

A factory method that returns a Colour with a value of 0x979c9f.

classmethod darker_grey()

A factory method that returns a Colour with a value of 0x546e7a.

classmethod darker_gray()

A factory method that returns a Colour with a value of 0x546e7a.

classmethod blurple()

A factory method that returns a Colour with a value of 0x7289da.

classmethod greyple()

A factory method that returns a Colour with a value of 0x99aab5.

classmethod dark_theme()

A factory method that returns a Colour with a value of 0x36393F. This will appear transparent on Discord’s dark theme.

Added in version 1.5.

BaseActivity

Attributes
class discord.BaseActivity(**kwargs)

Bases: object

The base activity that all user-settable activities inherit from. A user-settable activity is one that can be used in Client.change_presence().

The following types currently count as user-settable:

Note that although these types are considered user-settable by the library, Discord typically ignores certain combinations of activity depending on what is currently set. This behaviour may change in the future so there are no guarantees on whether Discord will actually let you set these types.

Added in version 1.3.

property created_at

When the user started doing this activity in UTC.

Added in version 1.3.

Type:

Optional[datetime.datetime]

Activity

Attributes
class discord.Activity(**kwargs)

Bases: BaseActivity

Represents an activity in Discord.

This could be an activity such as streaming, playing, listening or watching.

For memory optimisation purposes, some activities are offered in slimmed down versions:

application_id

The application ID of the game.

Type:

int

name

The name of the activity.

Type:

str

url

A stream URL that the activity could be doing.

Type:

str

type

The type of activity currently being done.

Type:

ActivityType

state

The user’s current state. For example, “In Game”.

Type:

str

details

The detail of the user’s current activity.

Type:

str

timestamps

A dictionary of timestamps. It contains the following optional keys:

  • start: Corresponds to when the user started doing the activity in milliseconds since Unix epoch.

  • end: Corresponds to when the user will finish doing the activity in milliseconds since Unix epoch.

Type:

dict

assets

A dictionary representing the images and their hover text of an activity. It contains the following optional keys:

  • large_image: A string representing the ID for the large image asset.

  • large_text: A string representing the text when hovering over the large image asset.

  • small_image: A string representing the ID for the small image asset.

  • small_text: A string representing the text when hovering over the small image asset.

Type:

dict

party

A dictionary representing the activity party. It contains the following optional keys:

  • id: A string representing the party ID.

  • size: A list of up to two integer elements denoting (current_size, maximum_size).

Type:

dict

emoji

The emoji that belongs to this activity.

Type:

Optional[PartialEmoji]

buttons

A list of dictionaries representing custom buttons shown in a rich presence. Each dictionary contains the following keys:

  • label: A string representing the text shown on the button.

  • url: A string representing the URL opened upon clicking the button.

Note

Bots cannot access a user’s activity button URLs. Therefore, the type of this attribute will be List[str] when received through the gateway.

Added in version 2.0.

Type:

Union[List[Dict[str, str]], List[str]]

property start

When the user started doing this activity in UTC, if applicable.

Type:

Optional[datetime.datetime]

property end

When the user will stop doing this activity in UTC, if applicable.

Type:

Optional[datetime.datetime]

property large_image_url

Returns a URL pointing to the large image asset of this activity if applicable.

Type:

Optional[str]

property small_image_url

Returns a URL pointing to the small image asset of this activity if applicable.

Type:

Optional[str]

property large_image_text

Returns the large image asset hover text of this activity if applicable.

Type:

Optional[str]

property small_image_text

Returns the small image asset hover text of this activity if applicable.

Type:

Optional[str]

Game

Attributes
class discord.Game(name, **extra)

Bases: BaseActivity

A slimmed down version of Activity that represents a Discord game.

This is typically displayed via Playing on the official Discord client.

x == y

Checks if two games are equal.

x != y

Checks if two games are not equal.

hash(x)

Returns the game’s hash.

str(x)

Returns the game’s name.

Parameters:

  • name (str) – The game’s name.

  • start (Optional[datetime.datetime]) – A naive UTC timestamp representing when the game started. Keyword-only parameter. Ignored for bots.

  • end (Optional[datetime.datetime]) – A naive UTC timestamp representing when the game ends. Keyword-only parameter. Ignored for bots.

name

The game’s name.

Type:

str

property type

Returns the game’s type. This is for compatibility with Activity.

It always returns ActivityType.playing.

Type:

ActivityType

property start

When the user started playing this game in UTC, if applicable.

Type:

Optional[datetime.datetime]

property end

When the user will stop playing this game in UTC, if applicable.

Type:

Optional[datetime.datetime]

Streaming

Attributes
class discord.Streaming(*, name, url, **extra)

Bases: BaseActivity

A slimmed down version of Activity that represents a Discord streaming status.

This is typically displayed via Streaming on the official Discord client.

x == y

Checks if two streams are equal.

x != y

Checks if two streams are not equal.

hash(x)

Returns the stream’s hash.

str(x)

Returns the stream’s name.

platform

Where the user is streaming from (ie. YouTube, Twitch).

Added in version 1.3.

Type:

str

name

The stream’s name.

Type:

Optional[str]

details

An alias for name

Type:

Optional[str]

game

The game being streamed.

Added in version 1.3.

Type:

Optional[str]

url

The stream’s URL.

Type:

str

assets

A dictionary comprising similar keys than those in Activity.assets.

Type:

dict

property type

Returns the game’s type. This is for compatibility with Activity.

It always returns ActivityType.streaming.

Type:

ActivityType

property twitch_name

If provided, the twitch name of the user streaming.

This corresponds to the large_image key of the Streaming.assets dictionary if it starts with twitch:. Typically set by the Discord client.

Type:

Optional[str]

CustomActivity

Attributes
class discord.CustomActivity(name, *, emoji=None, **extra)

Bases: BaseActivity

Represents a Custom activity from Discord.

x == y

Checks if two activities are equal.

x != y

Checks if two activities are not equal.

hash(x)

Returns the activity’s hash.

str(x)

Returns the custom status text.

Added in version 1.3.

name

The custom activity’s name.

Type:

Optional[str]

emoji

The emoji to pass to the activity, if any.

Type:

Optional[PartialEmoji]

property type

Returns the activity’s type. This is for compatibility with Activity.

It always returns ActivityType.custom.

Type:

ActivityType

Permissions

Attributes
Methods
class discord.Permissions(permissions=0, **kwargs)

Bases: BaseFlags

Wraps up the Discord permission value.

The properties provided are two-way. You can set and retrieve individual bits using the properties as if they were regular bools. This allows you to edit permissions.

Changed in version 1.3: You can now use keyword arguments to initialize Permissions similar to update().

x == y

Checks if two permissions are equal.

x != y

Checks if two permissions are not equal.

x <= y

Checks if a permission is a subset of another permission.

x >= y

Checks if a permission is a superset of another permission.

x < y

Checks if a permission is a strict subset of another permission.

x > y

Checks if a permission is a strict superset of another permission.

hash(x)

Return the permission’s hash.

iter(x)

Returns an iterator of (perm, value) pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown.

value

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

Type:

int

is_subset(other)

Returns True if self has the same or fewer permissions as other.

is_superset(other)

Returns True if self has the same or more permissions as other.

is_strict_subset(other)

Returns True if the permissions on other are a strict subset of those on self.

is_strict_superset(other)

Returns True if the permissions on other are a strict superset of those on self.

classmethod none()

A factory method that creates a Permissions with all permissions set to False.

classmethod all()

A factory method that creates a Permissions with all permissions set to True.

classmethod all_channel()

A Permissions with all channel-specific permissions set to True and the guild-specific ones set to False. The guild-specific permissions are currently:

Changed in version 1.7: Added stream, priority_speaker and use_slash_commands permissions.

Changed in version 2.0: Added start_embedded_activities, moderate_members, manage_events, create_private_threads, create_puplic_threads, manage_threads, send_messages_in_threads, request_to_speak and use_external_stickers

classmethod general()

A factory method that creates a Permissions with all “General” permissions from the official Discord UI set to True.

Changed in version 1.7: Permission read_messages is now included in the general permissions, but permissions administrator, create_instant_invite, kick_members, ban_members, change_nickname and manage_nicknames are no longer part of the general permissions.

Changed in version 2.0: Added moderate_members, manage_expressions and create_expressions permission.

classmethod membership()

A factory method that creates a Permissions with all “Membership” permissions from the official Discord UI set to True.

Added in version 1.7.

Changed in version 2.0: Added moderate_members permission.

classmethod text()

A factory method that creates a Permissions with all “Text” permissions from the official Discord UI set to True.

Changed in version 1.7: Permission read_messages is no longer part of the text permissions. Added use_slash_commands permission.

Changed in version 2.0: Added send_voice_messages, manage_threads, create_public_threads, create_private_threads, send_messages_in_threads and use_external_stickers permission.

classmethod voice()

A factory method that creates a Permissions with all “Voice” permissions from the official Discord UI set to True.

Changed in version 2.0: Added start_embedded_activities, use_soundboard use_external_sounds and set_voice_channel_status permission.

classmethod stage()

A factory method that creates a Permissions with all “Stage Channel” permissions from the official Discord UI set to True.

Added in version 1.7.

classmethod stage_moderator()

A factory method that creates a Permissions with all “Stage Moderator” permissions from the official Discord UI set to True.

Added in version 1.7.

classmethod events()

A factory method that creates a Permissions with all “Events” permissions from the official Discord UI set to True.

Added in version 2.0.

classmethod advanced()

A factory method that creates a Permissions with all “Advanced” permissions from the official Discord UI set to True.

Added in version 1.7.

update(**kwargs)

Bulk updates this permission object.

Allows you to set multiple attributes by using keyword arguments. The names must be equivalent to the properties listed. Extraneous key/value pairs will be silently ignored.

Parameters:

**kwargs – A list of key/value pairs to bulk update permissions with.

create_instant_invite

Returns True if the user can create instant invites.

Type:

bool

kick_members

Returns True if the user can kick users from the guild.

Type:

bool

ban_members

Returns True if a user can ban users from the guild.

Type:

bool

administrator

Returns True if a user is an administrator. This role overrides all other permissions.

This also bypasses all channel-specific overrides.

Type:

bool

manage_channels

Returns True if a user can edit, delete, or create channels in the guild.

This also corresponds to the “Manage Channel” channel-specific override.

Type:

bool

manage_guild

Returns True if a user can edit guild properties.

Type:

bool

add_reactions

Returns True if a user can add reactions to messages.

Type:

bool

view_audit_log

Returns True if a user can view the guild’s audit log.

Type:

bool

priority_speaker

Returns True if a user can be more easily heard while talking.

Type:

bool

stream

Returns True if a user can stream in a voice channel.

Type:

bool

read_messages

Returns True if a user can read messages from all or specific text channels.

Type:

bool

view_channel

An alias for read_messages.

Added in version 1.3.

Type:

bool

send_messages

Returns True if a user can send messages from all or specific text channels and create posts in forum channels.

Type:

bool

create_posts

An alias for send_messages.

Added in version 2.0.

Type:

bool

send_tts_messages

Returns True if a user can send TTS messages from all or specific text channels.

Type:

bool

manage_messages

Returns True if a user can delete or pin messages in a text channel.

Note

Note that there are currently no ways to edit other people’s messages.

Type:

bool

Returns True if a user’s messages will automatically be embedded by Discord.

Type:

bool

attach_files

Returns True if a user can send files in their messages.

Type:

bool

read_message_history

Returns True if a user can read a text channel’s previous messages.

Type:

bool

mention_everyone

Returns True if a user’s @everyone or @here will mention everyone in the text channel.

Type:

bool

external_emojis

Returns True if a user can use emojis from other guilds.

Type:

bool

use_external_emojis

An alias for external_emojis.

Added in version 1.3.

Type:

bool

view_guild_insights

Returns True if a user can view the guild’s insights.

Added in version 1.3.

Type:

bool

connect

Returns True if a user can connect to a voice channel.

Type:

bool

speak

Returns True if a user can speak in a voice channel.

Type:

bool

mute_members

Returns True if a user can mute other users.

Type:

bool

deafen_members

Returns True if a user can deafen other users.

Type:

bool

move_members

Returns True if a user can move users between other voice channels.

Type:

bool

use_voice_activation

Returns True if a user can use voice activation in voice channels.

Type:

bool

change_nickname

Returns True if a user can change their nickname in the guild.

Type:

bool

manage_nicknames

Returns True if a user can change other user’s nickname in the guild.

Type:

bool

manage_roles

Returns True if a user can create or edit roles less than their role’s position.

This also corresponds to the “Manage Permissions” channel-specific override.

Type:

bool

manage_permissions

An alias for manage_roles.

Added in version 1.3.

Type:

bool

manage_webhooks

Returns True if a user can create, edit, or delete webhooks.

Type:

bool

manage_expressions

Returns True if a user can create, edit, or delete emojis, stickers and sounds.

Type:

bool

manage_emojis

An aliase for manage_expressions

Type:

bool

manage_stickers

An aliase for manage_expressions

Type:

bool

manage_emojis_and_stickers

An aliase for manage_expressions

Type:

bool

manage_sounds

An aliase for manage_expressions

Type:

bool

create_expressions

Returns True if a user can create emojis, stickers or sounds in a server.

Added in version 2.0.

Type:

bool

create_emojis

An aliase for create_expressions

Type:

bool

create_stickers

An aliase for create_expressions

Type:

bool

create_sounds

An aliase for create_expressions

Type:

bool

use_application_commands

Returns True if a user can use application commands.

Added in version 1.7.

Type:

bool

use_slash_commands

An aliase for use_application_commands

Type:

bool

request_to_speak

Returns True if a user can request to speak in a stage channel.

Added in version 1.7.

Type:

bool

manage_events

Returns True if a user can create and manage Guild-Scheduled-Events.

Added in version 2.0.

Type:

bool

create_events

Returns True if a user can create Guild-Scheduled-Events.

Added in version 2.0.

Type:

bool

manage_threads

Returns True if a user can delete and archive threads and viewing all private threads.

Added in version 2.0.

Type:

bool

create_public_threads

Returns True if a user can create and participate in threads.

Added in version 2.0.

Type:

bool

create_private_threads

Returns True if a user can create and participate in private threads.

Added in version 2.0.

Type:

bool

use_external_stickers

Returns True if a user can use custom stickers from other servers.

Added in version 2.0.

Type:

bool

send_messages_in_threads

Returns True if a user can send messages in threads and forum posts.

Added in version 2.0.

Type:

bool

send_messages_in_posts

An alias for send_messages_in_threads.

Type:

bool

send_thread_messages

An alias for send_messages_in_threads.

Type:

bool

start_embedded_activities

Returns True if a user can start embedded activities in a voice channel (e.g. voice-activities).

Added in version 2.0.

Type:

bool

start_voice_activities

An alias for start_embedded_activities.

Type:

bool

moderate_members

Returns True if a user can moderate other members (like timeout or verify them).

Added in version 2.0.

Type:

bool

timeout_members

An alias for moderate_members.

Type:

bool

view_creator_monetization_analytics

Returns True if a user can view analytics for monetization of their content.

Added in version 2.0.

Type:

bool

use_soundboard

Returns True if a user can use the soundboard in a voice channel.

Added in version 2.0.

Type:

bool

use_external_sounds

Returns True if a user can use custom soundboard sounds from other servers.

Added in version 2.0.

Type:

bool

send_voice_messages

Returns True if a user can send voice messages.

Added in version 2.0.

Type:

bool

set_voice_channel_status

Returns True if a user can set the status of a voice channel.

Added in version 2.0.

Type:

bool

PermissionOverwrite

Methods
class discord.PermissionOverwrite(**kwargs)

Bases: object

A type that is used to represent a channel specific permission.

Unlike a regular Permissions, the default value of a permission is equivalent to None and not False. Setting a value to False is explicitly denying that permission, while setting a value to True is explicitly allowing that permission.

The values supported by this are the same as Permissions with the added possibility of it being set to None.

x == y

Checks if two overwrites are equal.

x != y

Checks if two overwrites are not equal.

iter(x) - (for ... in x: ...)

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

Note that aliases are not shown.

pair()

Tuple[Permissions, Permissions]: Returns the (allow, deny) pair from this overwrite.

classmethod from_pair(allow, deny)

Creates an overwrite from an allow/deny pair of Permissions.

is_empty()

Checks if the permission overwrite is currently empty.

An empty permission overwrite is one that has no overwrites set to True or False.

Returns:

Indicates if the overwrite is empty.

Return type:

bool

update(**kwargs)

Bulk updates this permission overwrite object.

Allows you to set multiple attributes by using keyword arguments. The names must be equivalent to the properties listed. Extraneous key/value pairs will be silently ignored.

Parameters:

**kwargs – A list of key/value pairs to bulk update with.

ShardInfo

Attributes
Methods
class discord.ShardInfo

Bases: object

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

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

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

bool: Whether the shard connection is currently closed.

await disconnect()

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

This function is a coroutine.

Disconnects and then connects the shard again.

await connect()

This function is a coroutine.

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

property latency

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

Type:

float

is_ws_ratelimited()

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

Added in version 1.6.

SystemChannelFlags

Attributes
class discord.SystemChannelFlags

Bases: BaseFlags

Wraps up a Discord system channel flag value.

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. This allows you to edit the system flags easily.

To construct an object you can pass keyword arguments denoting the flags to enable or disable.

x == y

Checks if two flags are equal.

x != y

Checks if two flags are not equal.

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.

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

join_notifications

Returns True if the system channel is used for member join notifications.

Type:

bool

premium_subscriptions

Returns True if the system channel is used for Nitro boosting notifications.

Type:

bool

guild_reminder_notifications

Returns True if the system channel is used for server setup tips.

Type:

bool

join_notification_replies

Returns True if sticker reply buttons should show under member join messages.

Type:

bool

role_subscription_purchase_notifications

Returns True if the system channel is used for role subscription purchase and renewal notifications.

Type:

bool

role_subscription_purchase_notification_replies

Returns True if sticker reply buttons should show under role subscription purchase and renewal messages.

Type:

bool

ChannelFlags

Attributes
class discord.ChannelFlags

Bases: BaseFlags

Wraps up a Discord Channel flag value

removed_from_guild_feed

Returns True if the channel is removed from the guild’s home feed/from highlights.

Type:

bool

removed_from_home

An alias to removed_from_guild_feed.

Type:

bool

pinned

Returns True if the channel is a ForumPost pinned at the top of the parent forum.

Type:

bool

removed_from_active_now

Returns True if the channel is removed from the active now section in the guild’s feed.

Type:

bool

require_tags

bool: Returns True if this channel is a ForumChannel that requires at least one tag when creating a post.

is_spam

Returns True if the channel is marked as spam.

Type:

bool

is_resource_channel

Returns True if the channel is a resource channel.

Type:

bool

clyde_ai

Returns True if clyde has access to this thread.

Experimental Discord Feature - Clyde, Discord’s AI Chatbot

This is an experimental feature and may be removed at any time.

For more information, take a look at the support article

Type:

bool

is_media_channel

Returns True if the channel is a media channel.

Type:

bool

summaries_disabled

Returns True if AI summaries are disabled for this channel.

Experimental Discord Feature - AI powered summaries

This is an experimental feature and may be removed at any time.

For more information, take a look at the support article

Type:

bool

is_role_subscription_template_preview_channel

Returns True if the channel is part of a role subscription template preview.

Experimental Discord Feature - Role Subscription Template

This is an experimental feature and may be removed at any time.

Type:

bool

MessageFlags

Attributes
class discord.MessageFlags

Bases: BaseFlags

Wraps up a Discord Message flag value.

See SystemChannelFlags.

x == y

Checks if two flags are equal.

x != y

Checks if two flags are not equal.

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.

Added in version 1.3.

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

crossposted

Returns True if the message is the original crossposted message.

Type:

bool

is_crossposted

Returns True if the message was crossposted from another channel.

Type:

bool

suppress_embeds

Returns True if the message’s embeds have been suppressed.

Type:

bool

source_message_deleted

Returns True if the source message for this crosspost has been deleted.

Type:

bool

urgent

Returns True if the source message is an urgent message.

An urgent message is one sent by Discord Trust and Safety.

Type:

bool

has_thread

Returns True if the source message is associated with a thread.

This message has an associated thread, with the same id as the message.

Type:

bool

ephemeral

Returns True if the message ist ephemeral (hidden).

This message is only visible to the user who invoked the Interaction.

Type:

bool

loading

Returns True if the message is an interaction response and the bot is “thinking”.

This message is an interaction response and the bot is “thinking”

Type:

bool

failed_to_mention_some_roles_in_thread

Returns True if the message failed to mention some roles and add their members to the thread.

Type:

bool

Returns True if the message should show a warning that the link may not be safe.

Note

Although this gets set by Discord for some embeds, and we receive a on_message_edit() event, it is not officially documented by Discord. It’s in the client but not used anywhere.

Type:

bool

suppress_notifications

Returns True if the message is “silent”.

The user(s) will still see a mention in the channel, but no push or desktop notification will be sent.

Type:

bool

is_voice_message

Returns True if the message is a voice message.

Type:

bool

PublicUserFlags

Attributes
Methods
class discord.PublicUserFlags

Bases: BaseFlags

Wraps up the Discord User Public flags.

x == y

Checks if two PublicUserFlags are equal.

x != y

Checks if two PublicUserFlags are not equal.

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.

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

Added in version 1.5.

Type:

bool

certified_moderator

Returns True if the user is an Discord Certified Moderator.

Type:

bool

bot_http_interactions

Returns True if a bot-user uses only HTTP interactions and is shown in the online member list

Type:

bool

spammer

Returns True if the user is flagged as a spammer by discord.

Type:

bool

active_developer

Returns True if the user is a developer of an active discord application.

Type:

bool

all()

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

AutoModAction

Attributes
class discord.AutoModAction

Bases: object

Represents an action which will execute whenever a rule is triggered.

type

The type of action

Type:

AutoModActionType

channel_id

The channel to which target user content should be logged.

Note

This field is only present if type is send_alert_message

Type:

int

timeout_duration

Duration in seconds (int) or a timerange (timedelta) for wich the target user should be timeouted.

The maximum value is 2419200 seconds (4 weeks)

Note

This field is only present if type is timeout_user

Type:

Union[int, timedelta]

custom_message

Additional explanation that will be shown to target users whenever their message is blocked. Max 150 characters

Note

This field might only be present if type is block_message

Type:

Optional[str]

Parameters:

  • type (AutoModActionType) – The type of action

  • channel_id (int) –

    The channel to which target user content should be logged.

    Note

    This field is only required if type is send_alert_message

  • timeout_duration (Union[int, datetime.timedelta]) –

    Duration in seconds (int) or a timerange (timedelta) for wich the user should be timeouted.

    The maximum value is 2419200 seconds (4 weeks)

    Note

    This field is only required if type is timeout_user

  • custom_message (Optional[str]) –

    Additional explanation that will be shown to target users whenever their message is blocked. Max 150 characters

    Note

    This field is only allowed if type is block_message

Raises:

  • TypeError – If the type is send_alert_message and no channel_id is provided, or if the type is timeout_user and no timeout_duration is provided.

  • ValueError – If the custom_message is longer than 150 characters, or if the timeout_duration is longer than 4 weeks.

AutoModTriggerMetadata

Attributes
class discord.AutoModTriggerMetadata

Bases: object

Additional data used to determine whether a rule should be triggered. Different fields are relevant based on the value of AutoModRule.trigger_type

Parameters:

  • keyword_filter (Optional[List[str]]) –

    Substrings which will be searched for in content

    Note

    This field is only present if trigger_type is AutoModTriggerType.keyword

  • presets (Optional[List[AutoModKeywordPresetType]]) –

    The internally pre-defined word sets which will be searched for in content

    Note

    This field is only present if trigger_type is AutoModTriggerType.keyword_preset

  • exempt_words (Optional[List[str]]) –

    Substrings which should be excluded from the blacklist.

    Note

    This field is only present if trigger_type is AutoModTriggerType.keyword_preset

  • total_mentions_limit (Optional[int]) –

    Total number of unique role and user mentions allowed per message (Maximum of 50)

    Note

    This field is only present if trigger_type is AutoModTriggerType.mention_spam

  • mention_raid_protection_enabled (Optional[bool]) –

    Whether to automatically detect mention raids

    Note

    This field is only present if trigger_type is AutoModTriggerType.mention_spam

Additional data used to determine whether a rule should be triggered. Different fields are relevant based on the value of AutoModRule.trigger_type

Parameters:

  • keyword_filter (Optional[List[str]]) –

    Substrings which will be searched for in content

    Note

    This field is only allowed if trigger_type is keyword

  • regex_patterns (Optional[List[Union[str, :class`~re.Pattern`]]]) –

    Regular expression patterns which will be matched against content (Maximum of 10, each max. 260 characters long)

    Warning

    Only <Rust https://docs.rs/regex/latest/regex/>_ flowered RegEx patterns are currently supported by Discord. So things like lookarounds are not allowed as they are not supported in Rust.

    Note

    This field is only allowed if trigger_type is keyword

  • presets (Optional[List[AutoModKeywordPresetType]]) –

    The internally pre-defined word sets which will be searched for in content

    Note

    This field is only required if trigger_type is keyword_preset

  • exempt_words (Optional[List[str]]) –

    Substrings which should be excluded from the blacklist.

    Note

    This field is only allowed if trigger_type is keyword_preset keyword

  • total_mentions_limit (Optional[int]) –

    Total number of unique role and user mentions allowed per message (Maximum of 50)

    Note

    This field is only allowed if trigger_type is AutoModTriggerType.mention_spam

  • mention_raid_protection_enabled (Optional[bool]) –

    Whether to automatically detect mention raids

    Note

    This field is only allowed if trigger_type is AutoModTriggerType.mention_spam

Raises:

TypeError – Both of keyword_filter and presets was passed

regex_patterns

The compiled regex patterns for this rule, if any.

Type:

List[Pattern]

property prefix_keywords

Returns all keywords for words that must start with the keyword.

Note

This is equal to

for keyword in self.keyword_filter:
    if keyword[0] != '*' and keyword[-1] == '*':
        yield keyword
Yields:

str – A keyword

property suffix_keywords

Returns all keywords for words that must end with the keyword.

Note

This is equal to

for keyword in self.keyword_filter:
    if keyword[0] == '*' and keyword[-1] != '*':
        yield keyword
Yields:

str – A keyword

property anywhere_keywords

Returns all keywords which can appear anywhere in a word

Note

This is equal to

for keyword in self.keyword_filter:
    if keyword[0] == '*' and keyword[-1] == '*':
        yield keyword
Yields:

str – A keyword

property whole_word_keywords

Returns all keywords that must occur as a whole in a word or phrase and must be surrounded by spaces.

Note

This is equal to

for keyword in self.keyword_filter:
    if keyword[0] != '*' and keyword[-1] != '*':
        yield keyword
Yields:

str – A keyword

WelcomeScreenChannel

Attributes
class discord.WelcomeScreenChannel

Bases: object

Represents a channel shown in a welcome screen.

channel

The channel the welcome screen channel belongs to

Type:

Snowflake

description

The description of the welcome screen channel

Type:

str

emoji

The emoji that is shown on the left side of the welcome screen channel

Type:

Optional[PartialEmoji]

Represents a channel shown in a welcome screen.

Parameters:

  • channel (Snowflake) – The channel the welcome screen channel belongs to

  • description (str) – The description of the welcome screen channel

  • emoji (Optional[Union[PartialEmoji, str]) – The emoji that is shown on the left side of the welcome screen channel