API Reference ¶

await fetch_guild_preview(guild_id, /)¶

This function is a coroutine.

Retrieves a public Guild preview from an ID.

New in version 2.0.

Raises

NotFound – Guild with given ID does not exist/is not public.
HTTPException – Retrieving the guild failed.

Returns

The guild from the ID.

Return type

await create_guild(name, icon=..., code=...)¶

This function is a coroutine.

Creates a Guild.

Changed in version 2.0: name and icon parameters are now keyword-only. The region parameter has been removed.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

name (str) – The name of the guild.
icon (Optional[bytes]) – The bytes-like object representing the icon. See ClientUser.edit() for more details on what is expected.
code (str) –
The code for a template to create the guild with.

New in version 1.4.

Raises

HTTPException – Guild creation failed.
ValueError – Invalid icon image format given. Must be PNG or JPG.

Returns

The guild created. This is not the same guild that is added to cache.

Return type

await join_guild(guild_id, /, lurking=False)¶

This function is a coroutine.

Joins a discoverable Guild.

Parameters

guild_id (int) – The ID of the guild to join.
lurking (bool) – Whether to lurk the guild.

Raises

NotFound – Guild with given ID does not exist/have discovery enabled.
HTTPException – Joining the guild failed.

Returns

The guild that was joined.

Return type

await leave_guild(guild, /, lurking=...)¶

This function is a coroutine.

Leaves a guild. Equivalent to Guild.leave().

New in version 2.0.

Parameters

guild (Snowflake) – The guild to leave.
lurking (bool) – Whether you are lurking the guild.

Raises

HTTPException – Leaving the guild failed.

await fetch_stage_instance(channel_id, /)¶

This function is a coroutine.

Gets a StageInstance for a stage channel ID.

New in version 2.0.

Parameters

channel_id (int) – The stage channel ID.

Raises

NotFound – The stage instance or channel could not be found.
HTTPException – Getting the stage instance failed.

Returns

The stage instance from the stage channel ID.

Return type

StageInstance

await invites()¶

This function is a coroutine.

Gets a list of the user’s friend Invites.

New in version 2.0.

Raises: HTTPException – Getting the invites failed.
Returns: The list of invites.
Return type: List[Invite]

await fetch_invite(url, /, *, with_counts=True, scheduled_event_id=None)¶

This function is a coroutine.

Gets an Invite from a discord.gg URL or ID.

Note

If the invite is for a guild you have not joined, the guild and channel attributes of the returned Invite will be PartialInviteGuild and PartialInviteChannel respectively.

Changed in version 2.0: url parameter is now positional-only.

Changed in version 2.1: The with_expiration parameter has been removed.

Parameters

url (Union[Invite, str]) – The Discord invite ID or URL (must be a discord.gg URL).
with_counts (bool) – Whether to include count information in the invite. This fills the Invite.approximate_member_count and Invite.approximate_presence_count fields.
scheduled_event_id (Optional[int]) –
The ID of the scheduled event this invite is for.

Note

It is not possible to provide a url that contains an event_id parameter when using this parameter.

New in version 2.0.

Raises

ValueError – The url contains an event_id, but scheduled_event_id has also been provided.
NotFound – The invite has expired or is invalid.
HTTPException – Getting the invite failed.

Returns

The invite from the URL/ID.

Return type

await create_invite()¶

This function is a coroutine.

Creates a new friend Invite.

New in version 2.0.

Raises: HTTPException – Creating the invite failed.
Returns: The created friend invite.
Return type: Invite

await accept_invite(url, /)¶

This function is a coroutine.

Uses an invite. Either joins a guild, joins a group DM, or adds a friend.

New in version 2.0.

Parameters: url (Union[Invite, str]) – The Discord invite ID, URL (must be a discord.gg URL), or Invite.
Raises: HTTPException – Using the invite failed.
Returns: The accepted invite.
Return type: Invite

await delete_invite(invite, /)¶

This function is a coroutine.

Revokes an Invite, URL, or ID to an invite.

You must have manage_channels in the associated guild to do this.

Changed in version 2.0: invite parameter is now positional-only.

Changed in version 2.0: The function now returns the deleted invite.

Parameters

invite (Union[Invite, str]) – The invite to revoke.

Raises

Forbidden – You do not have permissions to revoke invites.
NotFound – The invite is invalid or expired.
HTTPException – Revoking the invite failed.

Returns

The deleted invite.

Return type

await revoke_invites()¶

This function is a coroutine.

Revokes all of the user’s friend Invites.

New in version 2.0.

Raises: HTTPException – Revoking the invites failed.
Returns: The revoked invites.
Return type: List[Invite]

await fetch_widget(guild_id, /)¶

This function is a coroutine.

Gets a Widget from a guild ID.

Note

The guild must have the widget enabled to get this information.

Changed in version 2.0: guild_id parameter is now positional-only.

Parameters

guild_id (int) – The ID of the guild.

Raises

Forbidden – The widget for this guild is disabled.
HTTPException – Retrieving the widget failed.

Returns

The guild’s widget.

Return type

Widget

await fetch_user(user_id, /)¶

This function is a coroutine.

Retrieves a discord.User based on their ID. You do not have to share any guilds with the user to get this information, however many operations do require that you do.

Note

This method is an API call. If you have member cache enabled, consider get_user() instead.

Changed in version 2.0: user_id parameter is now positional-only.

Parameters

user_id (int) – The user’s ID to fetch from.

Raises

NotFound – A user with this ID does not exist.
HTTPException – Fetching the user failed.

Returns

The user you requested.

Return type

discord.User

await fetch_user_named(*args)¶

This function is a coroutine.

Retrieves a discord.User based on their name or legacy username. You do not have to share any guilds with the user to get this information, however you must be able to add them as a friend.

This function can be used in multiple ways.

New in version 2.1.

# Passing a username
await client.fetch_user_named('jake')

# Passing a legacy user:
await client.fetch_user_named('Jake#0001')

# Passing a legacy username and discriminator:
await client.fetch_user_named('Jake', '0001')

Parameters

user (str) – The user to send the friend request to.
username (str) – The username of the user to send the friend request to.
discriminator (str) – The discriminator of the user to send the friend request to.

Raises

Forbidden – Not allowed to send a friend request to this user.
HTTPException – Fetching the user failed.
TypeError – More than 2 parameters or less than 1 parameter was passed.

Returns

The user you requested.

Return type

discord.User

await fetch_user_profile(user_id, /, *, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

Retrieves a UserProfile based on their user ID.

You must share a guild, be friends with this user, or have an incoming friend request from them to get this information (unless the user is a bot).

Changed in version 2.0: user_id parameter is now positional-only.

Parameters

user_id (int) – The ID of the user to fetch their profile for.
with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in UserProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in UserProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in UserProfile.mutual_friends and UserProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

NotFound – A user with this ID does not exist.
Forbidden – You do not have a mutual with this user, and and the user is not a bot.
HTTPException – Fetching the profile failed.

Returns

The profile of the user.

Return type

await fetch_channel(channel_id, /)¶

This function is a coroutine.

Retrieves a abc.GuildChannel, abc.PrivateChannel, or Thread with the specified ID.

Note

This method is an API call. For general usage, consider get_channel() instead.

New in version 1.2.

Changed in version 2.0: channel_id parameter is now positional-only.

Raises

InvalidData – An unknown channel type was received from Discord.
HTTPException – Retrieving the channel failed.
NotFound – Invalid Channel ID.
Forbidden – You do not have permission to fetch this channel.

Returns

The channel from the ID.

Return type

Union[abc.GuildChannel, abc.PrivateChannel, Thread]

await fetch_webhook(webhook_id, /)¶

This function is a coroutine.

Retrieves a Webhook with the specified ID.

Changed in version 2.0: webhook_id parameter is now positional-only.

Raises

HTTPException – Retrieving the webhook failed.
NotFound – Invalid webhook ID.
Forbidden – You do not have permission to fetch this webhook.

Returns

The webhook you requested.

Return type

await fetch_sticker(sticker_id, /)¶

This function is a coroutine.

Retrieves a Sticker with the specified ID.

New in version 2.0.

Raises

HTTPException – Retrieving the sticker failed.
NotFound – Invalid sticker ID.

Returns

The sticker you requested.

Return type

Union[StandardSticker, GuildSticker]

await sticker_packs()¶

This function is a coroutine.

Retrieves all available default sticker packs.

New in version 2.0.

Raises: HTTPException – Retrieving the sticker packs failed.
Returns: All available sticker packs.
Return type: List[StickerPack]

await fetch_sticker_pack(pack_id, /)¶

This function is a coroutine.

Retrieves a sticker pack with the specified ID.

New in version 2.0.

Raises

NotFound – A sticker pack with that ID was not found.
HTTPException – Retrieving the sticker packs failed.

Returns

The sticker pack you requested.

Return type

StickerPack

await notes()¶

This function is a coroutine.

Retrieves a list of Note objects representing all your notes.

New in version 1.9.

Raises: HTTPException – Retrieving the notes failed.
Returns: All your notes.
Return type: List[Note]

await fetch_note(user_id, /)¶

This function is a coroutine.

Retrieves a Note for the specified user ID.

New in version 1.9.

Changed in version 2.0: user_id parameter is now positional-only.

Parameters: user_id (int) – The ID of the user to fetch the note for.
Raises: HTTPException – Retrieving the note failed.
Returns: The note you requested.
Return type: Note

await fetch_connections()¶

This function is a coroutine.

Retrieves all of your connections.

New in version 2.0.

Raises: HTTPException – Retrieving your connections failed.
Returns: All your connections.
Return type: List[Connection]

await authorize_connection(type, two_way_link_type=None, two_way_user_code=None, continuation=False)¶

This function is a coroutine.

Retrieves a URL to authorize a connection with a third-party service.

New in version 2.0.

Parameters

type (ConnectionType) – The type of connection to authorize.
two_way_link_type (Optional[ClientType]) – The type of two-way link to use, if any.
two_way_user_code (Optional[str]) – The device code to use for two-way linking, if any.
continuation (bool) – Whether this is a continuation of a previous authorization.

Raises

HTTPException – Authorizing the connection failed.

Returns

The URL to redirect the user to.

Return type

await create_connection(type, code, state, *, two_way_link_code=None, insecure=True, friend_sync=...)¶

This function is a coroutine.

Creates a new connection.

This is a low-level method that requires data obtained from other APIs.

New in version 2.0.

Parameters

type (ConnectionType) – The type of connection to add.
code (str) – The authorization code for the connection.
state (str) – The state used to authorize the connection.
two_way_link_code (Optional[str]) – The code to use for two-way linking, if any.
insecure (bool) – Whether the authorization is insecure.
friend_sync (bool) –
Whether friends are synced over the connection.

Defaults to True for ConnectionType.facebook and ConnectionType.contacts, else False.

Raises

HTTPException – Creating the connection failed.

await fetch_private_channels()¶

This function is a coroutine.

Retrieves all your private channels.

New in version 2.0.

Note

This method is an API call. For general usage, consider private_channels instead.

Raises: HTTPException – Retrieving your private channels failed.
Returns: All your private channels.
Return type: List[abc.PrivateChannel]

await fetch_settings()¶

This function is a coroutine.

Retrieves your user settings.

New in version 2.0.

Note

This method is an API call. For general usage, consider settings instead.

Raises: HTTPException – Retrieving your settings failed.
Returns: The current settings for your account.
Return type: UserSettings

await legacy_settings()¶

This function is a coroutine.

Retrieves your legacy user settings.

New in version 2.0.

Deprecated since version 2.0.

Note

This method is no longer the recommended way to fetch your settings. Use fetch_settings() instead.

Note

This method is an API call. For general usage, consider settings instead.

Raises: HTTPException – Retrieving your settings failed.
Returns: The current settings for your account.
Return type: LegacyUserSettings

await email_settings()¶

This function is a coroutine.

Retrieves your email settings.

New in version 2.0.

Raises: HTTPException – Getting the email settings failed.
Returns: The email settings.
Return type: EmailSettings

await fetch_tracking_settings()¶

This function is a coroutine.

Retrieves your Discord tracking consents.

New in version 2.0.

Raises: HTTPException – Retrieving the tracking settings failed.
Returns: The tracking settings.
Return type: TrackingSettings

await edit_legacy_settings(**kwargs)¶

This function is a coroutine.

Edits the client user’s settings.

Changed in version 2.0: The edit is no longer in-place, instead the newly edited settings are returned.

Deprecated since version 2.0.

Parameters

activity_restricted_guilds (List[Snowflake]) –
A list of guilds that your current activity will not be shown in.

New in version 2.0.
activity_joining_restricted_guilds (List[Snowflake]) –
A list of guilds that will not be able to join your current activity.

New in version 2.0.
afk_timeout (int) – How long (in seconds) the user needs to be AFK until Discord sends push notifications to mobile device (30-600).
allow_accessibility_detection (bool) – Whether to allow Discord to track screen reader usage.
animate_emojis (bool) – Whether to animate emojis in the chat.
animate_stickers (StickerAnimationOptions) – Whether to animate stickers in the chat.
contact_sync_enabled (bool) – Whether to enable the contact sync on Discord mobile.
convert_emoticons (bool) – Whether to automatically convert emoticons into emojis (e.g. :) -> 😃).
default_guilds_restricted (bool) – Whether to automatically disable DMs between you and members of new guilds you join.
detect_platform_accounts (bool) – Whether to automatically detect accounts from services like Steam and Blizzard when you open the Discord client.
developer_mode (bool) – Whether to enable developer mode.
disable_games_tab (bool) – Whether to disable the showing of the Games tab.
enable_tts_command (bool) – Whether to allow TTS messages to be played/sent.
explicit_content_filter (UserContentFilter) – The filter for explicit content in all messages.
friend_source_flags (FriendSourceFlags) – Who can add you as a friend.
friend_discovery_flags (FriendDiscoveryFlags) – How you get recommended friends.
gif_auto_play (bool) – Whether to automatically play GIFs that are in the chat.
guild_positions (List[Snowflake]) – A list of guilds in order of the guild/guild icons that are on the left hand side of the UI.
inline_attachment_media (bool) – Whether to display attachments when they are uploaded in chat.
inline_embed_media (bool) – Whether to display videos and images from links posted in chat.
locale (Locale) – The RFC 3066 language identifier of the locale to use for the language of the Discord client.
message_display_compact (bool) – Whether to use the compact Discord display mode.
native_phone_integration_enabled (bool) – Whether to enable the new Discord mobile phone number friend requesting features.
passwordless (bool) – Whether to enable passwordless login.
render_embeds (bool) – Whether to render embeds that are sent in the chat.
render_reactions (bool) – Whether to render reactions that are added to messages.
restricted_guilds (List[Snowflake]) – A list of guilds that you will not receive DMs from.
show_current_game (bool) – Whether to display the game that you are currently playing.
stream_notifications_enabled (bool) – Whether stream notifications for friends will be received.
theme (Theme) – The overall theme of the Discord UI.
timezone_offset (int) – The timezone offset to use.
view_nsfw_commands (bool) –
Whether to show NSFW application commands in DMs.

New in version 2.0.
view_nsfw_guilds (bool) –
Whether to show NSFW guilds on iOS.

New in version 2.0.

Raises

HTTPException – Editing the settings failed.

Returns

The client user’s updated settings.

Return type

UserSettings

await fetch_relationships()¶

This function is a coroutine.

Retrieves all your relationships.

New in version 2.0.

Note

This method is an API call. For general usage, consider relationships instead.

Raises: HTTPException – Retrieving your relationships failed.
Returns: All your relationships.
Return type: List[Relationship]

await friend_suggestions()¶

This function is a coroutine.

Retrieves all your friend suggestions.

New in version 2.1.

Raises: HTTPException – Retrieving your friend suggestions failed.
Returns: All your current friend suggestions.
Return type: List[FriendSuggestion]

await fetch_country_code()¶

This function is a coroutine.

Retrieves the country code of the client.

New in version 2.0.

Raises: HTTPException – Retrieving the country code failed.
Returns: The country code of the client.
Return type: str

await fetch_preferred_voice_regions()¶

This function is a coroutine.

Retrieves the preferred voice regions of the client.

New in version 2.0.

Raises: HTTPException – Retrieving the preferred voice regions failed.
Returns: The preferred voice regions of the client.
Return type: List[str]

await create_dm(user, /)¶

This function is a coroutine.

Creates a DMChannel with this user.

This should be rarely called, as this is done transparently for most people.

New in version 2.0.

Parameters: user (Snowflake) – The user to create a DM with.
Returns: The channel that was created.
Return type: DMChannel

await create_group(*recipients)¶

This function is a coroutine.

Creates a group direct message with the recipients provided. These recipients must be have a relationship of type RelationshipType.friend.

New in version 2.0.

Parameters: *recipients (Snowflake) – An argument list of discord.User to have in your group.
Raises: HTTPException – Failed to create the group direct message.
Returns: The new group channel.
Return type: GroupChannel

await send_friend_request(*args)¶

This function is a coroutine.

Sends a friend request to another user.

This function can be used in multiple ways.

New in version 2.0.

# Passing a user object:
await client.send_friend_request(user)

# Passing a username
await client.send_friend_request('jake')

# Passing a legacy user:
await client.send_friend_request('Jake#0001')

# Passing a legacy username and discriminator:
await client.send_friend_request('Jake', '0001')

Parameters

user (Union[discord.User, str]) – The user to send the friend request to.
username (str) – The username of the user to send the friend request to.
discriminator (str) – The discriminator of the user to send the friend request to.

Raises

Forbidden – Not allowed to send a friend request to this user.
HTTPException – Sending the friend request failed.
TypeError – More than 2 parameters or less than 1 parameter was passed.

await applications(*, with_team_applications=True)¶

This function is a coroutine.

Retrieves all applications owned by you.

New in version 2.0.

Parameters: with_team_applications (bool) – Whether to include applications owned by teams you’re a part of.
Raises: HTTPException – Retrieving the applications failed.
Returns: The applications you own.
Return type: List[Application]

await detectable_applications()¶

This function is a coroutine.

Retrieves the list of applications detectable by the Discord client.

New in version 2.0.

Raises: HTTPException – Retrieving the applications failed.
Returns: The applications detectable by the Discord client.
Return type: List[PartialApplication]

await fetch_application(application_id, /)¶

This function is a coroutine.

Retrieves the application with the given ID.

The application must be owned by you or a team you are a part of.

New in version 2.0.

Parameters

application_id (int) – The ID of the application to fetch.

Raises

NotFound – The application was not found.
Forbidden – You do not own the application.
HTTPException – Retrieving the application failed.

Returns

The retrieved application.

Return type

Application

await fetch_partial_application(application_id, /)¶

This function is a coroutine.

Retrieves the partial application with the given ID.

New in version 2.0.

Parameters

application_id (int) – The ID of the partial application to fetch.

Raises

NotFound – The partial application was not found.
HTTPException – Retrieving the partial application failed.

Returns

The retrieved application.

Return type

PartialApplication

await fetch_public_application(application_id, /, *, with_guild=False)¶

This function is a coroutine.

Retrieves the public application with the given ID.

New in version 2.0.

Parameters

application_id (int) – The ID of the public application to fetch.
with_guild (bool) – Whether to include the public guild of the application.

Raises

NotFound – The public application was not found.
HTTPException – Retrieving the public application failed.

Returns

The retrieved application.

Return type

PartialApplication

await fetch_public_applications(*application_ids)¶

This function is a coroutine.

Retrieves a list of public applications. Only found applications are returned.

New in version 2.0.

Parameters: *application_ids (int) – The IDs of the public applications to fetch.
Raises: HTTPException – Retrieving the applications failed.
Returns: The public applications.
Return type: List[PartialApplication]

await teams(*, with_payout_account_status=False)¶

This function is a coroutine.

Retrieves all the teams you’re a part of.

New in version 2.0.

Parameters: with_payout_account_status (bool) – Whether to return the payout account status of the teams.
Raises: HTTPException – Retrieving the teams failed.
Returns: The teams you’re a part of.
Return type: List[Team]

await fetch_team(team_id, /)¶

This function is a coroutine.

Retrieves the team with the given ID.

You must be a part of the team.

New in version 2.0.

Parameters

id (int) – The ID of the team to fetch.

Raises

NotFound – The team was not found.
Forbidden – You are not a part of the team.
HTTPException – Retrieving the team failed.

Returns

The retrieved team.

Return type

Team

await create_application(name, /, *, team=None)¶

This function is a coroutine.

Creates an application.

New in version 2.0.

Parameters

name (str) – The name of the application.
team (Snowflake) – The team to create the application under.

Raises

HTTPException – Failed to create the application.

Returns

The newly-created application.

Return type

Application

await create_team(name, /)¶

This function is a coroutine.

Creates a team.

New in version 2.0.

Parameters: name (str) – The name of the team.
Raises: HTTPException – Failed to create the team.
Returns: The newly-created team.
Return type: Team

await search_companies(query, /)¶

This function is a coroutine.

Query your created companies.

New in version 2.0.

Parameters: query (str) – The query to search for.
Raises: HTTPException – Searching failed.
Returns: The companies found.
Return type: List[Company]

await activity_statistics()¶

This function is a coroutine.

Retrieves the available activity usage statistics for your owned applications.

New in version 2.0.

Raises: HTTPException – Retrieving the statistics failed.
Returns: The activity statistics.
Return type: List[ApplicationActivityStatistics]

await relationship_activity_statistics()¶

This function is a coroutine.

Retrieves the available activity usage statistics for your relationships’ owned applications.

New in version 2.0.

Raises: HTTPException – Retrieving the statistics failed.
Returns: The activity statistics.
Return type: List[ApplicationActivityStatistics]

await payment_sources()¶

This function is a coroutine.

Retrieves all the payment sources for your account.

New in version 2.0.

Raises: HTTPException – Retrieving the payment sources failed.
Returns: The payment sources.
Return type: List[PaymentSource]

await fetch_payment_source(source_id, /)¶

This function is a coroutine.

Retrieves the payment source with the given ID.

New in version 2.0.

Parameters

source_id (int) – The ID of the payment source to fetch.

Raises

NotFound – The payment source was not found.
HTTPException – Retrieving the payment source failed.

Returns

The retrieved payment source.

Return type

PaymentSource

await create_payment_source(*, token, payment_gateway, billing_address, billing_address_token=..., return_url=None, bank=None)¶

This function is a coroutine.

Creates a payment source.

This is a low-level method that requires data obtained from other APIs.

New in version 2.0.

Parameters

token (str) – The payment source token.
payment_gateway (PaymentGateway) – The payment gateway to use.
billing_address (BillingAddress) – The billing address to use.
billing_address_token (Optional[str]) – The billing address token. If not provided, the library will fetch it for you. Not required for all payment gateways.
return_url (Optional[str]) – The URL to return to after the payment source is created.
bank (Optional[str]) – The bank information for the payment source. Not required for most payment gateways.

Raises

HTTPException – Creating the payment source failed.

Returns

The newly-created payment source.

Return type

PaymentSource

await subscriptions(limit=None, with_inactive=False)¶

This function is a coroutine.

Retrieves all the subscriptions on your account.

New in version 2.0.

Parameters

limit (Optional[int]) – The maximum number of subscriptions to retrieve. Defaults to all subscriptions.
with_inactive (bool) – Whether to include inactive subscriptions.

Raises

HTTPException – Retrieving the subscriptions failed.

Returns

Your account’s subscriptions.

Return type

List[Subscription]

await premium_guild_subscriptions()¶

This function is a coroutine.

Retrieves all the premium guild subscriptions (boosts) on your account.

New in version 2.0.

Raises: HTTPException – Retrieving the subscriptions failed.
Returns: Your account’s premium guild subscriptions.
Return type: List[PremiumGuildSubscription]

await premium_guild_subscription_slots()¶

This function is a coroutine.

Retrieves all the premium guild subscription (boost) slots available on your account.

New in version 2.0.

Raises: HTTPException – Retrieving the subscriptions failed.
Returns: Your account’s premium guild subscription slots.
Return type: List[PremiumGuildSubscriptionSlot]

await premium_guild_subscription_cooldown()¶

This function is a coroutine.

Retrieves the cooldown for your premium guild subscriptions (boosts).

New in version 2.0.

Raises: HTTPException – Retrieving the cooldown failed.
Returns: Your account’s premium guild subscription cooldown.
Return type: PremiumGuildSubscriptionCooldown

await fetch_subscription(subscription_id, /)¶

This function is a coroutine.

Retrieves the subscription with the given ID.

New in version 2.0.

Parameters

subscription_id (int) – The ID of the subscription to fetch.

Raises

NotFound – The subscription was not found.
HTTPException – Retrieving the subscription failed.

Returns

The retrieved subscription.

Return type

Subscription

await preview_subscription(items, *, payment_source=None, currency='usd', trial=None, apply_entitlements=True, renewal=False, code=None, metadata=None, guild=None)¶

This function is a coroutine.

Preview an invoice for the subscription with the given parameters.

All parameters are optional and default to the current subscription values.

New in version 2.0.

Parameters

items (List[SubscriptionItem]) – The items the previewed subscription should have.
payment_source (Optional[PaymentSource]) – The payment source the previewed subscription should be paid with.
currency (str) – The currency the previewed subscription should be paid in.
trial (Optional[SubscriptionTrial]) – The trial plan the previewed subscription should be on.
apply_entitlements (bool) – Whether to apply entitlements (credits) to the previewed subscription.
renewal (bool) – Whether the previewed subscription should be a renewal.
code (Optional[str]) – Unknown.
metadata (Optional[Mapping[str, Any]]) – Extra metadata about the subscription.
guild (Optional[Guild]) – The guild the previewed subscription’s entitlements should be applied to.

Raises

HTTPException – Failed to preview the invoice.

Returns

The previewed invoice.

Return type

SubscriptionInvoice

await create_subscription(items, payment_source, currency='usd', *, trial=None, payment_source_token=None, purchase_token=None, return_url=None, gateway_checkout_context=None, code=None, metadata=None, guild=None)¶

This function is a coroutine.

Creates a new subscription.

New in version 2.0.

Parameters

items (List[SubscriptionItem]) – The items in the subscription.
payment_source (PaymentSource) – The payment source to pay with.
currency (str) – The currency to pay with.
trial (Optional[SubscriptionTrial]) – The trial to apply to the subscription.
payment_source_token (Optional[str]) – The token used to authorize with the payment source.
purchase_token (Optional[str]) – The purchase token to use.
return_url (Optional[str]) – The URL to return to after the payment is complete.
gateway_checkout_context (Optional[str]) – The current checkout context.
code (Optional[str]) – Unknown.
metadata (Optional[Mapping[str, Any]]) – Extra metadata about the subscription.
guild (Optional[Guild]) – The guild the subscription’s entitlements should be applied to.

Raises

HTTPException – Creating the subscription failed.

Returns

The newly-created subscription.

Return type

Subscription

async for ... in payments(*, limit=100, before=None, after=None, oldest_first=None)¶

Returns an asynchronous iterator that enables receiving your payments.

New in version 2.0.

Examples

Usage

counter = 0
async for payment in client.payments(limit=200):
    if payment.is_purchased_externally():
        counter += 1

Flattening into a list:

payments = [payment async for payment in client.payments(limit=123)]
# payments is now a list of Payment...

All parameters are optional.

Parameters

limit (Optional[int]) – The number of payments to retrieve. If None, retrieves every payment you have made. Note, however, that this would make it a slow operation.
before (Optional[Union[Snowflake, datetime.datetime]]) – Retrieve payments before this date or payment. 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[Snowflake, datetime.datetime]]) – Retrieve messages after this date or payment. 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.
oldest_first (Optional[bool]) – If set to True, return payments in oldest->newest order. Defaults to True if after is specified, otherwise False.

Raises

HTTPException – The request to get payments failed.

Yields

Payment – The payment made.

await fetch_payment(payment_id)¶

This function is a coroutine.

Retrieves the payment with the given ID.

New in version 2.0.

Parameters: payment_id (int) – The ID of the payment to fetch.
Raises: HTTPException – Fetching the payment failed.
Returns: The retrieved payment.
Return type: Payment

await promotions(claimed=False)¶

This function is a coroutine.

Retrieves all the promotions available for your account.

New in version 2.0.

Parameters: claimed (bool) – Whether to only retrieve claimed promotions. These will have Promotion.claimed_at and Promotion.code set.
Raises: HTTPException – Retrieving the promotions failed.
Returns: The promotions available for you.
Return type: List[Promotion]

await trial_offer()¶

This function is a coroutine.

Retrieves the current trial offer for your account.

New in version 2.0.

Raises

NotFound – You do not have a trial offer.
HTTPException – Retrieving the trial offer failed.

Returns

The trial offer for your account.

Return type

TrialOffer

await pricing_promotion()¶

This function is a coroutine.

Retrieves the current localized pricing promotion for your account, if any.

This also updates your current country code.

New in version 2.0.

Raises: HTTPException – Retrieving the pricing promotion failed.
Returns: The pricing promotion for your account, if any.
Return type: Optional[PricingPromotion]

await library()¶

This function is a coroutine.

Retrieves the applications in your library.

New in version 2.0.

Raises: HTTPException – Retrieving the library failed.
Returns: The applications in your library.
Return type: List[LibraryApplication]

await authorizations()¶

This function is a coroutine.

Retrieves the OAuth2 applications authorized on your account.

New in version 2.1.

Raises: HTTPException – Retrieving the authorized applications failed.
Returns: The OAuth2 applications authorized on your account.
Return type: List[OAuth2Token]

await fetch_authorization(application_id, /, *, scopes, response_type=None, redirect_uri=None, code_challenge_method=None, code_challenge=None, state=None)¶

This function is a coroutine.

Retrieves an OAuth2 authorization for the given application. This provides information about the application before you authorize it.

New in version 2.1.

Parameters

application_id (int) – The ID of the application to fetch the authorization for.
scopes (List[str]) – The scopes to request for the authorization.
response_type (Optional[str]) – The response type that will be used for the authorization, if using the full OAuth2 flow.
redirect_uri (Optional[str]) – The redirect URI that will be used for the authorization, if using the full OAuth2 flow. If this isn’t provided and response_type is provided, then the default redirect URI for the application will be provided in the returned authorization.
code_challenge_method (Optional[str]) – The code challenge method that will be used for the PKCE authorization, if using the full OAuth2 flow.
code_challenge (Optional[str]) – The code challenge that will be used for the PKCE authorization, if using the full OAuth2 flow.
state (Optional[str]) – The state that will be used for authorization security.

Raises

HTTPException – Fetching the authorization failed.

Returns

The authorization for the application.

Return type

OAuth2Authorization

await create_authorization(application_id, /, *, scopes, response_type=None, redirect_uri=None, code_challenge_method=None, code_challenge=None, state=None, guild=..., channel=..., permissions=...)¶

This function is a coroutine.

Creates an OAuth2 authorization for the given application. It is recommended to instead first fetch the authorization information using fetch_authorization() and then call OAuth2Authorization.authorize().

New in version 2.1.

Parameters

application_id (int) – The ID of the application to create the authorization for.
scopes (List[str]) – The scopes to request for the authorization.
response_type (Optional[str]) – The response type to use for the authorization, if using the full OAuth2 flow.
redirect_uri (Optional[str]) – The redirect URI to use for the authorization, if using the full OAuth2 flow. If this isn’t provided and response_type is provided, then the default redirect URI for the application will be used.
code_challenge_method (Optional[str]) – The code challenge method to use for the PKCE authorization, if using the full OAuth2 flow.
code_challenge (Optional[str]) – The code challenge to use for the PKCE authorization, if using the full OAuth2 flow.
state (Optional[str]) – The state to use for authorization security.
guild (Guild) – The guild to authorize for, if authorizing with the applications.commands or bot scopes.
channel (Union[TextChannel, VoiceChannel, StageChannel]) – The channel to authorize for, if authorizing with the webhooks.incoming scope. See Guild.webhook_channels().
permissions (Permissions) – The permissions to grant, if authorizing with the bot scope.

Raises

HTTPException – Creating the authorization failed.

Returns

The URL to redirect the user to for authorization.

Return type

await entitlements(*, with_sku=True, with_application=True, entitlement_type=None)¶

This function is a coroutine.

Retrieves all the entitlements for your account.

New in version 2.0.

Parameters

with_sku (bool) – Whether to include the SKU information in the returned entitlements.
with_application (bool) – Whether to include the application in the returned entitlements’ SKUs. The premium subscription application is always returned.
entitlement_type (Optional[EntitlementType]) – The type of entitlement to retrieve. If None then all entitlements are returned.

Raises

HTTPException – Retrieving the entitlements failed.

Returns

The entitlements for your account.

Return type

List[Entitlement]

await giftable_entitlements()¶

This function is a coroutine.

Retrieves the giftable entitlements for your account.

These are entitlements you are able to gift to other users.

New in version 2.0.

Raises: HTTPException – Retrieving the giftable entitlements failed.
Returns: The giftable entitlements for your account.
Return type: List[Entitlement]

await premium_entitlements(*, exclude_consumed=True)¶

This function is a coroutine.

Retrieves the entitlements this account has granted for the premium application.

These are the entitlements used for premium subscriptions, referred to as “Nitro Credits”.

New in version 2.0.

Parameters: exclude_consumed (bool) – Whether to exclude consumed entitlements.
Raises: HTTPException – Fetching the entitlements failed.
Returns: The entitlements retrieved.
Return type: List[Entitlement]

await fetch_entitlements(application_id, /, *, exclude_consumed=True)¶

This function is a coroutine.

Retrieves the entitlements this account has granted for the given application.

Parameters

application_id (int) – The ID of the application to fetch the entitlements for.
exclude_consumed (bool) – Whether to exclude consumed entitlements.

Raises

HTTPException – Fetching the entitlements failed.

Returns

The entitlements retrieved.

Return type

List[Entitlement]

await fetch_gift(code, *, with_application=False, with_subscription_plan=True)¶

This function is a coroutine.

Retrieves a gift with the given code.

New in version 2.0.

Parameters

code (Union[Gift, str]) – The code of the gift to retrieve.
with_application (bool) – Whether to include the application in the response’s store listing. The premium subscription application is always returned.
with_subscription_plan (bool) – Whether to include the subscription plan in the response.

Raises

NotFound – The gift does not exist.
HTTPException – Retrieving the gift failed.

Returns

The retrieved gift.

Return type

Gift

await fetch_sku(sku_id, /, *, localize=True)¶

This function is a coroutine.

Retrieves a SKU with the given ID.

New in version 2.0.

Parameters

sku_id (int) – The ID of the SKU to retrieve.
localize (bool) – Whether to localize the SKU name and description to the current user’s locale. If False then all localizations are returned.

Raises

NotFound – The SKU does not exist.
Forbidden – You do not have access to the SKU.
HTTPException – Retrieving the SKU failed.

Returns

The retrieved SKU.

Return type

SKU

await fetch_store_listing(listing_id, /, *, localize=True)¶

This function is a coroutine.

Retrieves a store listing with the given ID.

New in version 2.0.

Parameters

listing_id (int) – The ID of the listing to retrieve.
localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.

Raises

NotFound – The listing does not exist.
Forbidden – You do not have access to the listing.
HTTPException – Retrieving the listing failed.

Returns

The store listing.

Return type

await fetch_published_store_listing(sku_id, /, *, localize=True)¶

This function is a coroutine.

Retrieves a published store listing with the given SKU ID.

New in version 2.0.

Parameters

sku_id (int) – The ID of the SKU to retrieve the listing for.
localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.

Raises

NotFound – The listing does not exist or is not public.
HTTPException – Retrieving the listing failed.

Returns

The store listing.

Return type

await fetch_published_store_listings(application_id, /, localize=True)¶

This function is a coroutine.

Retrieves all published store listings for the given application ID.

New in version 2.0.

Parameters

application_id (int) – The ID of the application to retrieve the listings for.
localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.

Raises

HTTPException – Retrieving the listings failed.

Returns

The store listings.

Return type

List[StoreListing]

await fetch_primary_store_listing(application_id, /, *, localize=True)¶

This function is a coroutine.

Retrieves the primary store listing for the given application ID.

This is the public store listing of the primary SKU.

New in version 2.0.

Parameters

application_id (int) – The ID of the application to retrieve the listing for.
localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.

Raises

NotFound – The application does not exist or have a primary SKU.
HTTPException – Retrieving the store listing failed.

Returns

The retrieved store listing.

Return type

await fetch_primary_store_listings(*application_ids, localize=True)¶

This function is a coroutine.

Retrieves the primary store listings for the given application IDs.

This is the public store listing of the primary SKU.

New in version 2.0.

Parameters

*application_ids (int) – A list of application IDs to retrieve the listings for.
localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.

Raises

HTTPException – Retrieving the store listings failed.

Returns

The retrieved store listings.

Return type

List[StoreListing]

await premium_subscription_plans()¶

This function is a coroutine.

Retrieves all premium subscription plans.

New in version 2.0.

Raises: HTTPException – Retrieving the premium subscription plans failed.
Returns: The premium subscription plans.
Return type: List[SubscriptionPlan]

await fetch_sku_subscription_plans(sku_id, /, *, country_code=..., payment_source=..., with_unpublished=False)¶

This function is a coroutine.

Retrieves all subscription plans for the given SKU ID.

New in version 2.0.

Parameters

sku_id (int) – The ID of the SKU to retrieve the subscription plans for.
country_code (str) – The country code to retrieve the subscription plan prices for. Defaults to the country code of the current user.
payment_source (PaymentSource) – The specific payment source to retrieve the subscription plan prices for. Defaults to all payment sources of the current user.
with_unpublished (bool) –
Whether to include unpublished subscription plans.

If True, then you require access to the application.

Raises

HTTPException – Retrieving the subscription plans failed.

Returns

The subscription plans.

Return type

List[SubscriptionPlan]

await fetch_skus_subscription_plans(*sku_ids, country_code=..., payment_source=..., with_unpublished=False)¶

This function is a coroutine.

Retrieves all subscription plans for the given SKU IDs.

New in version 2.0.

Parameters

*sku_ids (int) – A list of SKU IDs to retrieve the subscription plans for.
country_code (str) – The country code to retrieve the subscription plan prices for. Defaults to the country code of the current user.
payment_source (PaymentSource) – The specific payment source to retrieve the subscription plan prices for. Defaults to all payment sources of the current user.
with_unpublished (bool) –
Whether to include unpublished subscription plans.

If True, then you require access to the application(s).

Raises

HTTPException – Retrieving the subscription plans failed.

Returns

The subscription plans.

Return type

List[SubscriptionPlan]

await fetch_eula(eula_id, /)¶

This function is a coroutine.

Retrieves a EULA with the given ID.

New in version 2.0.

Parameters

eula_id (int) – The ID of the EULA to retrieve.

Raises

NotFound – The EULA does not exist.
HTTPException – Retrieving the EULA failed.

Returns

The retrieved EULA.

Return type

EULA

await fetch_live_build_ids(*branch_ids)¶

This function is a coroutine.

Retrieves the live build IDs for the given branch IDs.

New in version 2.0.

Parameters: *branch_ids (int) – A list of branch IDs to retrieve the live build IDs for.
Raises: HTTPException – Retrieving the live build IDs failed.
Returns: A mapping of found branch IDs to their live build ID, if any.
Return type: Dict[int, Optional[int]]

await price_tiers()¶

This function is a coroutine.

Retrieves all price tiers.

New in version 2.0.

Raises: HTTPException – Retrieving the price tiers failed.
Returns: The price tiers.
Return type: List[int]

await fetch_price_tier(price_tier, /)¶

This function is a coroutine.

Retrieves a mapping of currency to price for the given price tier.

New in version 2.0.

Parameters

price_tier (int) – The price tier to retrieve.

Raises

NotFound – The price tier does not exist.
HTTPException – Retrieving the price tier failed.

Returns

The retrieved price tier mapping.

Return type

Dict[str, int]

await premium_usage()¶

This function is a coroutine.

Retrieves the usage of the premium perks on your account.

New in version 2.0.

Raises: HTTPException – Retrieving the premium usage failed.
Returns: The premium usage.
Return type: PremiumUsage

async for ... in recent_mentions(*, limit=25, before=..., guild=..., roles=True, everyone=True)¶

Returns an asynchronous iterator that enables receiving your recent mentions.

New in version 2.0.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in client.recent_mentions(limit=123)]
# 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 recent mention received in the past week. Note, however, that this would make it a slow operation.
before (Optional[Union[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.
guild (Guild) – The guild to retrieve recent mentions from. If not provided, then the mentions are retrieved from all guilds.
roles (bool) – Whether to include role mentions.
everyone (bool) – Whether to include @everyone or @here mentions.

Raises

HTTPException – The request to get recent message history failed.

Yields

Message – The message with the message data parsed.

await delete_recent_mention(message)¶

This function is a coroutine.

Acknowledges a message the current user has been mentioned in.

New in version 2.0.

Parameters: message (abc.Snowflake) – The message to delete.
Raises: HTTPException – Deleting the recent mention failed.

await user_affinities()¶

This function is a coroutine.

Retrieves the user affinities for the current user.

User affinities are the users you interact with most frecently.

New in version 2.0.

Raises: HTTPException – Retrieving the user affinities failed.
Returns: The user affinities.
Return type: List[UserAffinity]

await guild_affinities()¶

This function is a coroutine.

Retrieves the guild affinities for the current user.

Guild affinities are the guilds you interact with most frecently.

New in version 2.0.

Raises: HTTPException – Retrieving the guild affinities failed.
Returns: The guild affinities.
Return type: List[GuildAffinity]

await join_active_developer_program(*, application, channel)¶

This function is a coroutine.

Joins the current user to the active developer program.

New in version 2.0.

Parameters

application (Application) – The application to join the active developer program with.
channel (TextChannel) – The channel to add the developer program webhook to.

Raises

HTTPException – Joining the active developer program failed.

Returns

The created webhook ID.

Return type

await leave_active_developer_program()¶

This function is a coroutine.

Leaves the current user from the active developer program. This does not remove the created webhook.

New in version 2.0.

Raises: HTTPException – Leaving the active developer program failed.

await report_unverified_application(name, *, icon, os, executable=..., publisher=..., distributor=..., sku=...)¶

This function is a coroutine.

Reports an unverified application (a game not detected by the Discord client) to Discord.

If missing, this also uploads the application icon to Discord.

New in version 2.1.

Parameters

name (str) – The name of the application.
icon (File) – The icon of the application.
os (OperatingSystem) – The operating system the application is found on.
executable (str) – The executable of the application.
publisher (str) – The publisher of the application.
distributor (Distributor) – The distributor of the application SKU.
sku (str) – The SKU of the application.

Raises

HTTPException – Reporting the unverified application failed.

Returns

The reported unverified application.

Return type

UnverifiedApplication

await fetch_experiments(with_guild_experiments=True)¶

This function is a coroutine.

Retrieves the experiment rollouts available in relation to the user.

New in version 2.1.

Note

Certain guild experiments are only available via the gateway. See guild_experiments for these.

Parameters: with_guild_experiments (bool) – Whether to include guild experiment rollouts in the response.
Raises: HTTPException – Retrieving the experiment assignments failed.
Returns: The experiment rollouts.
Return type: List[Union[UserExperiment, GuildExperiment]]

await join_hub_waitlist(email, school)¶

This function is a coroutine.

Signs up for the Discord Student Hub waitlist.

New in version 2.1.

Parameters

email (str) – The email to sign up with.
school (str) – The school name to sign up with.

Raises

HTTPException – Signing up for the waitlist failed.

await lookup_hubs(email, /)¶

This function is a coroutine.

Looks up the Discord Student Hubs for the given email.

Note

Using this, you will only receive Guild.id, Guild.name, and Guild.icon per guild.

New in version 2.1.

Parameters: email (str) – The email to look up.
Raises: HTTPException – Looking up the hubs failed.
Returns: The hubs found.
Return type: List[Guild]

await join_hub(guild, email, *, code=None)¶

This function is a coroutine.

Joins the user to or requests a verification code for a Student Hub.

New in version 2.1.

Parameters

guild (Guild) – The hub to join.
email (str) – The email to join with.
code (Optional[str]) –
The email verification code.

Note

If not provided, this method requests a verification code instead.

Raises

HTTPException – Joining the hub or requesting the verification code failed.

Returns

The joined hub, if a code was provided.

Return type

Optional[Guild]

await pomelo_suggestion()¶

This function is a coroutine.

Gets the suggested pomelo username for your account. This username can be used with edit() to migrate your account to Discord’s new unique username system

Note

This method requires you to be in the pomelo rollout.

New in version 2.1.

Raises: HTTPException – You are not in the pomelo rollout.
Returns: The suggested username.
Return type: str

await check_pomelo_username(username)¶

This function is a coroutine.

Checks if a pomelo username is taken.

Note

This method requires you to be in the pomelo rollout.

New in version 2.1.

Parameters: username (str) – The username to check.
Raises: HTTPException – You are not in the pomelo rollout.
Returns: Whether the username is taken.
Return type: bool

Event Reference¶

This section outlines the different types of events listened by Client.

There are two ways to register an event, the first way is through the use of Client.event(). The second way is through subclassing Client and overriding the specific events. For example:

import discord

class MyClient(discord.Client):
    async def on_message(self, message):
        if message.author != self.user:
            return

        if message.content.startswith('$hello'):
            await message.channel.send('Hello World!')

If an event handler raises an exception, on_error() will be called to handle it, which defaults to logging the traceback and ignoring the exception.

Warning

All the events must be a coroutine. If they aren’t, then you might get unexpected errors. In order to turn a function into a coroutine they must be defined with async def.

AutoMod¶

discord.on_automod_rule_create(rule)¶

Called when a AutoModRule is created. You must have manage_guild to receive this.

New in version 2.0.

Parameters: rule (AutoModRule) – The rule that was created.

discord.on_automod_rule_update(rule)¶

Called when a AutoModRule is updated. You must have manage_guild to receive this.

New in version 2.0.

Parameters: rule (AutoModRule) – The rule that was updated.

discord.on_automod_rule_delete(rule)¶

Called when a AutoModRule is deleted. You must have manage_guild to receive this.

New in version 2.0.

Parameters: rule (AutoModRule) – The rule that was deleted.

discord.on_automod_action(execution)¶

Called when a AutoModAction is created/performed. You must have manage_guild to receive this.

New in version 2.0.

Parameters: execution (AutoModAction) – The rule execution that was performed.

Channels¶

discord.on_guild_channel_delete(channel)¶

discord.on_guild_channel_create(channel)¶

Called whenever a guild channel is deleted or created.

Note that you can get the guild from guild.

Parameters: channel (abc.GuildChannel) – The guild channel that got created or deleted.

discord.on_guild_channel_update(before, after)¶

Called whenever a guild channel is updated. e.g. changed name, topic, permissions.

Parameters

before (abc.GuildChannel) – The updated guild channel’s old info.
after (abc.GuildChannel) – The updated guild channel’s new info.

discord.on_guild_channel_pins_update(channel, last_pin)¶

Called whenever a message is pinned or unpinned from a guild channel.

Parameters

channel (Union[abc.GuildChannel, Thread]) – The guild channel that had its pins updated.
last_pin (Optional[datetime.datetime]) – The latest message that was pinned as an aware datetime in UTC. Could be None.

discord.on_private_channel_delete(channel)¶

discord.on_private_channel_create(channel)¶

Called whenever a private channel is deleted or created.

Parameters: channel (abc.PrivateChannel) – The private channel that got created or deleted.

discord.on_private_channel_update(before, after)¶

Called whenever a private channel is updated. e.g. changed name or topic.

Parameters

before (abc.PrivateChannel) – The updated private channel’s old info.
after (abc.PrivateChannel) – The updated private channel’s new info.

discord.on_private_channel_pins_update(channel, last_pin)¶

Called whenever a message is pinned or unpinned from a private channel.

Parameters

channel (abc.PrivateChannel) – The private channel that had its pins updated.
last_pin (Optional[datetime.datetime]) – The latest message that was pinned as an aware datetime in UTC. Could be None.

discord.on_group_join(channel, user)¶

discord.on_group_remove(channel, user)¶

Called when someone joins or leaves a GroupChannel.

Parameters

channel (GroupChannel) – The group that the user joined or left.
user (User) – The user that joined or left.

discord.on_typing(channel, user, when)¶

Called when someone begins typing a message.

The channel parameter can be a abc.Messageable instance. Which could either be TextChannel, GroupChannel, or DMChannel.

If the channel is a TextChannel then the user parameter is a Member, otherwise it is a User.

Parameters

channel (abc.Messageable) – The location where the typing originated from.
user (Union[User, Member]) – The user that started typing.
when (datetime.datetime) – When the typing started as an aware datetime in UTC.

Connection¶

discord.on_connect()¶

Called when the client has successfully connected to Discord. This is not the same as the client being fully prepared, see on_ready() for that.

The warnings on on_ready() also apply.

discord.on_disconnect()¶

Called when the client has disconnected from Discord, or a connection attempt to Discord has failed. This could happen either through the internet being disconnected, explicit calls to close, or Discord terminating the connection one way or the other.

This function can be called many times without a corresponding on_connect() call.

Debug¶

discord.on_error(event, *args, **kwargs)¶

Usually when an event raises an uncaught exception, a traceback is logged to stderr and the exception is ignored. If you want to change this behaviour and handle the exception for whatever reason yourself, this event can be overridden. Which, when done, will suppress the default action of printing the traceback.

The information of the exception raised and the exception itself can be retrieved with a standard call to sys.exc_info().

Note

on_error will only be dispatched to Client.event().

It will not be received by Client.wait_for(), or, if used, Bots listeners such as listen() or listener().

Changed in version 2.0: The traceback is now logged rather than printed.

Parameters

event (str) – The name of the event that raised the exception.
args – The positional arguments for the event that raised the exception.
kwargs – The keyword arguments for the event that raised the exception.

discord.on_socket_event_type(event_type)¶

Called whenever a websocket event is received from the WebSocket.

This is mainly useful for logging how many events you are receiving from the Discord gateway.

New in version 2.0.

Parameters: event_type (str) – The event type from Discord that is received, e.g. 'READY'.

discord.on_socket_raw_receive(msg)¶

Called whenever a message is completely received from the WebSocket, before it’s processed and parsed. This event is always dispatched when a complete message is received and the passed data is not parsed in any way.

This is only really useful for grabbing the WebSocket stream and debugging purposes.

This requires setting the enable_debug_events setting in the Client.

Note

This is only for the messages received from the client WebSocket. The voice WebSocket will not trigger this event.

Parameters: msg (str) – The message passed in from the WebSocket library.

discord.on_socket_raw_send(payload)¶

Called whenever a send operation is done on the WebSocket before the message is sent. The passed parameter is the message that is being sent to the WebSocket.

This is only really useful for grabbing the WebSocket stream and debugging purposes.

This requires setting the enable_debug_events setting in the Client.

Note

This is only for the messages sent from the client WebSocket. The voice WebSocket will not trigger this event.

Parameters: payload (Union[bytes, str]) – The message that is about to be passed on to the WebSocket library. It can be bytes to denote a binary message or str to denote a regular text message.

Gateway¶

discord.on_ready()¶: Called when the client is done preparing the data received from Discord. Usually after login is successful and the Client.guilds and co. are filled up.

Warning

This function is not guaranteed to be the first event called. Likewise, this function is not guaranteed to only be called once. This library implements reconnection logic and thus will end up calling this event whenever a RESUME request fails.

discord.on_resumed()¶: Called when the client has resumed a session.

Client¶

discord.on_settings_update(before, after)¶

Called when your UserSettings updates, for example:

Changed theme
Changed custom activity
Changed locale
etc

New in version 2.0.

Parameters

before (UserSettings) – The settings prior to being updated.
after (UserSettings) – The settings after being updated.

discord.on_guild_settings_update(before, after)¶

Called when a Guild GuildSettings updates, for example:

Muted guild or channel
Changed notification settings
etc

Note that you can get the guild from GuildSettings.guild.

New in version 2.0.

Parameters

before (GuildSettings) – The guild settings prior to being updated.
after (GuildSettings) – The guild settings after being updated.

discord.on_required_action_update(action)¶

Called when Discord requires you to do something to continue using your account.

New in version 2.0.

Parameters: action (Optional[RequiredActionType]) – The action required. If None, then no further action is required.

discord.on_user_feature_ack(payload)¶

Called when a user-specific feature is acknowledged.

This is a purposefully low-level event. Richer events are dispatched separately.

New in version 2.1.

Parameters: payload (RawUserFeatureAckEvent) – The raw event payload data.

Billing¶

discord.on_payment_sources_update()¶: Called when your payment sources are updated.

New in version 2.0.

discord.on_subscriptions_update()¶: Called when your subscriptions are updated.

New in version 2.0.

discord.on_payment_client_add(purchase_token_hash, expires_at)¶

Called when a payment client is added to your account.

New in version 2.0.

Parameters

purchase_token_hash (str) – The purchase token hash.
expires_at (datetime.datetime) – When the payment client expires.

discord.on_payment_update(payment)¶

Called when a payment is created or updated.

New in version 2.0.

Parameters: payment (Payment) – The payment that was updated.

discord.on_premium_guild_subscription_slot_create(slot)¶

Called when a premium guild subscription (boost) slot is added to your account.

New in version 2.0.

Parameters: slot (PremiumGuildSubscriptionSlot) – The slot that was added.

discord.on_premium_guild_subscription_slot_update(slot)¶

Called when a premium guild subscription (boost) slot is updated.

New in version 2.0.

Parameters: slot (PremiumGuildSubscriptionSlot) – The slot that was updated.

discord.on_billing_popup_bridge_callback(payment_source_type, path, query, state)¶

Called when a billing popup bridge callback is received.

New in version 2.0.

Parameters

payment_source_type (PaymentSourceType) – The payment source type.
path (str) – The path of the callback.
query (str) – The query of the callback.
state (str) – The state of the callback.

Entitlements¶

discord.on_library_application_update(application)¶

Called when a library entry is updated.

New in version 2.0.

Parameters: application (LibraryApplication) – The library entry that was updated.

discord.on_achievement_update(achievement, percent_complete)¶

Called when an achievement is updated.

New in version 2.0.

Parameters

achievement (Achievement) – The achievement that was updated.
percent_complete (int) – The percentage of the acheivement completed.

discord.on_entitlement_create(entitlement)¶

Called when an entitlement is added to your account.

New in version 2.0.

Parameters: entitlement (Entitlement) – The entitlement that was added.

discord.on_entitlement_update(entitlement)¶

Called when an entitlement is updated.

New in version 2.0.

Parameters: entitlement (Entitlement) – The entitlement that was updated.

discord.on_entitlement_delete(entitlement)¶

Called when an entitlement is removed from your account.

New in version 2.0.

Parameters: entitlement (Entitlement) – The entitlement that was removed.

discord.on_gift_create(gift)¶

Called when a gift is created.

New in version 2.0.

Note

This event does not guarantee most gift attributes.

Parameters: gift (Gift) – The gift that was created.

discord.on_gift_update(gift)¶

Called when a gift is updated.

New in version 2.0.

Note

This event does not guarantee most gift attributes.

Parameters: gift (Gift) – The gift that was updated.

Connections¶

discord.on_connections_update()¶: Called when your account’s connections are updated. This may not be accompanied by an on_connection_create() or on_connection_update() event.

New in version 2.0.

discord.on_connection_create(connection)¶

Called when a connection is added to your account.

New in version 2.0.

Parameters: connection (Connection) – The connection that was added.

discord.on_connection_update(before, after)¶

Called when a connection is updated on your account.

Note

Due to a Discord limitation, this is also called when a connection is removed.

New in version 2.0.

Parameters

before (Connection) – The connection prior to being updated.
after (Connection) – The connection after being updated.

discord.on_connections_link_callback(provider, code, state)¶

Called when a connection link callback is received.

New in version 2.0.

Parameters

provider (str) – The provider that the callback is for.
code (str) – The callback code that was received.
state (str) – The callback state.

Relationships¶

discord.on_relationship_add(relationship)¶

discord.on_relationship_remove(relationship)¶

Called when a Relationship is added or removed from the ClientUser.

Parameters: relationship (Relationship) – The relationship that was added or removed.

discord.on_relationship_update(before, after)¶

Called when a Relationship is updated, e.g. when you block a friend or a friendship is accepted.

Parameters

before (Relationship) – The previous relationship.
after (Relationship) – The updated relationship.

discord.on_friend_suggestion_add(friend_suggestion)¶

Called when a FriendSuggestion is created.

New in version 2.1.

Parameters: friend_suggestion (FriendSuggestion) – The friend suggestion that was created.

discord.on_friend_suggestion_remove(user)¶

Called when a FriendSuggestion is removed.

New in version 2.1.

Parameters: user (User) – The friend suggestion that was removed.

discord.on_raw_friend_suggestion_remove(user_id)¶

Called when a FriendSuggestion is removed. Unlike on_message_edit(), this is called regardless of the user being in the internal user cache or not.

New in version 2.1.

Parameters: user_id (int) – The ID of the friend suggestion that was removed.

Notes¶

discord.on_note_update(note)¶

Called when a User's note is updated.

New in version 2.0.

Parameters: note (Note) – The note that was updated.

OAuth2¶

discord.on_oauth2_token_revoke(token)¶

Called when an authorized application is revoked.

New in version 2.0.

Parameters: token (str) – The token that was revoked.

Calls¶

discord.on_call_create(call)¶

discord.on_call_delete(call)¶

Called when a call is created in a abc.PrivateChannel.

Parameters: call (Union[PrivateCall, GroupCall]) – The call that was created or deleted.

discord.on_call_update(before, after)¶

Called when a PrivateCall or GroupCall is updated, e.g. when a member is added or another person is rung.

Parameters

before (Relationship) – The previous call.
after (Relationship) – The updated call.

Guilds¶

discord.on_guild_available(guild)¶

discord.on_guild_unavailable(guild)¶

Called when a guild becomes available or unavailable. The guild must have existed in the Client.guilds cache.

Parameters: guild – The Guild that has changed availability.

discord.on_guild_join(guild)¶

Called when a Guild is either created by the Client or when the Client joins a guild.

Parameters: guild (Guild) – The guild that was joined.

discord.on_guild_remove(guild)¶

Called when a Guild is removed from the Client.

This happens through, but not limited to, these circumstances:

The client got banned.
The client got kicked.
The client left the guild.
The client or the guild owner deleted the guild.

In order for this event to be invoked then the Client must have been part of the guild to begin with. (i.e. it is part of Client.guilds)

Parameters: guild (Guild) – The guild that got removed.

discord.on_guild_update(before, after)¶

Called when a Guild updates, for example:

Changed name
Changed AFK channel
Changed AFK timeout
etc

Parameters

before (Guild) – The guild prior to being updated.
after (Guild) – The guild after being updated.

discord.on_guild_emojis_update(guild, before, after)¶

Called when a Guild adds or removes Emoji.

Parameters

guild (Guild) – The guild who got their emojis updated.
before (Sequence[Emoji]) – A list of emojis before the update.
after (Sequence[Emoji]) – A list of emojis after the update.

discord.on_guild_stickers_update(guild, before, after)¶

Called when a Guild updates its stickers.

New in version 2.0.

Parameters

guild (Guild) – The guild who got their stickers updated.
before (Sequence[GuildSticker]) – A list of stickers before the update.
after (Sequence[GuildSticker]) – A list of stickers after the update.

discord.on_application_command_counts_update(guild, before, after)¶

Called when a Guild's application command counts are updated.

New in version 2.0.

Parameters

guild (Guild) – The guild who got their application command counts updated.
before (ApplicationCommandCounts) – A namedtuple of application command counts before the update.
after (ApplicationCommandCounts) – A namedtuple of application command counts after the update.

discord.on_audit_log_entry_create(entry)¶

Called when a Guild gets a new audit log entry. You must have view_audit_log to receive this.

New in version 2.0.

Warning

Audit log entries received through the gateway are subject to data retrieval from cache rather than REST. This means that some data might not be present when you expect it to be. For example, the AuditLogEntry.target attribute will usually be a discord.Object and the AuditLogEntry.user attribute will depend on user and member cache.

To get the user ID of entry, AuditLogEntry.user_id can be used instead.

Parameters: entry (AuditLogEntry) – The audit log entry that was created.

discord.on_invite_create(invite)¶

Called when an Invite is created. You must have manage_channels to receive this.

New in version 1.3.

Note

There is a rare possibility that the Invite.guild and Invite.channel attributes will be of Object rather than the respective models.

Parameters: invite (Invite) – The invite that was created.

discord.on_invite_delete(invite)¶

Called when an Invite is deleted. You must have manage_channels to receive this.

New in version 1.3.

Note

There is a rare possibility that the Invite.guild and Invite.channel attributes will be of Object rather than the respective models.

Outside of those two attributes, the only other attribute guaranteed to be filled by the Discord gateway for this event is Invite.code.

Parameters: invite (Invite) – The invite that was deleted.

discord.on_guild_feature_ack(payload)¶

Called when a Guild feature is acknowledged.

This is a purposefully low-level event. Richer events such as on_scheduled_event_ack() are dispatched separately.

New in version 2.1.

Parameters: payload (RawGuildFeatureAckEvent) – The raw event payload data.

Integrations¶

discord.on_integration_create(integration)¶

Called when an integration is created.

New in version 2.0.

Parameters: integration (Integration) – The integration that was created.

discord.on_integration_update(integration)¶

Called when an integration is updated.

New in version 2.0.

Parameters: integration (Integration) – The integration that was updated.

discord.on_guild_integrations_update(guild)¶

Called whenever an integration is created, modified, or removed from a guild.

New in version 1.4.

Parameters: guild (Guild) – The guild that had its integrations updated.

discord.on_webhooks_update(channel)¶

Called whenever a webhook is created, modified, or removed from a guild channel.

Parameters: channel (abc.GuildChannel) – The channel that had its webhooks updated.

discord.on_raw_integration_delete(payload)¶

Called when an integration is deleted.

New in version 2.0.

Parameters: payload (RawIntegrationDeleteEvent) – The raw event payload data.

Interactions¶

discord.on_interaction(interaction)¶

Called when an interaction happens.

This currently happens when an application command or component is used.

New in version 2.0.

Parameters: interaction (Interaction) – The interaction data.

discord.on_interaction_finish(interaction)¶

Called when an interaction’s result is finalized.

New in version 2.0.

Parameters: interaction (Interaction) – The interaction data with Interaction.successful filled.

discord.on_modal(modal)¶

Called when a modal is sent.

This currently happens when an application command or component responds with a modal.

New in version 2.0.

Parameters: modal (Modal) – The modal data.

Members¶

discord.on_member_join(member)¶

Called when a Member joins a Guild.

Parameters: member (Member) – The member who joined.

discord.on_member_remove(member)¶

Called when a Member leaves a Guild.

If the guild or member could not be found in the internal cache this event will not be called, you may use on_raw_member_remove() instead.

Parameters: member (Member) – The member who left.

discord.on_raw_member_remove(payload)¶

Called when a Member leaves a Guild.

Unlike on_member_remove() this is called regardless of the guild or member being in the internal cache.

New in version 2.1.

Parameters: payload (RawMemberRemoveEvent) – The raw event payload data.

discord.on_member_update(before, after)¶

Called when a Member updates their profile.

This is called when one or more of the following things change:

nickname
roles
pending
timeout
guild avatar
flags

Due to a Discord limitation, this event is not dispatched when a member’s timeout expires.

Parameters

before (Member) – The updated member’s old info.
after (Member) – The updated member’s updated info.

discord.on_user_update(before, after)¶

Called when a User updates their profile.

This is called when one or more of the following things change:

avatar
username
discriminator

Parameters

before (User) – The updated user’s old info.
after (User) – The updated user’s updated info.

discord.on_member_ban(guild, user)¶

Called when user gets banned from a Guild.

Parameters

guild (Guild) – The guild the user got banned from.
user (Union[User, Member]) – The user that got banned. Can be either User or Member depending if the user was in the guild or not at the time of removal.

discord.on_member_unban(guild, user)¶

Called when a User gets unbanned from a Guild.

Parameters

guild (Guild) – The guild the user got unbanned from.
user (User) – The user that got unbanned.

discord.on_presence_update(before, after)¶

Called when a Member or Relationship updates their presence.

This is called when one or more of the following things change:

status
activity

New in version 2.0.

Parameters

before (Union[Member, Relationship]) – The updated member or friend’s old info.
after (Union[Member, Relationship]) – The updated member or friend’s updated info.

discord.on_raw_member_list_update(data)¶

Called when a member list update is received and parsed.

New in version 2.0.

Parameters: data (dict) – The raw member list update data.

Messages¶

discord.on_message(message)¶

Called when a Message is created and sent.

Warning

Your bot’s own messages and private messages are sent through this event. This can lead cases of ‘recursion’ depending on how your bot was programmed. If you want the bot to not reply to itself, consider checking the user IDs. Note that Bot does not have this problem.

Parameters: message (Message) – The current message.

discord.on_message_edit(before, after)¶

Called when a Message receives an update event. If the message is not found in the internal message cache, then these events will not be called. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds.

If this occurs increase the max_messages parameter or use the on_raw_message_edit() event instead.

The following non-exhaustive cases trigger this event:

A message has been pinned or unpinned.
The message content has been changed.
The message has received an embed.
- For performance reasons, the embed server does not do this in a “consistent” manner.
The message’s embeds were suppressed or unsuppressed.
A call message has received an update to its participants or ending time.

Parameters

before (Message) – The previous version of the message.
after (Message) – The current version of the message.

discord.on_message_delete(message)¶

Called when a message is deleted. If the message is not found in the internal message cache, then this event will not be called. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds.

If this occurs increase the max_messages parameter or use the on_raw_message_delete() event instead.

Parameters: message (Message) – The deleted message.

discord.on_bulk_message_delete(messages)¶

Called when messages are bulk deleted. If none of the messages deleted are found in the internal message cache, then this event will not be called. If individual messages were not found in the internal message cache, this event will still be called, but the messages not found will not be included in the messages list. Messages might not be in cache if the message is too old or the client is participating in high traffic guilds.

If this occurs increase the max_messages parameter or use the on_raw_bulk_message_delete() event instead.

Parameters: messages (List[Message]) – The messages that have been deleted.

discord.on_message_ack(message, manual)¶

Called when a message is marked as read. If the message is not found in the internal message cache, or the message ID is not real, then this event will not be called.

If this occurs increase the max_messages parameter or use the on_raw_message_ack() event instead.

Note

Messages sent by the current user are automatically marked as read, but this event will not dispatch.

New in version 2.1.

Parameters

message (Message) – The message that has been marked as read.
manual (bool) – Whether the channel read state was manually set to this message.

discord.on_raw_message_edit(payload)¶

Called when a message is edited. Unlike on_message_edit(), this is called regardless of the state of the internal message cache.

If the message is found in the message cache, it can be accessed via RawMessageUpdateEvent.cached_message. The cached message represents the message before it has been edited. For example, if the content of a message is modified and triggers the on_raw_message_edit() coroutine, the RawMessageUpdateEvent.cached_message will return a Message object that represents the message before the content was modified.

Due to the inherently raw nature of this event, the data parameter coincides with the raw data given by the gateway.

Since the data payload can be partial, care must be taken when accessing stuff in the dictionary. One example of a common case of partial data is when the 'content' key is inaccessible. This denotes an “embed” only edit, which is an edit in which only the embeds are updated by the Discord embed server.

Parameters: payload (RawMessageUpdateEvent) – The raw event payload data.

discord.on_raw_message_delete(payload)¶

Called when a message is deleted. Unlike on_message_delete(), this is called regardless of the message being in the internal message cache or not.

If the message is found in the message cache, it can be accessed via RawMessageDeleteEvent.cached_message

Parameters: payload (RawMessageDeleteEvent) – The raw event payload data.

discord.on_raw_bulk_message_delete(payload)¶

Called when a bulk delete is triggered. Unlike on_bulk_message_delete(), this is called regardless of the messages being in the internal message cache or not.

If the messages are found in the message cache, they can be accessed via RawBulkMessageDeleteEvent.cached_messages

Parameters: payload (RawBulkMessageDeleteEvent) – The raw event payload data.

discord.on_raw_message_ack(payload)¶

Called when a message is marked as read. Unlike on_message_ack(), this is called regardless of the message being in the internal message cache or not.

If the message is found in the message cache, it can be accessed via RawMessageAckEvent.cached_message

New in version 2.1.

Parameters: payload (RawMessageAckEvent) – The raw event payload data.

discord.on_recent_mention_delete(message)¶

Called when a message you were mentioned in in the last week is acknowledged and deleted. If the message is not found in the internal message cache, then this event will not be called.

New in version 2.0.

Parameters: message (Message) – The message that was deleted.

discord.on_raw_recent_mention_delete(message_id)¶

Called when a message you were mentioned in in the last week is acknowledged and deleted. Unlike on_recent_mention_delete(), this is called regardless of the message being in the internal message cache or not.

New in version 2.0.

Parameters: message_id (int) – The ID of the message that was deleted.

Reactions¶

discord.on_reaction_add(reaction, user)¶

Called when a message has a reaction added to it. Similar to on_message_edit(), if the message is not found in the internal message cache, then this event will not be called. Consider using on_raw_reaction_add() instead.

Note

To get the Message being reacted, access it via Reaction.message.

Parameters

reaction (Reaction) – The current state of the reaction.
user (Union[Member, User]) – The user who added the reaction.

discord.on_reaction_remove(reaction, user)¶

Called when a message has a reaction removed from it. Similar to on_message_edit, if the message is not found in the internal message cache, then this event will not be called.

Note

To get the message being reacted, access it via Reaction.message.

Note

Consider using on_raw_reaction_remove() if you need this and do not have a complete member cache.

Parameters

reaction (Reaction) – The current state of the reaction.
user (Union[Member, User]) – The user whose reaction was removed.

discord.on_reaction_clear(message, reactions)¶

Called when a message has all its reactions removed from it. Similar to on_message_edit(), if the message is not found in the internal message cache, then this event will not be called. Consider using on_raw_reaction_clear() instead.

Parameters

message (Message) – The message that had its reactions cleared.
reactions (List[Reaction]) – The reactions that were removed.

discord.on_reaction_clear_emoji(reaction)¶

Called when a message has a specific reaction removed from it. Similar to on_message_edit(), if the message is not found in the internal message cache, then this event will not be called. Consider using on_raw_reaction_clear_emoji() instead.

New in version 1.3.

Parameters: reaction (Reaction) – The reaction that got cleared.

discord.on_raw_reaction_add(payload)¶

Called when a message has a reaction added. Unlike on_reaction_add(), this is called regardless of the state of the internal message cache.

Parameters: payload (RawReactionActionEvent) – The raw event payload data.

discord.on_raw_reaction_remove(payload)¶

Called when a message has a reaction removed. Unlike on_reaction_remove(), this is called regardless of the state of the internal message cache.

Parameters: payload (RawReactionActionEvent) – The raw event payload data.

discord.on_raw_reaction_clear(payload)¶

Called when a message has all its reactions removed. Unlike on_reaction_clear(), this is called regardless of the state of the internal message cache.

Parameters: payload (RawReactionClearEvent) – The raw event payload data.

discord.on_raw_reaction_clear_emoji(payload)¶

Called when a message has a specific reaction removed from it. Unlike on_reaction_clear_emoji() this is called regardless of the state of the internal message cache.

New in version 1.3.

Parameters: payload (RawReactionClearEmojiEvent) – The raw event payload data.

Roles¶

discord.on_guild_role_create(role)¶

discord.on_guild_role_delete(role)¶

Called when a Guild creates or deletes a new Role.

To get the guild it belongs to, use Role.guild.

Parameters: role (Role) – The role that was created or deleted.

discord.on_guild_role_update(before, after)¶

Called when a Role is changed guild-wide.

Parameters

before (Role) – The updated role’s old info.
after (Role) – The updated role’s updated info.

Scheduled Events¶

discord.on_scheduled_event_create(event)¶

discord.on_scheduled_event_delete(event)¶

Called when a ScheduledEvent is created or deleted.

New in version 2.0.

Parameters: event (ScheduledEvent) – The scheduled event that was created or deleted.

discord.on_scheduled_event_update(before, after)¶

Called when a ScheduledEvent is updated.

The following, but not limited to, examples illustrate when this event is called:

The scheduled start/end times are changed.
The channel is changed.
The description is changed.
The status is changed.
The image is changed.

New in version 2.0.

Parameters

before (ScheduledEvent) – The scheduled event before the update.
after (ScheduledEvent) – The scheduled event after the update.

discord.on_scheduled_event_user_add(event, user)¶

discord.on_scheduled_event_user_remove(event, user)¶

Called when a user is added or removed from a ScheduledEvent.

New in version 2.0.

Parameters

event (ScheduledEvent) – The scheduled event that the user was added or removed from.
user (User) – The user that was added or removed.

discord.on_raw_scheduled_event_user_add(event, user_id)¶

discord.on_raw_scheduled_event_user_remove(event, user_id)¶

Called when a user is added or removed from a ScheduledEvent. Unlike on_scheduled_event_user_add() and on_scheduled_event_user_remove() these are called regardless of the user being in the internal user cache or not.

New in version 2.1.

Parameters

event (ScheduledEvent) – The scheduled event that the user was added or removed from.
user_id (int) – The ID of the user that was added or removed.

discord.on_scheduled_event_ack(event)¶

Called when a scheduled event is marked as read.

Note

Scheduled events created by the current user are automatically marked as read, but this event will not dispatch.

New in version 2.1.

Parameters: event (ScheduledEvent) – The scheduled event that was marked as read.

Stages¶

discord.on_stage_instance_create(stage_instance)¶

discord.on_stage_instance_delete(stage_instance)¶

Called when a StageInstance is created or deleted for a StageChannel.

New in version 2.0.

Parameters: stage_instance (StageInstance) – The stage instance that was created or deleted.

discord.on_stage_instance_update(before, after)¶

Called when a StageInstance is updated.

The following, but not limited to, examples illustrate when this event is called:

The topic is changed.
The privacy level is changed.

New in version 2.0.

Parameters

before (StageInstance) – The stage instance before the update.
after (StageInstance) – The stage instance after the update.

Threads¶

discord.on_thread_create(thread)¶

Called whenever a thread is created.

Note that you can get the guild from Thread.guild.

New in version 2.0.

Parameters: thread (Thread) – The thread that was created.

discord.on_thread_join(thread)¶

Called whenever a thread is joined.

Note that you can get the guild from Thread.guild.

New in version 2.0.

Parameters: thread (Thread) – The thread that got joined.

discord.on_thread_update(before, after)¶

Called whenever a thread is updated.

New in version 2.0.

Parameters

before (Thread) – The updated thread’s old info.
after (Thread) – The updated thread’s new info.

discord.on_thread_remove(thread)¶

Called whenever a thread is removed. This is different from a thread being deleted.

Note that you can get the guild from Thread.guild.

Warning

Due to technical limitations, this event might not be called as soon as one expects. Since the library tracks thread membership locally, the API only sends updated thread membership status upon being synced by joining a thread.

New in version 2.0.

Parameters: thread (Thread) – The thread that got removed.

discord.on_thread_delete(thread)¶

Called whenever a thread is deleted. If the thread could not be found in the internal cache this event will not be called. Threads will not be in the cache if they are archived.

If you need this information use on_raw_thread_delete() instead.

Note that you can get the guild from Thread.guild.

New in version 2.0.

Parameters: thread (Thread) – The thread that got deleted.

discord.on_raw_thread_delete(payload)¶

Called whenever a thread is deleted. Unlike on_thread_delete() this is called regardless of the thread being in the internal thread cache or not.

New in version 2.0.

Parameters: payload (RawThreadDeleteEvent) – The raw event payload data.

discord.on_thread_member_join(member)¶

discord.on_thread_member_remove(member)¶

Called when a ThreadMember leaves or joins a Thread.

You can get the thread a member belongs in by accessing ThreadMember.thread.

New in version 2.0.

Parameters: member (ThreadMember) – The member who joined or left.

discord.on_raw_thread_member_remove(payload)¶

Called when a ThreadMember leaves a Thread. Unlike on_thread_member_remove() this is called regardless of the member being in the internal thread’s members cache or not.

New in version 2.0.

Parameters: payload (RawThreadMembersUpdate) – The raw event payload data.

Voice¶

discord.on_voice_state_update(member, before, after)¶

Called when a Member changes their VoiceState.

The following, but not limited to, examples illustrate when this event is called:

A member joins a voice or stage channel.
A member leaves a voice or stage channel.
A member is muted or deafened by their own accord.
A member is muted or deafened by a guild administrator.

Parameters

member (Member) – The member whose voice states changed.
before (VoiceState) – The voice state prior to the changes.
after (VoiceState) – The voice state after the changes.

Utility Functions¶

discord.utils.find(predicate, iterable, /)¶

A helper to return the first element found in the sequence that meets the predicate. For example:

member = discord.utils.find(lambda m: m.name == 'Mighty', channel.guild.members)

would find the first Member whose name is ‘Mighty’ and return it. If an entry is not found, then None is returned.

This is different from filter() due to the fact it stops the moment it finds a valid entry.

Changed in version 2.0: Both parameters are now positional-only.

Changed in version 2.0: The iterable parameter supports asynchronous iterables.

Parameters

predicate – A function that returns a boolean-like result.
iterable (Union[collections.abc.Iterable, collections.abc.AsyncIterable]) – The iterable to search through. Using a collections.abc.AsyncIterable, makes this function return a coroutine.

discord.utils.get(iterable, /, **attrs)¶

A helper that returns the first element in the iterable that meets all the traits passed in attrs. This is an alternative for find().

When multiple attributes are specified, they are checked using logical AND, not logical OR. Meaning they have to meet every attribute passed in and not one of them.

To have a nested attribute search (i.e. search by x.y) then pass in x__y as the keyword argument.

If nothing is found that matches the attributes passed, then None is returned.

Changed in version 2.0: The iterable parameter is now positional-only.

Changed in version 2.0: The iterable parameter supports asynchronous iterables.

Examples

Basic usage:

member = discord.utils.get(message.guild.members, name='Foo')

Multiple attribute matching:

channel = discord.utils.get(guild.voice_channels, name='Foo', bitrate=64000)

Nested attribute matching:

channel = discord.utils.get(client.get_all_channels(), guild__name='Cool', name='general')

Async iterables:

msg = await discord.utils.get(channel.history(), author__name='Dave')

Parameters

iterable (Union[collections.abc.Iterable, collections.abc.AsyncIterable]) – The iterable to search through. Using a collections.abc.AsyncIterable, makes this function return a coroutine.
**attrs – Keyword arguments that denote attributes to search with.

discord.utils.setup_logging(*, handler=..., formatter=..., level=..., root=True)¶

A helper function to setup logging.

This is superficially similar to logging.basicConfig() but uses different defaults and a colour formatter if the stream can display colour.

This is used by the Client to set up logging if log_handler is not None.

New in version 2.0.

Parameters

handler (logging.Handler) –
The log handler to use for the library’s logger.

The default log handler if not provided is logging.StreamHandler.
formatter (logging.Formatter) – The formatter to use with the given log handler. If not provided then it defaults to a colour based logging formatter (if available). If colour is not available then a simple logging formatter is provided.
level (int) – The default log level for the library’s logger. Defaults to logging.INFO.
root (bool) – Whether to set up the root logger rather than the library logger. Unlike the default for Client, this defaults to True.

await discord.utils.maybe_coroutine(f, *args, **kwargs)¶

This function is a coroutine.

A helper function that will await the result of a function if it’s a coroutine or return the result if it’s not.

This is useful for functions that may or may not be coroutines.

New in version 2.0.

Parameters

f (Callable[..., Any]) – The function or coroutine to call.
*args – The arguments to pass to the function.
**kwargs – The keyword arguments to pass to the function.

Returns

The result of the function or coroutine.

Return type

Any

discord.utils.snowflake_time(id, /)¶

Returns the creation time of the given snowflake.

Changed in version 2.0: The id parameter is now positional-only.

Parameters: id (int) – The snowflake ID.
Returns: An aware datetime in UTC representing the creation time of the snowflake.
Return type: datetime.datetime

discord.utils.time_snowflake(dt, /, *, high=False)¶

Returns a numeric snowflake pretending to be created at the given date.

When using as the lower end of a range, use time_snowflake(dt, high=False) - 1 to be inclusive, high=True to be exclusive.

When using as the higher end of a range, use time_snowflake(dt, high=True) + 1 to be inclusive, high=False to be exclusive.

Changed in version 2.0: The high parameter is now keyword-only and the dt parameter is now positional-only.

Parameters

dt (datetime.datetime) – A datetime object to convert to a snowflake. If naive, the timezone is assumed to be local time.
high (bool) – Whether or not to set the lower 22 bit to high or low.

Returns

The snowflake representing the time given.

Return type

discord.utils.oauth_url(client_id, *, permissions=..., guild=..., redirect_uri=..., scopes=..., disable_guild_select=False, state=...)¶

A helper function that returns the OAuth2 URL for inviting a bot into guilds.

Changed in version 2.0: permissions, guild, redirect_uri, scopes and state parameters are now keyword-only.

Parameters

client_id (Union[int, str]) – The client ID for the bot.
permissions (Permissions) – The permissions you’re requesting. If not given then you won’t be requesting any permissions.
guild (Snowflake) – The guild to pre-select in the authorization screen, if available.
redirect_uri (str) – An optional valid redirect URI.
scopes (Iterable[str]) –
An optional valid list of scopes. Defaults to ('bot', 'applications.commands').

New in version 1.7.
disable_guild_select (bool) –
Whether to disallow the user from changing the guild dropdown.

New in version 2.0.
state (str) –
The state to return after the authorization.

New in version 2.0.

Returns

The OAuth2 URL for inviting the bot into guilds.

Return type

discord.utils.remove_markdown(text, *, ignore_links=True)¶

A helper function that removes markdown characters.

New in version 1.7.

Note

This function is not markdown aware and may remove meaning from the original text. For example, if the input contains 10 * 5 then it will be converted into 10 5.

Parameters

text (str) – The text to remove markdown from.
ignore_links (bool) – Whether to leave links alone when removing markdown. For example, if a URL in the text contains characters such as _ then it will be left alone. Defaults to True.

Returns

The text with the markdown special characters removed.

Return type

discord.utils.escape_markdown(text, *, as_needed=False, ignore_links=True)¶

A helper function that escapes Discord’s markdown.

Parameters

text (str) – The text to escape markdown from.
as_needed (bool) – Whether to escape the markdown characters as needed. This means that it does not escape extraneous characters if it’s not necessary, e.g. **hello** is escaped into \*\*hello** instead of \*\*hello\*\*. Note however that this can open you up to some clever syntax abuse. Defaults to False.
ignore_links (bool) – Whether to leave links alone when escaping markdown. For example, if a URL in the text contains characters such as _ then it will be left alone. This option is not supported with as_needed. Defaults to True.

Returns

The text with the markdown special characters escaped with a slash.

Return type

discord.utils.escape_mentions(text)¶

A helper function that escapes everyone, here, role, and user mentions.

Note

This does not include channel mentions.

Note

For more granular control over what mentions should be escaped within messages, refer to the AllowedMentions class.

Parameters: text (str) – The text to escape mentions from.
Returns: The text with the mentions removed.
Return type: str

class discord.ResolvedInvite¶

A data class which represents a resolved invite returned from discord.utils.resolve_invite().

code¶

The invite code.

Type: str

event¶

The id of the scheduled event that the invite refers to.

Type: Optional[int]

discord.utils.resolve_invite(invite)¶

Resolves an invite from a Invite, URL or code.

Changed in version 2.0: Now returns a ResolvedInvite instead of a str.

Parameters: invite (Union[Invite, str]) – The invite.
Returns: A data class containing the invite code and the event ID.
Return type: ResolvedInvite

discord.utils.resolve_template(code)¶

Resolves a template code from a Template, URL or code.

New in version 1.4.

Parameters: code (Union[Template, str]) – The code.
Returns: The template code.
Return type: str

await discord.utils.sleep_until(when, result=None)¶

This function is a coroutine.

Sleep until a specified time.

If the time supplied is in the past this function will yield instantly.

New in version 1.3.

Parameters

when (datetime.datetime) – The timestamp in which to sleep until. If the datetime is naive then it is assumed to be local time.
result (Any) – If provided is returned to the caller when the coroutine completes.

discord.utils.utcnow()¶

A helper function to return an aware UTC datetime representing the current time.

This should be preferred to datetime.datetime.utcnow() since it is an aware datetime, compared to the naive datetime in the standard library.

New in version 2.0.

Returns: The current aware datetime in UTC.
Return type: datetime.datetime

discord.utils.format_dt(dt, /, style=None)¶

A helper function to format a datetime.datetime for presentation within Discord.

This allows for a locale-independent way of presenting data using Discord specific Markdown.

Style	Example Output	Description
t	22:57	Short Time
T	22:57:58	Long Time
d	17/05/2016	Short Date
D	17 May 2016	Long Date
f (default)	17 May 2016 22:57	Short Date Time
F	Tuesday, 17 May 2016 22:57	Long Date Time
R	5 years ago	Relative Time

Note that the exact output depends on the user’s locale setting in the client. The example output presented is using the en-GB locale.

New in version 2.0.

Parameters

dt (datetime.datetime) – The datetime to format.
style (str) – The style to format the datetime with.

Returns

The formatted string.

Return type

discord.utils.as_chunks(iterator, max_size)¶

A helper function that collects an iterator into chunks of a given size.

New in version 2.0.

Parameters

iterator (Union[collections.abc.Iterable, collections.abc.AsyncIterable]) – The iterator to chunk, can be sync or async.
max_size (int) – The maximum chunk size.

Warning

The last chunk collected may not be as large as max_size.

Returns: A new iterator which yields chunks of a given size.
Return type: Union[Iterator, AsyncIterator]

discord.utils.set_target(items, *, channel=..., message=..., user=...)¶

A helper function to set the target for a list of items.

This is used to set the target for a list of application commands.

Suppresses all AttributeErrors so you can pass multiple types of commands and not worry about which elements support which parameter.

New in version 2.0.

Deprecated since version 2.1.

Parameters

items (Iterable[abc.ApplicationCommand]) – A list of items to set the target for.
channel (Optional[abc.Messageable]) – The channel to target.
message (Optional[Message]) – The message to target.
user (Optional[Snowflake]) – The user to target.

discord.utils.MISSING¶: A type safe sentinel used in the library to represent something as missing. Used to distinguish from None values.

New in version 2.0.

Enumerations¶

The API provides some enumerations for certain types of strings to avoid the API from being stringly typed in case the strings change in the future.

All enumerations are subclasses of an internal class which mimics the behaviour of enum.Enum.

class discord.ChannelType¶

Specifies the type of channel.

text¶: A text channel.

voice¶: A voice channel.

private¶: A private text channel. Also called a direct message.

group¶: A private group text channel.

category¶: A category channel.

news¶: A guild news channel.

stage_voice¶: A guild stage voice channel.

New in version 1.7.

news_thread¶: A news thread.

New in version 2.0.

public_thread¶: A public thread.

New in version 2.0.

private_thread¶: A private thread.

New in version 2.0.

directory¶: A directory channel.

New in version 2.1.

forum¶: A forum channel.

New in version 2.0.

class discord.MessageType¶

Specifies the type of Message. This is used to denote if a message is to be interpreted as a system message or a regular message.

x == y: Checks if two messages are equal.

x != y: Checks if two messages are not equal.

default¶: The default message type. This is the same as regular messages.

recipient_add¶: The system message when a user is added to a group private message or a thread.

recipient_remove¶: The system message when a user is removed from a group private message or a thread.

call¶: The system message denoting call state, e.g. missed call, started call, etc.

channel_name_change¶: The system message denoting that a channel’s name has been changed.

channel_icon_change¶: The system message denoting that a channel’s icon has been changed.

pins_add¶: The system message denoting that a pinned message has been added to a channel.

new_member¶: The system message denoting that a new member has joined a Guild.

premium_guild_subscription¶: The system message denoting that a member has “nitro boosted” a guild.

premium_guild_tier_1¶: The system message denoting that a member has “nitro boosted” a guild and it achieved level 1.

premium_guild_tier_2¶: The system message denoting that a member has “nitro boosted” a guild and it achieved level 2.

premium_guild_tier_3¶: The system message denoting that a member has “nitro boosted” a guild and it achieved level 3.

channel_follow_add¶: The system message denoting that an announcement channel has been followed.

New in version 1.3.

guild_stream¶: The system message denoting that a member is streaming in the guild.

New in version 1.7.

guild_discovery_disqualified¶: The system message denoting that the guild is no longer eligible for Server Discovery.

New in version 1.7.

guild_discovery_requalified¶: The system message denoting that the guild has become eligible again for Server Discovery.

New in version 1.7.

guild_discovery_grace_period_initial_warning¶: The system message denoting that the guild has failed to meet the Server Discovery requirements for one week.

New in version 1.7.

guild_discovery_grace_period_final_warning¶: The system message denoting that the guild has failed to meet the Server Discovery requirements for 3 weeks in a row.

New in version 1.7.

thread_created¶: The system message denoting that a thread has been created. This is only sent if the thread has been created from an older message. The period of time required for a message to be considered old cannot be relied upon and is up to Discord.

New in version 2.0.

reply¶: The system message denoting that the author is replying to a message.

New in version 2.0.

chat_input_command¶: The system message denoting that a slash command was executed.

New in version 2.0.

guild_invite_reminder¶: The system message sent as a reminder to invite people to the guild.

New in version 2.0.

thread_starter_message¶: The system message denoting the message in the thread that is the one that started the thread’s conversation topic.

New in version 2.0.

context_menu_command¶: The system message denoting that a context menu command was executed.

New in version 2.0.

auto_moderation_action¶: The system message sent when an AutoMod rule is triggered. This is only sent if the rule is configured to sent an alert when triggered.

New in version 2.0.

role_subscription_purchase¶: The system message sent when a user purchases or renews a role subscription.

New in version 2.0.

interaction_premium_upsell¶: The system message sent when a user is given an advertisement to purchase a premium tier for an application during an interaction.

New in version 2.0.

stage_start¶: The system message sent when the stage starts.

New in version 2.0.

stage_end¶: The system message sent when the stage ends.

New in version 2.0.

stage_speaker¶: The system message sent when the stage speaker changes.

New in version 2.0.

stage_raise_hand¶: The system message sent when a user is requesting to speak by raising their hands.

New in version 2.0.

stage_topic¶: The system message sent when the stage topic changes.

New in version 2.0.

guild_application_premium_subscription¶: The system message sent when an application’s premium subscription is purchased for the guild.

New in version 2.0.

class discord.InviteType¶

Specifies the type of Invite.

guild¶: A guild invite.

group_dm¶: A group DM invite.

friend¶: A friend invite.

class discord.UserFlags¶

Represents Discord User flags.

staff¶: The user is a Discord Employee.

partner¶: The user is a Discord Partner.

hypesquad¶: The user is a HypeSquad Events member.

bug_hunter¶: The user is a Bug Hunter.

bug_hunter_level_1¶: The user is a Bug Hunter.

New in version 2.0.

mfa_sms¶: The user has SMS recovery for Multi Factor Authentication enabled.

premium_promo_dismissed¶: The user has dismissed the Discord Nitro promotion.

hypesquad_bravery¶: The user is a HypeSquad Bravery member.

hypesquad_brilliance¶: The user is a HypeSquad Brilliance member.

hypesquad_balance¶: The user is a HypeSquad Balance member.

early_supporter¶: The user is an Early Supporter.

team_user¶: The user is a Team User.

partner_or_verification_application¶: The user has a partner or verification application.

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

New in version 2.0.

has_unread_urgent_messages¶: The user has an unread system message.

bug_hunter_level_2¶: The user is a Bug Hunter Level 2.

underage_deleted¶: The user has been flagged for deletion for being underage.

New in version 2.0.

verified_bot¶: The user is a Verified Bot.

verified_bot_developer¶: The user is an Early Verified Bot Developer.

discord_certified_moderator¶: The user is a Discord Certified Moderator.

bot_http_interactions¶: The user is a bot that only uses HTTP interactions and is shown in the online member list.

New in version 2.0.

spammer¶: The user is flagged as a spammer by Discord.

New in version 2.0.

disable_premium¶: The user bought premium but has it manually disabled.

New in version 2.0.

quarantined¶: The user is quarantined.

New in version 2.0.

active_developer¶: The user is an active developer.

New in version 2.0.

class discord.ActivityType¶

Specifies the type of Activity. This is used to check how to interpret the activity itself.

unknown¶: An unknown activity type. This should generally not happen.

playing¶: A “Playing” activity type.

streaming¶: A “Streaming” activity type.

listening¶: A “Listening” activity type.

watching¶: A “Watching” activity type.

custom¶: A custom activity type.

competing¶: A competing activity type.

New in version 1.5.

class discord.HypeSquadHouse¶

Specifies the HypeSquad house a user belongs to.

bravery¶: The “Bravery” house.

brilliance¶: The “Brilliance” house.

balance¶: The “Balance” house.

class discord.VerificationLevel¶

Specifies a Guild's verification level, which is the criteria in which a member must meet before being able to send messages to the guild.

New in version 2.0.

x == y: Checks if two verification levels are equal.

x != y: Checks if two verification levels are not equal.

x > y: Checks if a verification level is higher than another.

x < y: Checks if a verification level is lower than another.

x >= y: Checks if a verification level is higher or equal to another.

x <= y: Checks if a verification level is lower or equal to another.

none¶: No criteria set.

low¶: Member must have a verified email on their Discord account.

medium¶: Member must have a verified email and be registered on Discord for more than five minutes.

high¶: Member must have a verified email, be registered on Discord for more than five minutes, and be a member of the guild itself for more than ten minutes.

highest¶: Member must have a verified phone on their Discord account.

class discord.NotificationLevel¶

Specifies whether a Guild has notifications on for all messages or mentions only by default.

New in version 2.0.

x == y: Checks if two notification levels are equal.

x != y: Checks if two notification levels are not equal.

x > y: Checks if a notification level is higher than another.

x < y: Checks if a notification level is lower than another.

x >= y: Checks if a notification level is higher or equal to another.

x <= y: Checks if a notification level is lower or equal to another.

all_messages¶: Members receive notifications for every message regardless of them being mentioned.

only_mentions¶: Members receive notifications for messages they are mentioned in.

class discord.HighlightLevel¶

Specifies whether a Guild has highlights included in notifications.

New in version 2.0.

default¶: The highlight level is set to Discord default. This seems to always be enabled, which makes the purpose of this enum unclear.

disabled¶: Members do not receive additional notifications for highlights.

enabled¶: Members receive additional notifications for highlights.

class discord.ContentFilter¶

Specifies a Guild's explicit content filter, which is the machine learning algorithms that Discord uses to detect if an image contains pornography or otherwise explicit content.

New in version 2.0.

x == y: Checks if two content filter levels are equal.

x != y: Checks if two content filter levels are not equal.

x > y: Checks if a content filter level is higher than another.

x < y: Checks if a content filter level is lower than another.

x >= y: Checks if a content filter level is higher or equal to another.

x <= y: Checks if a content filter level is lower or equal to another.

disabled¶: The guild does not have the content filter enabled.

no_role¶: The guild has the content filter enabled for members without a role.

all_members¶: The guild has the content filter enabled for every member.

class discord.Status¶

Specifies a Member ‘s status.

online¶: The member is online.

offline¶: The member is offline.

idle¶: The member is idle.

dnd¶: The member is “Do Not Disturb”.

do_not_disturb¶: An alias for dnd.

invisible¶: The member is “invisible”. In reality, this is only used when sending a presence a la Client.change_presence(). When you receive a user’s presence this will be offline instead.

class discord.AuditLogAction¶

Represents the type of action being done for a AuditLogEntry, which is retrievable via Guild.audit_logs().

guild_update¶

The guild has updated. Things that trigger this include:

Changing the guild vanity URL
Changing the guild invite splash
Changing the guild AFK channel or timeout
Changing the guild voice server region
Changing the guild icon, banner, or discovery splash
Changing the guild moderation settings
Changing things related to the guild widget

When this is the action, the type of target is the Guild.

Possible attributes for AuditLogDiff:

channel_create¶

A new channel was created.

When this is the action, the type of target is either a abc.GuildChannel or Object with an ID.

A more filled out object in the Object case can be found by using after.

Possible attributes for AuditLogDiff:

name
type
overwrites

channel_update¶

A channel was updated. Things that trigger this include:

The channel name or topic was changed
The channel bitrate was changed

When this is the action, the type of target is the abc.GuildChannel or Object with an ID.

A more filled out object in the Object case can be found by using after or before.

Possible attributes for AuditLogDiff:

name
type
position
overwrites
topic
bitrate
rtc_region
video_quality_mode
default_auto_archive_duration
nsfw
slowmode_delay
user_limit

channel_delete¶

A channel was deleted.

When this is the action, the type of target is an Object with an ID.

A more filled out object can be found by using the before object.

Possible attributes for AuditLogDiff:

name
type
overwrites
flags
nsfw
slowmode_delay

overwrite_create¶

A channel permission overwrite was created.

When this is the action, the type of target is the abc.GuildChannel or Object with an ID.

When this is the action, the type of extra is either a Role or Member. If the object is not found then it is a Object with an ID being filled, a name, and a type attribute set to either 'role' or 'member' to help dictate what type of ID it is.

Possible attributes for AuditLogDiff:

deny
allow
id
type

overwrite_update¶

A channel permission overwrite was changed, this is typically when the permission values change.

See overwrite_create for more information on how the target and extra fields are set.

Possible attributes for AuditLogDiff:

deny
allow
id
type

overwrite_delete¶

A channel permission overwrite was deleted.

See overwrite_create for more information on how the target and extra fields are set.

Possible attributes for AuditLogDiff:

deny
allow
id
type

kick¶

A member was kicked.

When this is the action, the type of target is the User or Object who got kicked.

When this is the action, changes is empty.

member_prune¶

A member prune was triggered.

When this is the action, the type of target is set to None.

When this is the action, the type of extra is set to an unspecified proxy object with two attributes:

delete_member_days: An integer specifying how far the prune was.
members_removed: An integer specifying how many members were removed.

When this is the action, changes is empty.

ban¶

A member was banned.

When this is the action, the type of target is the User or Object who got banned.

When this is the action, changes is empty.

unban¶

A member was unbanned.

When this is the action, the type of target is the User or Object who got unbanned.

When this is the action, changes is empty.

member_update¶

A member has updated. This triggers in the following situations:

A nickname was changed
They were server muted or deafened (or it was undo’d)

When this is the action, the type of target is the Member, User, or Object who got updated.

Possible attributes for AuditLogDiff:

nick
mute
deaf
timed_out_until

member_role_update¶

A member’s role has been updated. This triggers when a member either gains a role or loses a role.

When this is the action, the type of target is the Member, User, or Object who got the role.

Possible attributes for AuditLogDiff:

roles

member_move¶

A member’s voice channel has been updated. This triggers when a member is moved to a different voice channel.

When this is the action, the type of extra is set to an unspecified proxy object with two attributes:

channel: A TextChannel or Object with the channel ID where the members were moved.
count: An integer specifying how many members were moved.

New in version 1.3.

member_disconnect¶

A member’s voice state has changed. This triggers when a member is force disconnected from voice.

When this is the action, the type of extra is set to an unspecified proxy object with one attribute:

count: An integer specifying how many members were disconnected.

New in version 1.3.

bot_add¶

A bot was added to the guild.

When this is the action, the type of target is the Member, User, or Object which was added to the guild.

New in version 1.3.

role_create¶

A new role was created.

When this is the action, the type of target is the Role or a Object with the ID.

Possible attributes for AuditLogDiff:

colour
mentionable
hoist
icon
unicode_emoji
name
permissions

role_update¶

A role was updated. This triggers in the following situations:

The name has changed
The permissions have changed
The colour has changed
The role icon (or unicode emoji) has changed
Its hoist/mentionable state has changed

When this is the action, the type of target is the Role or a Object with the ID.

Possible attributes for AuditLogDiff:

colour
mentionable
hoist
icon
unicode_emoji
name
permissions

role_delete¶

A role was deleted.

When this is the action, the type of target is the Role or a Object with the ID.

Possible attributes for AuditLogDiff:

colour
mentionable
hoist
name
permissions

invite_create¶

An invite was created.

When this is the action, the type of target is the Invite that was created.

Possible attributes for AuditLogDiff:

max_age
code
temporary
inviter
channel
uses
max_uses

invite_update¶

An invite was updated.

When this is the action, the type of target is the Invite that was updated.

invite_delete¶

An invite was deleted.

When this is the action, the type of target is the Invite that was deleted.

Possible attributes for AuditLogDiff:

max_age
code
temporary
inviter
channel
uses
max_uses

webhook_create¶

A webhook was created.

When this is the action, the type of target is the Object with the webhook ID.

Possible attributes for AuditLogDiff:

channel
name
type (always set to 1 if so)

webhook_update¶

A webhook was updated. This trigger in the following situations:

The webhook name changed
The webhook channel changed

When this is the action, the type of target is the Object with the webhook ID.

Possible attributes for AuditLogDiff:

channel
name
avatar

webhook_delete¶

A webhook was deleted.

When this is the action, the type of target is the Object with the webhook ID.

Possible attributes for AuditLogDiff:

channel
name
type (always set to 1 if so)

emoji_create¶

An emoji was created.

When this is the action, the type of target is the Emoji or Object with the emoji ID.

Possible attributes for AuditLogDiff:

name

emoji_update¶

An emoji was updated. This triggers when the name has changed.

When this is the action, the type of target is the Emoji or Object with the emoji ID.

Possible attributes for AuditLogDiff:

name

emoji_delete¶

An emoji was deleted.

When this is the action, the type of target is the Object with the emoji ID.

Possible attributes for AuditLogDiff:

name

message_delete¶

A message was deleted by a moderator. Note that this only triggers if the message was deleted by someone other than the author.

When this is the action, the type of target is the Member, User, or Object who had their message deleted.

When this is the action, the type of extra is set to an unspecified proxy object with two attributes:

count: An integer specifying how many messages were deleted.
channel: A TextChannel or Object with the channel ID where the message got deleted.

message_bulk_delete¶

Messages were bulk deleted by a moderator.

When this is the action, the type of target is the TextChannel or Object with the ID of the channel that was purged.

When this is the action, the type of extra is set to an unspecified proxy object with one attribute:

count: An integer specifying how many messages were deleted.

New in version 1.3.

message_pin¶

A message was pinned in a channel.

When this is the action, the type of target is the Member, User, or Object who had their message pinned.

When this is the action, the type of extra is set to an unspecified proxy object with two attributes:

channel: A TextChannel or Object with the channel ID where the message was pinned.
message_id: the ID of the message which was pinned.

New in version 1.3.

message_unpin¶

A message was unpinned in a channel.

When this is the action, the type of target is the Member, User, or Object who had their message unpinned.

When this is the action, the type of extra is set to an unspecified proxy object with two attributes:

channel: A TextChannel or Object with the channel ID where the message was unpinned.
message_id: the ID of the message which was unpinned.

New in version 1.3.

integration_create¶

A guild integration was created.

When this is the action, the type of target is the Object with the integration ID of the integration which was created.

New in version 1.3.

integration_update¶

A guild integration was updated.

When this is the action, the type of target is the Object with the integration ID of the integration which was updated.

New in version 1.3.

integration_delete¶

A guild integration was deleted.

When this is the action, the type of target is the Object with the integration ID of the integration which was deleted.

New in version 1.3.

stage_instance_create¶

A stage instance was started.

When this is the action, the type of target is the StageInstance or Object with the ID of the stage instance which was created.

Possible attributes for AuditLogDiff:

topic
privacy_level

New in version 2.0.

stage_instance_update¶

A stage instance was updated.

When this is the action, the type of target is the StageInstance or Object with the ID of the stage instance which was updated.

Possible attributes for AuditLogDiff:

topic
privacy_level

New in version 2.0.

stage_instance_delete¶: A stage instance was ended.

New in version 2.0.

sticker_create¶

A sticker was created.

When this is the action, the type of target is the GuildSticker or Object with the ID of the sticker which was created.

Possible attributes for AuditLogDiff:

name
emoji
type
format_type
description
available

New in version 2.0.

sticker_update¶

A sticker was updated.

When this is the action, the type of target is the GuildSticker or Object with the ID of the sticker which was updated.

Possible attributes for AuditLogDiff:

name
emoji
type
format_type
description
available

New in version 2.0.

sticker_delete¶

A sticker was deleted.

When this is the action, the type of target is the GuildSticker or Object with the ID of the sticker which was updated.

Possible attributes for AuditLogDiff:

name
emoji
type
format_type
description
available

New in version 2.0.

scheduled_event_create¶

A scheduled event was created.

When this is the action, the type of target is the ScheduledEvent or Object with the ID of the event which was created.

Possible attributes for AuditLogDiff: - name - channel - description - privacy_level - status - entity_type - cover_image

New in version 2.0.

scheduled_event_update¶

A scheduled event was created.

When this is the action, the type of target is the ScheduledEvent or Object with the ID of the event which was updated.

Possible attributes for AuditLogDiff: - name - channel - description - privacy_level - status - entity_type - cover_image

New in version 2.0.

scheduled_event_delete¶

A scheduled event was created.

When this is the action, the type of target is the ScheduledEvent or Object with the ID of the event which was deleted.

Possible attributes for AuditLogDiff: - name - channel - description - privacy_level - status - entity_type - cover_image

New in version 2.0.

thread_create¶

A thread was created.

When this is the action, the type of target is the Thread or Object with the ID of the thread which was created.

Possible attributes for AuditLogDiff:

name
archived
locked
auto_archive_duration
invitable

New in version 2.0.

thread_update¶

A thread was updated.

When this is the action, the type of target is the Thread or Object with the ID of the thread which was updated.

Possible attributes for AuditLogDiff:

name
archived
locked
auto_archive_duration
invitable

New in version 2.0.

thread_delete¶

A thread was deleted.

When this is the action, the type of target is the Thread or Object with the ID of the thread which was deleted.

Possible attributes for AuditLogDiff:

name
archived
locked
auto_archive_duration
invitable

New in version 2.0.

automod_rule_create¶

An automod rule was created.

When this is the action, the type of target is a AutoModRule or Object with the ID of the automod rule that was created.

Possible attributes for AuditLogDiff:

name
enabled
event_type
trigger_type
trigger
actions
exempt_roles
exempt_channels

New in version 2.0.

automod_rule_update¶

An automod rule was updated.

When this is the action, the type of target is a AutoModRule or Object with the ID of the automod rule that was created.

Possible attributes for AuditLogDiff:

name
enabled
event_type
trigger_type
trigger
actions
exempt_roles
exempt_channels

New in version 2.0.

automod_rule_delete¶

An automod rule was deleted.

When this is the action, the type of target is a AutoModRule or Object with the ID of the automod rule that was created.

Possible attributes for AuditLogDiff:

name
enabled
event_type
trigger_type
trigger
actions
exempt_roles
exempt_channels

New in version 2.0.

automod_block_message¶

An automod rule blocked a message from being sent.

When this is the action, the type of target is a Member with the ID of the person who triggered the automod rule.

When this is the action, the type of extra is set to an unspecified proxy object with 3 attributes:

automod_rule_name: The name of the automod rule that was triggered.
automod_rule_trigger: A AutoModRuleTriggerType representation of the rule type that was triggered.
channel: The channel in which the automod rule was triggered.

When this is the action, AuditLogEntry.changes is empty.

New in version 2.0.

automod_flag_message¶

An automod rule flagged a message.

When this is the action, the type of target is a Member with the ID of the person who triggered the automod rule.

When this is the action, the type of extra is set to an unspecified proxy object with 3 attributes:

automod_rule_name: The name of the automod rule that was triggered.
automod_rule_trigger: A AutoModRuleTriggerType representation of the rule type that was triggered.
channel: The channel in which the automod rule was triggered.

When this is the action, AuditLogEntry.changes is empty.

New in version 2.0.

automod_timeout_member¶

An automod rule timed-out a member.

When this is the action, the type of target is a Member with the ID of the person who triggered the automod rule.

When this is the action, the type of extra is set to an unspecified proxy object with 3 attributes:

automod_rule_name: The name of the automod rule that was triggered.
automod_rule_trigger: A AutoModRuleTriggerType representation of the rule type that was triggered.
channel: The channel in which the automod rule was triggered.

When this is the action, AuditLogEntry.changes is empty.

New in version 2.0.

creator_monetization_request_created¶: A request to monetize the server was created.

New in version 2.1.

creator_monetization_terms_accepted¶: The terms and conditions for creator monetization were accepted.

New in version 2.1.

class discord.AuditLogActionCategory¶

Represents the category that the AuditLogAction belongs to.

This can be retrieved via AuditLogEntry.category.

create¶: The action is the creation of something.

delete¶: The action is the deletion of something.

update¶: The action is the update of something.

class discord.ApplicationType¶

Represents the type of an Application.

New in version 2.0.

game¶: The application is a game.

music¶: The application is music-related.

ticketed_events¶: The application can use ticketed event.

guild_role_subscriptions¶: The application can make custom guild role subscriptions.

class discord.ApplicationMembershipState¶

Represents the membership state of a TeamMember or ApplicationTester.

New in version 1.3.

Changed in version 2.0: Renamed from TeamMembershipState.

New in version 2.0.

x == y: Checks if two application states are equal.

x != y: Checks if two application states are not equal.

x > y: Checks if a application state is higher than another.

x < y: Checks if a application state is lower than another.

x >= y: Checks if a application state is higher or equal to another.

x <= y: Checks if a application state is lower or equal to another.

invited¶: Represents an invited user.

accepted¶: Represents a user that has accepted the given invite.

class discord.ApplicationVerificationState¶

Represents the verification application state of an Application.

New in version 2.0.

x == y: Checks if two application states are equal.

x != y: Checks if two application states are not equal.

x > y: Checks if a application state is higher than another.

x < y: Checks if a application state is lower than another.

x >= y: Checks if a application state is higher or equal to another.

x <= y: Checks if a application state is lower or equal to another.

ineligible¶: The application is ineligible for verification.

unsubmitted¶: The application is has not submitted a verification request.

submitted¶: The application has submitted a verification request and is pending a response.

succeeded¶: The application has been verified.

class discord.StoreApplicationState¶

Represents the commerce application state of an Application.

New in version 2.0.

x == y: Checks if two application states are equal.

x != y: Checks if two application states are not equal.

x > y: Checks if a application state is higher than another.

x < y: Checks if a application state is lower than another.

x >= y: Checks if a application state is higher or equal to another.

x <= y: Checks if a application state is lower or equal to another.

none¶: The application has not applied for commerce features.

paid¶: The application has paid the commerce feature fee.

submitted¶: The application has submitted a commerce application and is pending a response.

approved¶: The application has been approved for commerce features.

rejected¶: The application has not been approved for commerce features.

blocked¶: The application has been blocked from using commerce features.

class discord.RPCApplicationState¶

Represents the RPC application state of an Application.

New in version 2.0.

x == y: Checks if two application states are equal.

x != y: Checks if two application states are not equal.

x > y: Checks if a application state is higher than another.

x < y: Checks if a application state is lower than another.

x >= y: Checks if a application state is higher or equal to another.

x <= y: Checks if a application state is lower or equal to another.

disabled¶: The application has not applied for RPC functionality and cannot use the feature.

none¶: The application has not applied for RPC functionality and cannot use the feature.

unsubmitted¶: The application has not submitted a RPC application.

submitted¶: The application has submitted a RPC application and is pending a response.

approved¶: The application has been approved for RPC funcionality.

rejected¶: The application has not been approved for RPC funcionality.

blocked¶: The application has been blocked from using commerce features.

class discord.ApplicationDiscoverabilityState¶

Represents the discoverability state of an Application.

New in version 2.0.

x == y: Checks if two application states are equal.

x != y: Checks if two application states are not equal.

x > y: Checks if a application state is higher than another.

x < y: Checks if a application state is lower than another.

x >= y: Checks if a application state is higher or equal to another.

x <= y: Checks if a application state is lower or equal to another.

ineligible¶: The application is ineligible for appearing on app discovery.

not_discoverable¶: The application is not discoverable on app discovery.

discoverable¶: The application is discoverable on app discovery.

featureable¶: The application is featureable on app discovery.

blocked¶: The application is blocked from appearing on app discovery.

class discord.ApplicationBuildStatus¶

Represents the status of an ApplicationBuild.

New in version 2.0.

created¶: The build has been created.

uploading¶: The build is being uploaded.

uploaded¶: The build has been uploaded.

validating¶: The build is being validated.

invalid¶: The build is invalid.

corrupted¶: The build is corrupted.

ready¶: The build is ready to be published.

class discord.EmbeddedActivityPlatform¶

Represents an available platform for a EmbeddedActivityConfig.

New in version 2.0.

web¶: The activity is available on web/desktop.

ios¶: The activity is available on iOS.

android¶: The activity is available on Android.

class discord.EmbeddedActivityOrientation¶

Represents an orientation capability of a EmbeddedActivityConfig.

This is only used by mobile clients.

New in version 2.0.

unlocked¶: The activity can be rotated.

portrait¶: The activity is locked to portrait.

landscape¶: The activity is locked to landscape.

class discord.EmbeddedActivityLabelType¶

Represents the label shown by an embedded activity.

New in version 2.1.

none¶: No special label.

new¶: The activity is new.

updated¶: The activity has been recently updated.

class discord.EmbeddedActivityReleasePhase¶

Represents the release phase of an embedded activity for a specific EmbeddedActivityPlatform.

New in version 2.1.

in_development¶: The activity is still in development.

activities_team¶: The activity is available to guilds with the ACTIVITIES_INTERNAL_DEV guild feature.

employee_release¶: The activity is available to guilds with the ACTIVITIES_EMPLOYEE guild feature.

soft_launch¶: The activity is available to guilds with the ACTIVITIES_ALPHA guild feature.

global_launch¶: The activity is available to all guilds.

class discord.PayoutAccountStatus¶

Represents the status of a team payout account.

New in version 2.0.

unsubmitted¶: The payout account application has not been submitted.

pending¶: The payout account is pending.

action_required¶: The payout account requires action.

active¶: The payout account is active.

blocked¶: The payout account is blocked.

suspended¶: The payout account is suspended.

class discord.PayoutStatus¶

Represents the status of a team payout.

New in version 2.0.

open¶: The payout is open.

paid¶: The payout has been paid out.

pending¶: The payout is pending.

manual¶: The payout has been manually made.

cancelled¶: The payout has been cancelled.

canceled¶: An alias for cancelled.

deferred¶: The payout has been deferred.

deferred_internal¶: The payout has been deferred internally.

processing¶: The payout is processing.

error¶: The payout has an error.

rejected¶: The payout has been rejected.

risk_review¶: The payout is under risk review.

submitted¶: The payout has been submitted.

pending_funds¶: The payout is pending sufficient funds.

class discord.PayoutReportType¶

Represents the type of downloadable payout report.

New in version 2.0.

by_sku¶: The payout report is by SKU.

by_transaction¶: The payout report is by transaction.

class discord.WebhookType¶

Represents the type of webhook that can be received.

New in version 1.3.

incoming¶: Represents a webhook that can post messages to channels with a token.

channel_follower¶: Represents a webhook that is internally managed by Discord, used for following channels.

application¶: Represents a webhook that is used for interactions or applications.

New in version 2.0.

class discord.ExpireBehaviour¶

Represents the behaviour the Integration should perform when a user’s subscription has finished.

There is an alias for this called ExpireBehavior.

New in version 1.4.

remove_role¶: This will remove the StreamIntegration.role from the user when their subscription is finished.

kick¶: This will kick the user when their subscription is finished.

class discord.DefaultAvatar¶

Represents the default avatar of a Discord User

blurple¶: Represents the default avatar with the colour blurple. See also Colour.blurple

grey¶: Represents the default avatar with the colour grey. See also Colour.greyple

gray¶: An alias for grey.

green¶: Represents the default avatar with the colour green. See also Colour.green

orange¶: Represents the default avatar with the colour orange. See also Colour.orange

red¶: Represents the default avatar with the colour red. See also Colour.red

pink¶: Represents the default avatar with the colour pink. See also Colour.pink

class discord.StickerType¶

Represents the type of sticker.

New in version 2.0.

standard¶: Represents a standard sticker that all Nitro users can use.

guild¶: Represents a custom sticker created in a guild.

class discord.StickerFormatType¶

Represents the type of sticker images.

New in version 1.6.

png¶: Represents a sticker with a png image.

apng¶: Represents a sticker with an apng image.

lottie¶: Represents a sticker with a lottie image.

gif¶: Represents a sticker with a gif image.

New in version 2.0.

class discord.InviteTarget¶

Represents the invite type for voice channel invites.

New in version 2.0.

unknown¶: The invite doesn’t target anyone or anything.

stream¶: A stream invite that targets a user.

embedded_application¶: A stream invite that targets an embedded application.

role_subscriptions¶: A guild invite that redirects to the role subscriptions page of a guild when accepted.

New in version 2.0.

creator_page¶: A guild invite that originates from the creator page of a guild.

New in version 2.0.

class discord.VideoQualityMode¶

Represents the camera video quality mode for voice channel participants.

New in version 2.0.

auto¶: Represents auto camera video quality.

full¶: Represents full camera video quality.

class discord.PrivacyLevel¶

Represents the privacy level of a stage instance or scheduled event.

New in version 2.0.

guild_only¶: The stage instance or scheduled event is only accessible within the guild.

class discord.NSFWLevel¶

Represents the NSFW level of a guild.

New in version 2.0.

x == y: Checks if two NSFW levels are equal.

x != y: Checks if two NSFW levels are not equal.

x > y: Checks if a NSFW level is higher than another.

x < y: Checks if a NSFW level is lower than another.

x >= y: Checks if a NSFW level is higher or equal to another.

x <= y: Checks if a NSFW level is lower or equal to another.

default¶: The guild has not been categorised yet.

explicit¶: The guild contains NSFW content.

safe¶: The guild does not contain any NSFW content.

age_restricted¶: The guild may contain NSFW content.

class discord.RelationshipType¶

Specifies the type of Relationship.

friend¶: You are friends with this user.

blocked¶: You have blocked this user.

incoming_request¶: The user has sent you a friend request.

outgoing_request¶: You have sent a friend request to this user.

implicit¶: You frecently interact with this user. See UserAffinity for more information.

New in version 2.0.

class discord.FriendSuggestionReasonType¶

Specifies the type of FriendSuggestionReason.

New in version 2.1.

external_friend¶: You are friends with this user on another platform.

class discord.UserContentFilter¶

Represents the options found in Settings > Privacy & Safety > Safe Direct Messaging in the Discord client.

all_messages¶: Scan all direct messages from everyone.

non_friends¶: Scan all direct messages that aren’t from friends.

disabled¶: Don’t scan any direct messages.

class discord.PremiumType¶

Represents the user’s Discord Nitro subscription type.

none¶: The user does not have a Discord Nitro subscription.

New in version 2.0.

nitro¶: Represents the new, full Discord Nitro.

nitro_classic¶: Represents the classic Discord Nitro.

nitro_basic¶: Represents the basic Discord Nitro.

New in version 2.0.

class discord.PaymentSourceType¶

Represents the type of a payment source.

New in version 2.0.

unknown¶: The payment source is unknown.

credit_card¶: The payment source is a credit card.

paypal¶: The payment source is a PayPal account.

giropay¶: The payment source is a Giropay account.

sofort¶: The payment source is a Sofort account.

przelewy24¶: The payment source is a Przelewy24 account.

sepa_debit¶: The payment source is a SEPA debit account.

paysafecard¶: The payment source is a Paysafe card.

gcash¶: The payment source is a GCash account.

grabpay¶: The payment source is a GrabPay (Malaysia) account.

momo_wallet¶: The payment source is a MoMo Wallet account.

venmo¶: The payment source is a Venmo account.

gopay_wallet¶: The payment source is a GoPay Wallet account.

kakaopay¶: The payment source is a KakaoPay account.

bancontact¶: The payment source is a Bancontact account.

eps¶: The payment source is an EPS account.

ideal¶: The payment source is an iDEAL account.

cash_app¶: The payment source is a Cash App account.

New in version 2.1.

class discord.PaymentGateway¶

Represents the payment gateway used for a payment source.

New in version 2.0.

stripe¶: The payment source is a Stripe payment source.

braintree¶: The payment source is a Braintree payment source.

apple¶: The payment source is an Apple payment source.

google¶: The payment source is a Google payment source.

adyen¶: The payment source is an Adyen payment source.

apple_pay¶: The payment source is an Apple Pay payment source (unconfirmed).

class discord.SubscriptionType¶

Represents the type of a subscription.

New in version 2.0.

premium¶: The subscription is a Discord premium (Nitro) subscription.

guild¶: The subscription is a guild role subscription.

application¶: The subscription is an application subscription.

class discord.SubscriptionStatus¶

Represents the status of a subscription.

New in version 2.0.

unpaid¶: The subscription is unpaid.

active¶: The subscription is active.

past_due¶: The subscription is past due.

canceled¶: The subscription is canceled.

ended¶: The subscription has ended.

inactive¶: The subscription is inactive.

account_hold¶: The subscription is on account hold.

class discord.SubscriptionInvoiceStatus¶

Represents the status of a subscription invoice.

New in version 2.0.

x == y: Checks if two subscription invoice statuses are equal.

x != y: Checks if two subscription invoice statuses are not equal.

x > y: Checks if a subscription invoice status is higher than another.

x < y: Checks if a subscription invoice status is lower than another.

x >= y: Checks if a subscription invoice status is higher or equal to another.

x <= y: Checks if a subscription invoice status is lower or equal to another.

open¶: The invoice is open.

paid¶: The invoice is paid.

void¶: The invoice is void.

uncollectible¶: The invoice is uncollectible.

class discord.SubscriptionDiscountType¶

Represents the type of a subscription discount.

New in version 2.0.

subscription_plan¶: The discount is from an existing subscription plan’s remaining credit.

entitlement¶: The discount is from an applied entitlement.

premium_legacy_upgrade_promotion¶: The discount is from a legacy premium plan promotion discount.

premium_trial¶: The discount is from a premium trial.

class discord.SubscriptionInterval¶

Represents the interval of a subscription.

New in version 2.0.

month¶: The subscription is billed monthly.

year¶: The subscription is billed yearly.

day¶: The subscription is billed daily.

class discord.SubscriptionPlanPurchaseType¶

Represents the different types of subscription plan purchases.

New in version 2.0.

default¶: The plan is purchased with default pricing.

gift¶: The plan is purchased with gift pricing.

sale¶: The plan is purchased with sale pricing.

nitro_classic¶: The plan is purchased with Nitro Classic discounted pricing.

nitro¶: The plan is purchased with Nitro discounted pricing.

class discord.PaymentStatus¶

Represents the status of a payment.

New in version 2.0.

pending¶: The payment is pending.

completed¶: The payment has gone through.

failed¶: The payment has failed.

reversed¶: The payment has been reversed.

refunded¶: The payment has been refunded.

cancelled¶: The payment has been canceled.

canceled¶: An alias for PaymentStatus.cancelled.

class discord.EntitlementType¶

Represents the type of an entitlement.

New in version 2.0.

purchase¶: The entitlement is from a purchase.

premium_subscription¶: The entitlement is a Discord premium subscription.

developer_gift¶: The entitlement is gifted by the developer.

test_mode_purchase¶: The entitlement is from a free test mode purchase.

free_purchase¶: The entitlement is a free purchase.

user_gift¶: The entitlement is gifted by a user.

premium_purchase¶: The entitlement is a premium subscription perk.

application_subscription¶: The entitlement is an application subscription.

class discord.RefundReason¶

Represents the reason for a refund.

New in version 2.1.

other¶: The refund is due to another reason.

gifting_refund¶: The refund is due to an unwanted gift.

buyers_remorse¶: The refund is due to buyer’s remorse.

wrong_purchase¶: The refund is due to a wrong purchase.

forgot_to_cancel¶: The refund is due to forgetting to cancel a subscription.

premium_guild_cooldown¶: The refund is due to a premium guild (boosting) cooldown.

user_confusion¶: The refund is due to user confusion.

want_to_switch_tiers¶: The refund is due to wanting to switch premium (Nitro) tiers.

dont_need¶: The refund is due to not needing the purchase.

class discord.RefundDisqualificationReason¶

Represents the reason for a refund disqualification.

New in version 2.1.

other¶: The purchase is disqualified from a refund due to another reason.

already_refunded¶: The purchase is disqualified from a refund because it has already been refunded.

not_user_refundable_type¶: The purchase is disqualified from a refund because it is not a user refundable type. The user must contact Discord support to request a refund.

past_refundable_date¶: The purchase is disqualified from a refund because it is past the refundable date.

entitlement_already_consumed¶: The purchase is disqualified from a refund because the purchased entitlement has already been consumed.

already_refunded_premium¶: The purchase is disqualified from a refund because the user has already refunded a premium (Nitro) purchase.

already_refunded_premium_guild¶: The purchase is disqualified from a refund because the user has already refunded a premium guild (boosting) purchase.

class discord.SKUType¶

Represents the type of a SKU.

New in version 2.0.

durable_primary¶: Represents a primary SKU (game).

durable¶: Represents a DLC.

consumable¶: Represents a IAP (in-app purchase).

bundle¶: Represents a bundle comprising the above.

subscription¶: Represents a subscription-only SKU.

group¶: Represents a group of SKUs.

class discord.SKUAccessLevel¶

Represents the access level of a SKU.

New in version 2.0.

full¶: The SKU is available to all users.

early_access¶: The SKU is available in early access only.

vip_access¶: The SKU is available to VIP users only.

class discord.SKUProductLine¶

Represents the product line of a SKU.

New in version 2.1.

premium¶: The SKU is a premium (Nitro) product.

premium_guild¶: The SKU is a premium guild product.

iap¶: The SKU is an embedded in-app purchase.

guild_role¶: The SKU is a guild role subscription.

guild_product¶: The SKU is a guild product.

application¶: The SKU is an application subscription.

collectible¶: The SKU is a collectible avatar decoration or profile effect.

class discord.SKUFeature¶

Represents a feature of a SKU.

New in version 2.0.

single_player¶: The SKU supports single player.

online_multiplayer¶: The SKU supports online multiplayer.

local_multiplayer¶: The SKU supports local multiplayer.

pvp¶: The SKU supports PvP.

local_coop¶: The SKU supports local co-op.

cross_platform¶: The SKU supports cross-platform play.

rich_presence¶: The SKU supports rich presence.

discord_game_invites¶: The SKU supports Discord game invites.

spectator_mode¶: The SKU supports spectator mode.

controller_support¶: The SKU supports controller support.

cloud_saves¶: The SKU supports cloud saves.

online_coop¶: The SKU supports online co-op.

secure_networking¶: The SKU supports secure networking.

class discord.SKUGenre¶

Represents the genre of a SKU.

New in version 2.0.

action¶: The SKU is an action game.

action_adventure¶: The SKU is an action-adventure game.

action_rpg¶: The SKU is an action RPG.

adventure¶: The SKU is an adventure game.

artillery¶: The SKU is an artillery game.

baseball¶: The SKU is a baseball game.

basketball¶: The SKU is a basketball game.

billiards¶: The SKU is a billiards game.

bowling¶: The SKU is a bowling game.

boxing¶: The SKU is a boxing game.

brawler¶: The SKU is a brawler.

card_game¶: The SKU is a card game.

driving_racing¶: The SKU is a driving/racing game.

dual_joystick_shooter¶: The SKU is a dual joystick shooter.

dungeon_crawler¶: The SKU is a dungeon crawler.

education¶: The SKU is an education game.

fighting¶: The SKU is a fighting game.

fishing¶: The SKU is a fishing game.

fitness¶: The SKU is a fitness game.

flight_simulator¶: The SKU is a flight simulator.

football¶: The SKU is a football game.

four_x¶: The SKU is a 4X game.

fps¶: The SKU is a first-person shooter.

gambling¶: The SKU is a gambling game.

golf¶: The SKU is a golf game.

hack_and_slash¶: The SKU is a hack-and-slash game.

hockey¶: The SKU is a hockey game.

life_simulator¶: The SKU is a life simulator.

light_gun¶: The SKU is a light gun game.

massively_multiplayer¶: The SKU is a massively multiplayer game.

music¶: The SKU is a music game.

party¶: The SKU is a party game.

pinball¶: The SKU is a pinball game.

platformer¶: The SKU is a platformer.

point_and_click¶: The SKU is a point-and-click game.

puzzle¶: The SKU is a puzzle game.

rpg¶: The SKU is an RPG.

role_playing¶: The SKU is a role-playing game.

rts¶: The SKU is a real-time strategy game.

sandbox¶: The SKU is a sandbox game.

shooter¶: The SKU is a shooter.

shoot_em_up¶: The SKU is a shoot ‘em up game.

simulation¶: The SKU is a simulation game.

skateboarding_skating¶: The SKU is a skateboarding/skating game.

snowboarding_skiing¶: The SKU is a snowboarding/skiing game.

soccer¶: The SKU is a soccer game.

sports¶: The SKU is a sports game.

stealth¶: The SKU is a stealth game.

strategy¶: The SKU is a strategy game.

surfing_wakeboarding¶: The SKU is a surfing/wakeboarding game.

survival¶: The SKU is a survival game.

tennis¶: The SKU is a tennis game.

third_person_shooter¶: The SKU is a third-person shooter.

turn_based_strategy¶: The SKU is a turn-based strategy game.

vehicular_combat¶: The SKU is a vehicular combat game.

visual_novel¶: The SKU is a visual novel.

wargame¶: The SKU is a wargame.

wrestling¶: The SKU is a wrestling game.

class discord.ContentRatingAgency¶

Represents the content rating agency of a SKU.

New in version 2.0.

esrb¶: The ESRB.

pegi¶: The PEGI system.

class discord.ESRBRating¶

Represents the ESRB rating of a SKU.

New in version 2.0.

everyone¶: The SKU is rated E for everyone.

everyone_ten_plus¶: The SKU is rated E10+ for everyone ten and older.

teen¶: The SKU is rated T for teen.

mature¶: The SKU is rated M for mature.

adults_only¶: The SKU is rated AO for adults only.

rating_pending¶: The SKU is pending a rating.

class discord.PEGIRating¶

Represents the PEGI rating of a SKU.

New in version 2.0.

three¶: The SKU is rated 3.

seven¶: The SKU is rated 7.

twelve¶: The SKU is rated 12.

sixteen¶: The SKU is rated 16.

eighteen¶: The SKU is rated 18.

class discord.ESRBContentDescriptor¶

Represents an ESRB rating content descriptor.

New in version 2.0.

alcohol_reference¶: The SKU contains alcohol references.

animated_blood¶: The SKU contains animated blood.

blood¶: The SKU contains blood.

blood_and_gore¶: The SKU contains blood and gore.

cartoon_violence¶: The SKU contains cartoon violence.

comic_mischief¶: The SKU contains comic mischief.

crude_humor¶: The SKU contains crude humor.

drug_reference¶: The SKU contains drug references.

fantasy_violence¶: The SKU contains fantasy violence.

intense_violence¶: The SKU contains intense violence.

language¶: The SKU contains language.

lyrics¶: The SKU contains lyrics.

mature_humor¶: The SKU contains mature humor.

nudity¶: The SKU contains nudity.

partial_nudity¶: The SKU contains partial nudity.

real_gambling¶: The SKU contains real gambling.

sexual_content¶: The SKU contains sexual content.

sexual_themes¶: The SKU contains sexual themes.

sexual_violence¶: The SKU contains sexual violence.

simulated_gambling¶: The SKU contains simulated gambling.

strong_language¶: The SKU contains strong language.

strong_lyrics¶: The SKU contains strong lyrics.

strong_sexual_content¶: The SKU contains strong sexual content.

suggestive_themes¶: The SKU contains suggestive themes.

tobacco_reference¶: The SKU contains tobacco references.

use_of_alcohol¶: The SKU contains use of alcohol.

use_of_drugs¶: The SKU contains use of drugs.

use_of_tobacco¶: The SKU contains use of tobacco.

violence¶: The SKU contains violence.

violent_references¶: The SKU contains violent references.

in_game_purchases¶: The SKU provides in-game purchases.

users_interact¶: The SKU allows users to interact.

shares_location¶: The SKU shares your location.

unrestricted_internet¶: The SKU has unrestricted internet access.

mild_blood¶: The SKU contains mild blood.

mild_cartoon_violence¶: The SKU contains mild cartoon violence.

mild_fantasy_violence¶: The SKU contains mild fantasy violence.

mild_language¶: The SKU contains mild language.

mild_lyrics¶: The SKU contains mild inappropriate lyrics.

mild_sexual_themes¶: The SKU contains mild sexual themes.

mild_suggestive_themes¶: The SKU contains mild suggestive themes.

mild_violence¶: The SKU contains mild violence.

animated_violence¶: The SKU contains animated violence.

class discord.PEGIContentDescriptor¶

Represents a PEGI rating content descriptor.

New in version 2.0.

violence¶: The SKU contains violence.

bad_language¶: The SKU contains bad language.

fear¶: The SKU instills fear.

gambling¶: The SKU contains gambling.

sex¶: The SKU contains sexual themes.

drugs¶: The SKU contains drug references.

discrimination¶: The SKU contains discrimination.

class discord.Distributor¶

Represents the distributor of a third-party SKU on Discord.

New in version 2.0.

discord¶: The SKU is distributed by Discord.

steam¶: The SKU is distributed by Steam.

twitch¶: The SKU is distributed by Twitch.

uplay¶: The SKU is distributed by Ubisoft Connect.

battle_net¶: The SKU is distributed by Battle.net.

origin¶: The SKU is distributed by Origin.

gog¶: The SKU is distributed by GOG.

epic_games¶: The SKU is distributed by Epic Games.

google_play¶: The SKU is distributed by Google Play.

class discord.OperatingSystem¶

Represents the operating system of a SKU’s system requirements.

New in version 2.0.

windows¶: Represents Windows.

mac¶: Represents macOS.

linux¶: Represents Linux.

class discord.StickerAnimationOptions¶

Represents the options found in Settings > Accessibility > Stickers in the Discord client.

always¶: Always animate stickers.

on_interaction¶: Animate stickers when they are interacted with.

never¶: Never animate stickers.

class discord.SpoilerRenderOptions¶

Represents the options found in Settings > Text and Images > Show Spoiler Content in the Discord client.

New in version 2.0.

always¶: Always render spoilers.

on_click¶: Render spoilers when they are interacted with.

if_moderator¶: Render spoilers if the user is a moderator.

class discord.InboxTab¶

Represents the tabs found in the Discord inbox.

New in version 2.0.

default¶: No inbox tab has been yet selected.

mentions¶: The mentions tab.

unreads¶: The unreads tab.

todos¶: The todos tab.

for_you¶: The for you tab.

class discord.EmojiPickerSection¶

Represents the sections found in the Discord emoji picker. Any guild is also a valid section.

New in version 2.0.

favorite¶: The favorite section.

top_emojis¶: The top emojis section.

recent¶: The recents section.

people¶: The people emojis section.

nature¶: The nature emojis section.

food¶: The food emojis section.

activity¶: The activity emojis section.

travel¶: The travel emojis section.

objects¶: The objects emojis section.

symbols¶: The symbols emojis section.

flags¶: The flags emojis section.

class discord.StickerPickerSection¶

Represents the sections found in the Discord sticker picker. Any guild and sticker pack SKU is also a valid section.

New in version 2.0.

favorite¶: The favorite section.

recent¶: The recents section.

class discord.Theme¶

Represents the theme synced across all Discord clients.

light¶: Represents the Light theme on Discord.

dark¶: Represents the Dark theme on Discord.

class discord.Locale¶

Supported locales by Discord.

New in version 2.0.

american_english¶: The en-US locale.

arabic¶: The ar locale.

New in version 2.1.

british_english¶: The en-GB locale.

bulgarian¶: The bg locale.

chinese¶: The zh-CN locale.

taiwan_chinese¶: The zh-TW locale.

croatian¶: The hr locale.

czech¶: The cs locale.

danish¶: The da locale.

dutch¶: The nl locale.

finnish¶: The fi locale.

french¶: The fr locale.

german¶: The de locale.

greek¶: The el locale.

hindi¶: The hi locale.

hungarian¶: The hu locale.

indonesian¶: The id locale.

italian¶: The it locale.

japanese¶: The ja locale.

korean¶: The ko locale.

latin_american_spanish¶: The es-419 locale.

New in version 2.1.

lithuanian¶: The lt locale.

norwegian¶: The no locale.

polish¶: The pl locale.

brazil_portuguese¶: The pt-BR locale.

romanian¶: The ro locale.

russian¶: The ru locale.

spain_spanish¶: The es-ES locale.

swedish¶: The sv-SE locale.

thai¶: The th locale.

turkish¶: The tr locale.

ukrainian¶: The uk locale.

vietnamese¶: The vi locale.

class discord.MFALevel¶

Represents the Multi-Factor Authentication requirement level of a guild.

New in version 2.0.

x == y: Checks if two MFA levels are equal.

x != y: Checks if two MFA levels are not equal.

x > y: Checks if a MFA level is higher than another.

x < y: Checks if a MFA level is lower than another.

x >= y: Checks if a MFA level is higher or equal to another.

x <= y: Checks if a MFA level is lower or equal to another.

disabled¶: The guild has no MFA requirement.

require_2fa¶: The guild requires 2 factor authentication.

class discord.EntityType¶

Represents the type of entity that a scheduled event is for.

New in version 2.0.

stage_instance¶: The scheduled event will occur in a stage instance.

voice¶: The scheduled event will occur in a voice channel.

external¶: The scheduled event will occur externally.

class discord.EventStatus¶

Represents the status of an event.

New in version 2.0.

scheduled¶: The event is scheduled.

active¶: The event is active.

completed¶: The event has ended.

cancelled¶: The event has been cancelled.

canceled¶: An alias for cancelled.

ended¶: An alias for completed.

class discord.RequiredActionType¶

Represents an action Discord requires the user to take.

New in version 2.0.

update_agreements¶: The user must update their agreement of Discord’s terms of service and privacy policy. This does not limit the user from using Discord.

complete_captcha¶: The user must complete a captcha.

verify_email¶: The user must add and verify an email address to their account.

reverify_email¶: The user must reverify their existing email address.

verify_phone¶: The user must add a phone number to their account.

reverify_phone¶: The user must reverify their existing phone number.

reverify_email_or_verify_phone¶: The user must reverify their existing email address or add a phone number to their account.

verify_email_or_reverify_phone¶: The user must add and verify an email address to their account or reverify their existing phone number.

reverify_email_or_reverify_phone¶: The user must reverify their existing email address or reverify their existing phone number.

class discord.ConnectionType¶

Represents the type of connection a user has with Discord.

New in version 2.0.

battle_net¶: The user has a Battle.net connection.

contacts¶: The user has a contact sync connection.

crunchyroll¶: The user has a Crunchyroll connection.

ebay¶: The user has an eBay connection.

epic_games¶: The user has an Epic Games connection.

facebook¶: The user has a Facebook connection.

github¶: The user has a GitHub connection.

instagram¶: The user has Instagram connection.

New in version 2.1.

league_of_legends¶: The user has a League of Legends connection.

paypal¶: The user has a PayPal connection.

playstation¶: The user has a PlayStation connection.

reddit¶: The user has a Reddit connection.

riot_games¶: The user has a Riot Games connection.

samsung¶: The user has a Samsung Account connection.

spotify¶: The user has a Spotify connection.

skype¶: The user has a Skype connection.

steam¶: The user has a Steam connection.

tiktok¶: The user has a TikTok connection.

twitch¶: The user has a Twitch connection.

twitter¶: The user has a Twitter connection.

youtube¶: The user has a YouTube connection.

xbox¶: The user has an Xbox Live connection.

class discord.ClientType¶

Represents a type of Discord client.

New in version 2.0.

web¶: Represents the web client.

mobile¶: Represents a mobile client.

desktop¶: Represents a desktop client.

unknown¶: Represents an unknown client.

class discord.GiftStyle¶

Represents the special style of a gift.

New in version 2.0.

snowglobe¶: The gift is a snowglobe.

box¶: The gift is a box.

class discord.InteractionType¶

Specifies the type of Interaction.

New in version 2.0.

application_command¶: Represents a slash command interaction.

component¶: Represents a component based interaction, i.e. clicking a button.

autocomplete¶: Represents an autocomplete interaction.

modal_submit¶: Represents submission of a modal interaction.

class discord.ComponentType¶

Represents the component type of a component.

New in version 2.0.

action_row¶: Represents the group component which holds different components in a row.

button¶: Represents a button component.

select¶: Represents a select component.

text_input¶: Represents a text box component.

class discord.ButtonStyle¶

Represents the style of the button component.

New in version 2.0.

primary¶: Represents a blurple button for the primary action.

secondary¶: Represents a grey button for the secondary action.

success¶: Represents a green button for a successful action.

danger¶: Represents a red button for a dangerous action.

link¶: Represents a link button.

blurple¶: An alias for primary.

grey¶: An alias for secondary.

gray¶: An alias for secondary.

green¶: An alias for success.

red¶: An alias for danger.

url¶: An alias for link.

class discord.TextStyle¶

Represents the style of the text box component.

New in version 2.0.

short¶: Represents a short text box.

paragraph¶: Represents a long form text box.

long¶: An alias for paragraph.

class discord.ApplicationCommandType¶

The type of application command.

New in version 2.0.

chat_input¶: A slash command.

user¶: A user context menu command.

message¶: A message context menu command.

class discord.ApplicationCommandOptionType¶

The application command’s option type. This is usually the type of parameter an application command takes.

New in version 2.0.

subcommand¶: A subcommand.

subcommand_group¶: A subcommand group.

string¶: A string parameter.

integer¶: A integer parameter.

boolean¶: A boolean parameter.

user¶: A user parameter.

channel¶: A channel parameter.

role¶: A role parameter.

mentionable¶: A mentionable parameter.

number¶: A number parameter.

attachment¶: An attachment parameter.

class discord.AutoModRuleTriggerType¶

Represents the trigger type of an automod rule.

New in version 2.0.

keyword¶: The rule will trigger when a keyword is mentioned.

harmful_link¶: The rule will trigger when a harmful link is posted.

spam¶: The rule will trigger when a spam message is posted.

keyword_preset¶: The rule will trigger when something triggers based on the set keyword preset types.

mention_spam¶: The rule will trigger when combined number of role and user mentions is greater than the set limit.

class discord.AutoModRuleEventType¶

Represents the event type of an automod rule.

New in version 2.0.

message_send¶: The rule will trigger when a message is sent.

class discord.AutoModRuleActionType¶

Represents the action type of an automod rule.

New in version 2.0.

block_message¶: The rule will block a message from being sent.

send_alert_message¶: The rule will send an alert message to a predefined channel.

timeout¶: The rule will timeout a user.

class discord.ForumLayoutType¶

Represents how a forum’s posts are layed out in the client.

New in version 2.0.

not_set¶: No default has been set, so it is up to the client to know how to lay it out.

list_view¶: Displays posts as a list.

gallery_view¶: Displays posts as a collection of tiles.

class discord.ForumOrderType¶

Represents how a forum’s posts are sorted in the client.

New in version 2.0.

latest_activity¶: Sort forum posts by activity.

creation_date¶: Sort forum posts by creation time (from most recent to oldest).

class discord.ReadStateType¶

Represents the type of a read state.

New in version 2.1.

channel¶: Represents a regular, channel-bound read state for messages.

scheduled_events¶: Represents a guild-bound read state for scheduled events. Only one exists per guild.

notification_center¶: Represents a global read state for the notification center. Only one exists.

guild_home¶: Represents a guild-bound read state for guild home. Only one exists per guild.

onboarding¶: Represents a guild-bound read state for guild onboarding. Only one exists per guild.

class discord.DirectoryEntryType¶

Represents the type of a directory entry.

New in version 2.1.

guild¶: Represents a guild directory entry.

scheduled_event¶: Represents a broadcasted scheduled event directory entry.

class discord.DirectoryCategory¶

Represents the category of a directory entry.

New in version 2.1.

uncategorized¶: The directory entry is uncategorized.

school_club¶: The directory entry is a school club.

class_subject¶: The directory entry is a class/subject.

study_social¶: The directory entry is a study/social venue.

miscellaneous¶: The directory entry is miscellaneous.

class discord.HubType¶

Represents the type of Student Hub a guild is.

New in version 2.1.

default¶: The Student Hub is not categorized as a high school or post-secondary institution.

high_school¶: The Student Hub is for a high school.

college¶: The Student Hub is for a post-secondary institution (college or university).

university¶: An alias for college.

Audit Log Data¶

Working with Guild.audit_logs() is a complicated process with a lot of machinery involved. The library attempts to make it easy to use and friendly. In order to accomplish this goal, it must make use of a couple of data classes that aid in this goal.

AuditLogEntry¶

Attributes

action
after
before
category
changes
created_at
extra
guild
id
reason
target
user
user_id

class discord.AuditLogEntry(*, users, automod_rules, webhooks, data, guild)¶

Represents an Audit Log entry.

You retrieve these via Guild.audit_logs().

x == y: Checks if two entries are equal.

x != y: Checks if two entries are not equal.

hash(x): Returns the entry’s hash.

Changed in version 1.7: Audit log entries are now comparable and hashable.

action¶

The action that was done.

Type: AuditLogAction

user¶

The user who initiated this action. Usually a Member, unless gone then it’s a User.

Type: Optional[abc.User]

user_id¶

The user ID who initiated this action.

New in version 2.0.

Type: Optional[int]

id¶

The entry ID.

Type: int

guild¶

The guild that this entry belongs to.

Type: Guild

target¶

The target that got changed. The exact type of this depends on the action being done.

Type: Any

reason¶

The reason this action was done.

Type: Optional[str]

extra¶

Extra information that this entry has that might be useful. For most actions, this is None. However in some cases it contains extra information. See AuditLogAction for which actions have this field filled out.

Type: Any

created_at¶

Returns the entry’s creation time in UTC.

Type: datetime.datetime

category¶

The category of the action, if applicable.

Type: Optional[AuditLogActionCategory]

changes¶

The list of changes this entry has.

Type: AuditLogChanges

before¶

The target’s prior state.

Type: AuditLogDiff

after¶

The target’s subsequent state.

Type: AuditLogDiff

AuditLogChanges¶

Attributes

after
before

class discord.AuditLogChanges¶

An audit log change set.

before¶

The old value. The attribute has the type of AuditLogDiff.

Depending on the AuditLogActionCategory retrieved by category, the data retrieved by this attribute differs:

Category	Description
`create`	All attributes are set to `None`.
`delete`	All attributes are set the value before deletion.
`update`	All attributes are set the value before updating.
`None`	No attributes are set.

after¶

The new value. The attribute has the type of AuditLogDiff.

Depending on the AuditLogActionCategory retrieved by category, the data retrieved by this attribute differs:

Category	Description
`create`	All attributes are set to the created value
`delete`	All attributes are set to `None`
`update`	All attributes are set the value after updating.
`None`	No attributes are set.

AuditLogDiff¶

Attributes

actions
afk_channel
afk_timeout
allow
application_id
applied_tags
archived
auto_archive_duration
available
available_tags
avatar
banner
bitrate
channel
code
color
colour
cover_image
deaf
default_auto_archive_duration
default_notifications
default_reaction_emoji
default_thread_slowmode_delay
deny
description
discovery_splash
emoji
enable_emoticons
enabled
entity_type
event_type
exempt_channels
exempt_roles
expire_behavior
expire_behaviour
expire_grace_period
explicit_content_filter
flags
format_type
guild
hoist
icon
id
invitable
inviter
locked
max_age
max_uses
mentionable
mfa_level
mute
name
nick
nsfw
overwrites
owner
permissions
position
preferred_locale
premium_progress_bar_enabled
privacy_level
prune_delete_days
public_updates_channel
roles
rtc_region
rules_channel
slowmode_delay
splash
status
system_channel
system_channel_flags
temporary
timed_out_until
topic
trigger
trigger_type
type
unicode_emoji
user_limit
uses
vanity_url_code
verification_level
video_quality_mode
widget_channel
widget_enabled

class discord.AuditLogDiff¶

Represents an audit log “change” object. A change object has dynamic attributes that depend on the type of action being done. Certain actions map to certain attributes being set.

Note that accessing an attribute that does not match the specified action will lead to an attribute error.

To get a list of attributes that have been set, you can iterate over them. To see a list of all possible attributes that could be set based on the action being done, check the documentation for AuditLogAction, otherwise check the documentation below for all attributes that are possible.

iter(diff): Returns an iterator over (attribute, value) tuple of this diff.

name¶

A name of something.

Type: str

guild¶

The guild of something.

Type: Guild

icon¶

A guild’s or role’s icon. See also Guild.icon or Role.icon.

Type: Asset

splash¶

The guild’s invite splash. See also Guild.splash.

Type: Asset

discovery_splash¶

The guild’s discovery splash. See also Guild.discovery_splash.

Type: Asset

banner¶

The guild’s banner. See also Guild.banner.

Type: Asset

owner¶

The guild’s owner. See also Guild.owner

Type: Union[Member, User]

application_id¶

The application ID of the guild owner (if applicable). See also Guild.application_id.

Type: int

afk_channel¶

The guild’s AFK channel.

If this could not be found, then it falls back to a Object with the ID being set.

See Guild.afk_channel.

Type: Union[VoiceChannel, Object]

system_channel¶

The guild’s system channel.

If this could not be found, then it falls back to a Object with the ID being set.

See Guild.system_channel.

Type: Union[TextChannel, Object]

rules_channel¶

The guild’s rules channel.

If this could not be found then it falls back to a Object with the ID being set.

See Guild.rules_channel.

Type: Union[TextChannel, Object]

public_updates_channel¶

The guild’s public updates channel.

If this could not be found then it falls back to a Object with the ID being set.

See Guild.public_updates_channel.

Type: Union[TextChannel, Object]

afk_timeout¶

The guild’s AFK timeout. See Guild.afk_timeout.

Type: int

mfa_level¶

The guild’s MFA level. See Guild.mfa_level.

Type: MFALevel

widget_enabled¶

The guild’s widget has been enabled or disabled.

Type: bool

widget_channel¶

The widget’s channel.

If this could not be found then it falls back to a Object with the ID being set.

Type: Union[TextChannel, Object]

verification_level¶

The guild’s verification level.

Webhook Support¶

discord.py-self offers support for creating, editing, and executing webhooks through the Webhook class.

Webhook¶

Attributes

avatar
channel
channel_id
created_at
default_avatar
display_avatar
guild
guild_id
id
name
source_channel
source_guild
token
type
url
user

Methods

clsWebhook.from_url
clsWebhook.partial
asyncdelete
asyncdelete_message
asyncedit
asyncedit_message
asyncfetch
asyncfetch_message
defis_authenticated
defis_partial
asyncsend

class discord.Webhook¶

Represents an asynchronous Discord webhook.

Webhooks are a form to send messages to channels in Discord without a bot user or authentication.

There are two main ways to use Webhooks. The first is through the ones received by the library such as Guild.webhooks(), TextChannel.webhooks(), VoiceChannel.webhooks() and ForumChannel.webhooks(). The ones received by the library will automatically be bound using the library’s internal HTTP session.

The second form involves creating a webhook object manually using the from_url() or partial() classmethods.

For example, creating a webhook from a URL and using aiohttp:

from discord import Webhook
import aiohttp

async def foo():
    async with aiohttp.ClientSession() as session:
        webhook = Webhook.from_url('url-here', session=session)
        await webhook.send('Hello World', username='Foo')

For a synchronous counterpart, see SyncWebhook.

x == y: Checks if two webhooks are equal.

x != y: Checks if two webhooks are not equal.

hash(x): Returns the webhooks’s hash.

Changed in version 1.4: Webhooks are now comparable and hashable.

id¶

The webhook’s ID

Type: int

type¶

The type of the webhook.

New in version 1.3.

Type: WebhookType

token¶

The authentication token of the webhook. If this is None then the webhook cannot be used to make requests.

Type: Optional[str]

guild_id¶

The guild ID this webhook is for.

Type: Optional[int]

channel_id¶

The channel ID this webhook is for.

Type: Optional[int]

user¶

The user this webhook was created by. If the webhook was received without authentication then this will be None.

Type: Optional[abc.User]

name¶

The default name of the webhook.

Type: Optional[str]

source_guild¶

The guild of the channel that this webhook is following. Only given if type is WebhookType.channel_follower.

New in version 2.0.

Type: Optional[PartialWebhookGuild]

source_channel¶

The channel that this webhook is following. Only given if type is WebhookType.channel_follower.

New in version 2.0.

Type: Optional[PartialWebhookChannel]

property url¶

Returns the webhook’s url.

Type: str

classmethod partial(id, token, *, session=..., client=..., user_token=None)¶

Creates a partial Webhook.

Parameters

id (int) – The ID of the webhook.
token (str) – The authentication token of the webhook.
session (aiohttp.ClientSession) –
The session to use to send requests with. Note that the library does not manage the session and will not close it.

New in version 2.0.
client (Client) –
The client to initialise this webhook with. This allows it to attach the client’s internal state. If session is not given while this is given then the client’s internal session will be used.

New in version 2.0.
user_token (Optional[str]) –
The user authentication token for authenticated requests involving the webhook.

New in version 2.0.

Raises

TypeError – Neither session nor client were given.

Returns

A partial Webhook. A partial webhook is just a webhook object with an ID and a token.

Return type

classmethod from_url(url, *, session=..., client=..., user_token=None)¶

Creates a partial Webhook from a webhook URL.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

url (str) – The URL of the webhook.
session (aiohttp.ClientSession) –
The session to use to send requests with. Note that the library does not manage the session and will not close it.

New in version 2.0.
client (Client) –
The client to initialise this webhook with. This allows it to attach the client’s internal state. If session is not given while this is given then the client’s internal session will be used.

New in version 2.0.
user_token (Optional[str]) –
The bot authentication token for authenticated requests involving the webhook.

New in version 2.0.

Raises

ValueError – The URL is invalid.
TypeError – Neither session nor client were given.

Returns

A partial Webhook. A partial webhook is just a webhook object with an ID and a token.

Return type

await fetch(*, prefer_auth=True)¶

This function is a coroutine.

Fetches the current webhook.

This could be used to get a full webhook from a partial webhook.

New in version 2.0.

Note

When fetching with an unauthenticated webhook, i.e. is_authenticated() returns False, then the returned webhook does not contain any user information.

Parameters

prefer_auth (bool) – Whether to use the bot token over the webhook token if available. Defaults to True.

Raises

HTTPException – Could not fetch the webhook
NotFound – Could not find the webhook by this ID
ValueError – This webhook does not have a token associated with it.

Returns

The fetched webhook.

Return type

await delete(*, reason=None, prefer_auth=True)¶

This function is a coroutine.

Deletes this Webhook.

Parameters

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

New in version 1.4.
prefer_auth (bool) –
Whether to use the bot token over the webhook token if available. Defaults to True.

New in version 2.0.

Raises

HTTPException – Deleting the webhook failed.
NotFound – This webhook does not exist.
Forbidden – You do not have permissions to delete this webhook.
ValueError – This webhook does not have a token associated with it.

await edit(*, reason=None, name=..., avatar=..., channel=None, prefer_auth=True)¶

This function is a coroutine.

Edits this Webhook.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

name (Optional[str]) – The webhook’s new default name.
avatar (Optional[bytes]) – A bytes-like object representing the webhook’s new default avatar.
channel (Optional[abc.Snowflake]) –
The webhook’s new channel. This requires an authenticated webhook.

New in version 2.0.
reason (Optional[str]) –
The reason for editing this webhook. Shows up on the audit log.

New in version 1.4.
prefer_auth (bool) –
Whether to use the bot token over the webhook token if available. Defaults to True.

New in version 2.0.

Raises

HTTPException – Editing the webhook failed.
NotFound – This webhook does not exist.
ValueError – This webhook does not have a token associated with it or it tried editing a channel without authentication.

property avatar¶

Returns an Asset for the avatar the webhook has.

If the webhook does not have a traditional avatar, None is returned. If you want the avatar that a webhook has displayed, consider display_avatar.

Type: Optional[Asset]

property channel¶

The channel this webhook belongs to.

If this is a partial webhook, then this will always return None.

Type: Optional[Union[ForumChannel, VoiceChannel, StageChannel, TextChannel]]

property created_at¶

Returns the webhook’s creation time in UTC.

Type: datetime.datetime

property default_avatar¶

Returns the default avatar. This is always the blurple avatar.

New in version 2.0.

Type: Asset

property display_avatar¶

Returns the webhook’s display avatar.

This is either webhook’s default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

property guild¶

The guild this webhook belongs to.

If this is a partial webhook, then this will always return None.

Type: Optional[Guild]

is_authenticated()¶: bool: Whether the webhook is authenticated with a bot token.

New in version 2.0.

is_partial()¶: bool: Whether the webhook is a “partial” webhook.

New in version 2.0.

await send(content=..., *, username=..., avatar_url=..., tts=False, file=..., files=..., embed=..., embeds=..., allowed_mentions=..., thread=..., thread_name=..., wait=False, suppress_embeds=False, silent=False)¶

This function is a coroutine.

Sends a message using the webhook.

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

To upload a single file, the file parameter should be used with a single File object.

If the embed parameter is provided, it must be of type Embed and it must be a rich embed type. You cannot mix the embed parameter with the embeds parameter, which must be a list of Embed objects to send.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

content (str) – The content of the message to send.
wait (bool) – Whether the server should wait before sending a response. This essentially means that the return type of this function changes from None to a WebhookMessage if set to True. If the type of webhook is WebhookType.application then this is always set to True.
username (str) – The username to send with this message. If no username is provided then the default username for the webhook is used.
avatar_url (str) – The avatar URL to send with this message. If no avatar URL is provided then the default avatar for the webhook is used. If this is not a string then it is explicitly cast using str.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (File) – The file to upload. This cannot be mixed with files parameter.
files (List[File]) – A list of files to send with the content. This cannot be mixed with the file parameter.
embed (Embed) – The rich embed for the content to send. This cannot be mixed with embeds parameter.
embeds (List[Embed]) – A list of embeds to send with the content. Maximum of 10. This cannot be mixed with the embed parameter.
allowed_mentions (AllowedMentions) –
Controls the mentions being processed in this message.

New in version 1.4.
thread (Snowflake) –
The thread to send this webhook to.

New in version 2.0.
thread_name (str) –
The thread name to create with this webhook if the webhook belongs to a ForumChannel. Note that this is mutually exclusive with the thread parameter, as this will create a new thread with the given name.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
NotFound – This webhook was not found.
Forbidden – The authorization token for the webhook is incorrect.
TypeError – You specified both embed and embeds or file and files or thread and thread_name.
ValueError – The length of embeds was invalid, or there was no token associated with this webhook.

Returns

If wait is True then the message that was sent, otherwise None.

Return type

Optional[WebhookMessage]

await fetch_message(id, /, *, thread=...)¶

This function is a coroutine.

Retrieves a single WebhookMessage owned by this webhook.

New in version 2.0.

Parameters

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

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.
ValueError – There was no token associated with this webhook.

Returns

The message asked for.

Return type

await edit_message(message_id, *, content=..., embeds=..., embed=..., attachments=..., allowed_mentions=None, thread=...)¶

This function is a coroutine.

Edits a message owned by this webhook.

This is a lower level interface to WebhookMessage.edit() in case you only have an ID.

New in version 1.6.

Changed in version 2.0: The edit is no longer in-place, instead the newly edited message is returned.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

message_id (int) – The message ID to edit.
content (Optional[str]) – The content to edit the message with or None to clear it.
embeds (List[Embed]) – A list of embeds to edit the message with.
embed (Optional[Embed]) – The embed to edit the message with. None suppresses the embeds. This should not be mixed with the embeds parameter.
attachments (List[Union[Attachment, File]]) –
A list of attachments to keep in the message as well as new files to upload. If [] is passed then all attachments are removed.

New in version 2.0.
allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.
thread (Snowflake) –
The thread the webhook message belongs to.

New in version 2.0.

Raises

HTTPException – Editing the message failed.
Forbidden – Edited a message that is not yours.
TypeError – You specified both embed and embeds
ValueError – The length of embeds was invalid, there was no token associated with this webhook or the webhook had no state.

Returns

The newly edited webhook message.

Return type

await delete_message(message_id, /, *, thread=...)¶

This function is a coroutine.

Deletes a message owned by this webhook.

This is a lower level interface to WebhookMessage.delete() in case you only have an ID.

New in version 1.6.

Changed in version 2.0: message_id parameter is now positional-only.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

message_id (int) – The message ID to delete.
thread (Snowflake) –
The thread the webhook message belongs to.

New in version 2.0.

Raises

HTTPException – Deleting the message failed.
Forbidden – Deleted a message that is not yours.
ValueError – This webhook does not have a token associated with it.

WebhookMessage¶

Attributes

clean_content
created_at
edited_at
jump_url
raw_channel_mentions
raw_mentions
raw_role_mentions
system_content

Methods

asyncack
asyncadd_files
asyncadd_reaction
asyncclear_reaction
asyncclear_reactions
asynccreate_thread
asyncdelete
asyncedit
asyncfetch
asyncgreet
defis_acked
defis_system
defmessage_commands
asyncpin
asyncpublish
asyncremove_attachments
asyncremove_reaction
asyncreply
defto_reference
asyncunack
asyncunpin

class discord.WebhookMessage¶

Represents a message sent from your webhook.

This allows you to edit or delete a message sent by your webhook.

This inherits from discord.Message with changes to edit() and delete() to work.

New in version 1.6.

await edit(content=..., embeds=..., embed=..., attachments=..., allowed_mentions=None)¶

This function is a coroutine.

Edits the message.

New in version 1.6.

Changed in version 2.0: The edit is no longer in-place, instead the newly edited message is returned.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content to edit the message with or None to clear it.
embeds (List[Embed]) – A list of embeds to edit the message with.
embed (Optional[Embed]) – The embed to edit the message with. None suppresses the embeds. This should not be mixed with the embeds parameter.
attachments (List[Union[Attachment, File]]) –
A list of attachments to keep in the message as well as new files to upload. If [] is passed then all attachments are removed.

Note

New files will always appear after current attachments.

New in version 2.0.
allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.

Raises

HTTPException – Editing the message failed.
Forbidden – Edited a message that is not yours.
TypeError – You specified both embed and embeds
ValueError – The length of embeds was invalid or there was no token associated with this webhook.

Returns

The newly edited message.

Return type

await add_files(*files)¶

This function is a coroutine.

Adds new files to the end of the message attachments.

New in version 2.0.

Parameters

*files (File) – New files to add to the message.

Raises

HTTPException – Editing the message failed.
Forbidden – Tried to edit a message that isn’t yours.

Returns

The newly edited message.

Return type

await remove_attachments(*attachments)¶

This function is a coroutine.

Removes attachments from the message.

New in version 2.0.

Parameters

*attachments (Attachment) – Attachments to remove from the message.

Raises

HTTPException – Editing the message failed.
Forbidden – Tried to edit a message that isn’t yours.

Returns

The newly edited message.

Return type

await delete(*, delay=None)¶

This function is a coroutine.

Deletes the message.

Parameters

delay (Optional[float]) – If provided, the number of seconds to wait before deleting the message. The waiting is done in the background and deletion failures are ignored.

Raises

Forbidden – You do not have proper permissions to delete the message.
NotFound – The message was deleted already.
HTTPException – Deleting the message failed.

await ack(*, manual=False, mention_count=None)¶

This function is a coroutine.

Marks this message as read.

Note

This sets the last acknowledged message to this message, which will mark acknowledged messages created after this one as unread.

Parameters

manual (bool) –
Whether to manually set the channel read state to this message.

New in version 2.1.
mention_count (Optional[int]) –
The mention count to set the channel read state to. Only applicable for manual acknowledgements.

New in version 2.1.

Raises

HTTPException – Acking failed.

await add_reaction(emoji, /)¶

This function is a coroutine.

Adds a reaction to the message.

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

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

Changed in version 2.0: emoji parameter is now positional-only.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

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.
TypeError – The emoji parameter is invalid.

clean_content¶

A property that returns the content in a “cleaned up” manner. This basically means that mentions are transformed into the way the client shows it. e.g. <#id> will transform into #name.

This will also transform @everyone and @here mentions into non-mentions.

Note

This does not affect markdown. If you want to escape or remove markdown then use utils.escape_markdown() or utils.remove_markdown() respectively, along with this function.

Type: str

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 must have manage_messages to do this.

New in version 1.3.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

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.
TypeError – The emoji parameter is invalid.

await clear_reactions()¶

This function is a coroutine.

Removes all the reactions from the message.

You must have manage_messages to do this.

Raises

HTTPException – Removing the reactions failed.
Forbidden – You do not have the proper permissions to remove all the reactions.

await create_thread(*, name, auto_archive_duration=..., slowmode_delay=None, reason=None)¶

This function is a coroutine.

Creates a public thread from this message.

You must have create_public_threads in order to create a public thread from a message.

The channel this message belongs in must be a TextChannel.

New in version 2.0.

Parameters

name (str) – The name of the thread.
auto_archive_duration (int) –
The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

Must be one of 60, 1440, 4320, or 10080, if provided.
slowmode_delay (Optional[int]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is 21600. By default no slowmode rate limit if this is None.
reason (Optional[str]) – The reason for creating a new thread. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to create a thread.
HTTPException – Creating the thread failed.
ValueError – This message does not have guild info attached.

Returns

The created thread.

Return type

property created_at¶

The message’s creation time in UTC.

Type: datetime.datetime

property edited_at¶

An aware UTC datetime object containing the edited time of the message.

Type: Optional[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

await greet(sticker, **kwargs)¶

This function is a coroutine.

A shortcut method to abc.Messageable.greet() to reply to the Message with a sticker greeting.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.

Returns

The sticker greeting that was sent.

Return type

is_acked()¶: bool: Whether the message has been marked as read.

New in version 2.1.

is_system()¶

bool: Whether the message is a system message.

A system message is a message that is constructed entirely by the Discord API in response to something.

New in version 1.3.

property jump_url¶

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

Type: str

message_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the message commands available to use on the message.

Deprecated since version 2.1.

Examples

Usage

async for command in message.message_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in message.message_commands()]
# commands is now a list of MessageCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

MessageCommand – A message command.

await pin(*, reason=None)¶

This function is a coroutine.

Pins the message.

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

Parameters

reason (Optional[str]) –

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

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

await publish()¶

This function is a coroutine.

Publishes this message to the channel’s followers.

The message must have been sent in a news channel. You must have send_messages to do this.

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

Raises

Forbidden – You do not have the proper permissions to publish this message or the channel is not a news channel.
HTTPException – Publishing the message failed.

raw_channel_mentions¶

A property that returns an array of channel IDs matched with the syntax of <#channel_id> in the message content.

Type: List[int]

raw_mentions¶

A property that returns an array of user IDs matched with the syntax of <@user_id> in the message content.

This allows you to receive the user IDs of mentioned users even in a private message context.

Type: List[int]

raw_role_mentions¶

A property that returns an array of role IDs matched with the syntax of <@&role_id> in the message content.

Type: List[int]

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 manage_messages is needed.

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

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

emoji (Union[Emoji, Reaction, PartialEmoji, str]) – The emoji to remove.
member (abc.Snowflake) – The member for which to remove the reaction.

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.
TypeError – The emoji parameter is invalid.

await reply(content=None, **kwargs)¶

This function is a coroutine.

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

New in version 1.6.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size
TypeError – You specified both file and files.

Returns

The message that was sent.

Return type

system_content¶

A property that returns the content that is rendered regardless of the Message.type.

In the case of MessageType.default and MessageType.reply, this just returns the regular Message.content. Otherwise this returns an English message denoting the contents of the system message.

Type: str

to_reference(*, fail_if_not_exists=True)¶

Creates a MessageReference from the current message.

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

New in version 1.7.

Returns

The reference to this message.

Return type

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks this message as unread. This manually sets the read state to the current message’s ID - 1.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking failed.

await unpin(*, reason=None)¶

This function is a coroutine.

Unpins the message.

You must have manage_messages 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.

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

SyncWebhook¶

Attributes

avatar
channel
channel_id
created_at
default_avatar
display_avatar
guild
guild_id
id
name
source_channel
source_guild
token
type
url
user

Methods

clsSyncWebhook.from_url
clsSyncWebhook.partial
defdelete
defdelete_message
defedit
defedit_message
deffetch
deffetch_message
defis_authenticated
defis_partial
defsend

class discord.SyncWebhook¶

Represents a synchronous Discord webhook.

For an asynchronous counterpart, see Webhook.

x == y: Checks if two webhooks are equal.

x != y: Checks if two webhooks are not equal.

hash(x): Returns the webhooks’s hash.

Changed in version 1.4: Webhooks are now comparable and hashable.

id¶

The webhook’s ID

Type: int

type¶

The type of the webhook.

New in version 1.3.

Type: WebhookType

token¶

The authentication token of the webhook. If this is None then the webhook cannot be used to make requests.

Type: Optional[str]

guild_id¶

The guild ID this webhook is for.

Type: Optional[int]

channel_id¶

The channel ID this webhook is for.

Type: Optional[int]

user¶

The user this webhook was created by. If the webhook was received without authentication then this will be None.

Type: Optional[abc.User]

name¶

The default name of the webhook.

Type: Optional[str]

source_guild¶

The guild of the channel that this webhook is following. Only given if type is WebhookType.channel_follower.

New in version 2.0.

Type: Optional[PartialWebhookGuild]

source_channel¶

The channel that this webhook is following. Only given if type is WebhookType.channel_follower.

New in version 2.0.

Type: Optional[PartialWebhookChannel]

property url¶

Returns the webhook’s url.

Type: str

classmethod partial(id, token, *, session=..., user_token=None)¶

Creates a partial Webhook.

Parameters

id (int) – The ID of the webhook.
token (str) – The authentication token of the webhook.
session (requests.Session) – The session to use to send requests with. Note that the library does not manage the session and will not close it. If not given, the requests auto session creation functions are used instead.
user_token (Optional[str]) – The bot authentication token for authenticated requests involving the webhook.

Returns

A partial SyncWebhook. A partial SyncWebhook is just a SyncWebhook object with an ID and a token.

Return type

classmethod from_url(url, *, session=..., user_token=None)¶

Creates a partial Webhook from a webhook URL.

Parameters

url (str) – The URL of the webhook.
session (requests.Session) – The session to use to send requests with. Note that the library does not manage the session and will not close it. If not given, the requests auto session creation functions are used instead.
user_token (Optional[str]) – The bot authentication token for authenticated requests involving the webhook.

Raises

ValueError – The URL is invalid.

Returns

A partial SyncWebhook. A partial SyncWebhook is just a SyncWebhook object with an ID and a token.

Return type

fetch(*, prefer_auth=True)¶

Fetches the current webhook.

This could be used to get a full webhook from a partial webhook.

Note

When fetching with an unauthenticated webhook, i.e. is_authenticated() returns False, then the returned webhook does not contain any user information.

Parameters

prefer_auth (bool) – Whether to use the bot token over the webhook token if available. Defaults to True.

Raises

HTTPException – Could not fetch the webhook
NotFound – Could not find the webhook by this ID
ValueError – This webhook does not have a token associated with it.

Returns

The fetched webhook.

Return type

delete(*, reason=None, prefer_auth=True)¶

Deletes this Webhook.

Parameters

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

New in version 1.4.
prefer_auth (bool) – Whether to use the bot token over the webhook token if available. Defaults to True.

Raises

HTTPException – Deleting the webhook failed.
NotFound – This webhook does not exist.
Forbidden – You do not have permissions to delete this webhook.
ValueError – This webhook does not have a token associated with it.

edit(*, reason=None, name=..., avatar=..., channel=None, prefer_auth=True)¶

Edits this Webhook.

Parameters

name (Optional[str]) – The webhook’s new default name.
avatar (Optional[bytes]) – A bytes-like object representing the webhook’s new default avatar.
channel (Optional[abc.Snowflake]) – The webhook’s new channel. This requires an authenticated webhook.
reason (Optional[str]) –
The reason for editing this webhook. Shows up on the audit log.

New in version 1.4.
prefer_auth (bool) – Whether to use the bot token over the webhook token if available. Defaults to True.

Raises

HTTPException – Editing the webhook failed.
NotFound – This webhook does not exist.
ValueError – This webhook does not have a token associated with it or it tried editing a channel without authentication.

Returns

The newly edited webhook.

Return type

send(content=..., *, username=..., avatar_url=..., tts=False, file=..., files=..., embed=..., embeds=..., allowed_mentions=..., thread=..., thread_name=..., wait=False, suppress_embeds=False, silent=False)¶

Sends a message using the webhook.

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

To upload a single file, the file parameter should be used with a single File object.

Parameters

content (str) – The content of the message to send.
wait (bool) – Whether the server should wait before sending a response. This essentially means that the return type of this function changes from None to a WebhookMessage if set to True.
username (str) – The username to send with this message. If no username is provided then the default username for the webhook is used.
avatar_url (str) – The avatar URL to send with this message. If no avatar URL is provided then the default avatar for the webhook is used. If this is not a string then it is explicitly cast using str.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (File) – The file to upload. This cannot be mixed with files parameter.
files (List[File]) – A list of files to send with the content. This cannot be mixed with the file parameter.
embed (Embed) – The rich embed for the content to send. This cannot be mixed with embeds parameter.
embeds (List[Embed]) – A list of embeds to send with the content. Maximum of 10. This cannot be mixed with the embed parameter.
allowed_mentions (AllowedMentions) –
Controls the mentions being processed in this message.

New in version 1.4.
thread (Snowflake) –
The thread to send this message to.

New in version 2.0.
thread_name (str) –
The thread name to create with this webhook if the webhook belongs to a ForumChannel. Note that this is mutually exclusive with the thread parameter, as this will create a new thread with the given name.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
NotFound – This webhook was not found.
Forbidden – The authorization token for the webhook is incorrect.
TypeError – You specified both embed and embeds or file and files or thread and thread_name.
ValueError – The length of embeds was invalid or there was no token associated with this webhook.

Returns

If wait is True then the message that was sent, otherwise None.

Return type

Optional[SyncWebhookMessage]

fetch_message(id, /, *, thread=...)¶

Retrieves a single SyncWebhookMessage owned by this webhook.

New in version 2.0.

Parameters

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

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.
ValueError – There was no token associated with this webhook.

Returns

The message asked for.

Return type

property avatar¶

Returns an Asset for the avatar the webhook has.

If the webhook does not have a traditional avatar, None is returned. If you want the avatar that a webhook has displayed, consider display_avatar.

Type: Optional[Asset]

property channel¶

The channel this webhook belongs to.

If this is a partial webhook, then this will always return None.

Type: Optional[Union[ForumChannel, VoiceChannel, StageChannel, TextChannel]]

property created_at¶

Returns the webhook’s creation time in UTC.

Type: datetime.datetime

property default_avatar¶

Returns the default avatar. This is always the blurple avatar.

New in version 2.0.

Type: Asset

property display_avatar¶

Returns the webhook’s display avatar.

This is either webhook’s default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

edit_message(message_id, *, content=..., embeds=..., embed=..., attachments=..., allowed_mentions=None, thread=...)¶

Edits a message owned by this webhook.

This is a lower level interface to WebhookMessage.edit() in case you only have an ID.

New in version 1.6.

Parameters

message_id (int) – The message ID to edit.
content (Optional[str]) – The content to edit the message with or None to clear it.
embeds (List[Embed]) – A list of embeds to edit the message with.
embed (Optional[Embed]) – The embed to edit the message with. None suppresses the embeds. This should not be mixed with the embeds parameter.
attachments (List[Union[Attachment, File]]) –
A list of attachments to keep in the message as well as new files to upload. If [] is passed then all attachments are removed.

New in version 2.0.
allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.
thread (Snowflake) –
The thread the webhook message belongs to.

New in version 2.0.

Raises

HTTPException – Editing the message failed.
Forbidden – Edited a message that is not yours.
TypeError – You specified both embed and embeds
ValueError – The length of embeds was invalid or there was no token associated with this webhook.

property guild¶

The guild this webhook belongs to.

If this is a partial webhook, then this will always return None.

Type: Optional[Guild]

is_authenticated()¶: bool: Whether the webhook is authenticated with a bot token.

New in version 2.0.

is_partial()¶: bool: Whether the webhook is a “partial” webhook.

New in version 2.0.

delete_message(message_id, /, *, thread=...)¶

Deletes a message owned by this webhook.

This is a lower level interface to WebhookMessage.delete() in case you only have an ID.

New in version 1.6.

Parameters

message_id (int) – The message ID to delete.
thread (Snowflake) –
The thread the webhook message belongs to.

New in version 2.0.

Raises

HTTPException – Deleting the message failed.
Forbidden – Deleted a message that is not yours.
ValueError – This webhook does not have a token associated with it.

SyncWebhookMessage¶

Methods

defadd_files
defdelete
defedit
defremove_attachments

class discord.SyncWebhookMessage¶

Represents a message sent from your webhook.

This allows you to edit or delete a message sent by your webhook.

This inherits from discord.Message with changes to edit() and delete() to work.

New in version 2.0.

edit(content=..., embeds=..., embed=..., attachments=..., allowed_mentions=None)¶

Edits the message.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content to edit the message with or None to clear it.
embeds (List[Embed]) – A list of embeds to edit the message with.
embed (Optional[Embed]) – The embed to edit the message with. None suppresses the embeds. This should not be mixed with the embeds parameter.
attachments (List[Union[Attachment, File]]) –
A list of attachments to keep in the message as well as new files to upload. If [] is passed then all attachments are removed.

Note

New files will always appear after current attachments.

New in version 2.0.
allowed_mentions (AllowedMentions) – Controls the mentions being processed in this message. See abc.Messageable.send() for more information.

Raises

HTTPException – Editing the message failed.
Forbidden – Edited a message that is not yours.
TypeError – You specified both embed and embeds
ValueError – The length of embeds was invalid or there was no token associated with this webhook.

Returns

The newly edited message.

Return type

add_files(*files)¶

Adds new files to the end of the message attachments.

New in version 2.0.

Parameters

*files (File) – New files to add to the message.

Raises

HTTPException – Editing the message failed.
Forbidden – Tried to edit a message that isn’t yours.

Returns

The newly edited message.

Return type

remove_attachments(*attachments)¶

Removes attachments from the message.

New in version 2.0.

Parameters

*attachments (Attachment) – Attachments to remove from the message.

Raises

HTTPException – Editing the message failed.
Forbidden – Tried to edit a message that isn’t yours.

Returns

The newly edited message.

Return type

delete(*, delay=None)¶

Deletes the message.

Parameters

delay (Optional[float]) – If provided, the number of seconds to wait before deleting the message. This blocks the thread.

Raises

Forbidden – You do not have proper permissions to delete the message.
NotFound – The message was deleted already.
HTTPException – Deleting the message failed.

PartialWebhookGuild¶

Attributes

icon
id
name

class discord.PartialWebhookGuild¶

Represents a partial guild for webhooks.

These are typically given for channel follower webhooks.

New in version 2.0.

id¶

The partial guild’s ID.

Type: int

name¶

The partial guild’s name.

Type: str

property icon¶

Returns the guild’s icon asset, if available.

Type: Optional[Asset]

PartialWebhookChannel¶

Attributes

id
name

class discord.PartialWebhookChannel¶

Represents a partial channel for webhooks.

These are typically given for channel follower webhooks.

New in version 2.0.

id¶

The partial channel’s ID.

Type: int

name¶

The partial channel’s name.

Type: str

Abstract Base Classes¶

An abstract base class (also known as an abc) is a class that models can inherit to get their behaviour. Abstract base classes should not be instantiated. They are mainly there for usage with isinstance() and issubclass().

This library has a module related to abstract base classes, in which all the ABCs are subclasses of typing.Protocol.

Snowflake¶

Attributes

class discord.abc.Snowflake¶

An ABC that details the common operations on a Discord model.

Almost all Discord models meet this abstract base class.

If you want to create a snowflake on your own, consider using Object.

id¶

The model’s unique ID.

Type: int

User¶

Attributes

avatar
avatar_decoration
avatar_decoration_sku_id
bot
default_avatar
discriminator
display_avatar
display_name
global_name
mention
name
system

Methods

defmentioned_in

class discord.abc.User¶

An ABC that details the common operations on a Discord user.

The following implement this ABC:

User
ClientUser
Member

This ABC must also implement Snowflake.

name¶

The user’s username.

Type: str

discriminator¶

The user’s discriminator. This is a legacy concept that is no longer used.

Type: str

global_name¶

The user’s global nickname.

Type: Optional[str]

bot¶

If the user is a bot account.

Type: bool

system¶

If the user is a system account.

Type: bool

property display_name¶

Returns the user’s display name.

Type: str

property mention¶

Returns a string that allows you to mention the given user.

Type: str

property avatar¶

Returns an Asset that represents the user’s avatar, if present.

Type: Optional[Asset]

property avatar_decoration¶

Returns an Asset that represents the user’s avatar decoration, if present.

New in version 2.0.

Type: Optional[Asset]

property avatar_decoration_sku_id¶

Returns the SKU ID of the user’s avatar decoration, if present.

New in version 2.1.

Type: Optional[int]

property default_avatar¶

Returns the default avatar for a given user.

Type: Asset

property display_avatar¶

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

mentioned_in(message)¶

Checks if the user is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the user is mentioned in the message.
Return type: bool

PrivateChannel¶

Attributes

class discord.abc.PrivateChannel¶

An ABC that details the common operations on a private Discord channel.

The following implement this ABC:

DMChannel
GroupChannel

This ABC must also implement Snowflake.

me¶

The user presenting yourself.

Type: ClientUser

GuildChannel¶

Attributes

category
changed_roles
created_at
guild
jump_url
mention
name
notification_settings
overwrites
permissions_synced
position

Methods

asyncclone
asynccreate_invite
asyncdelete
asyncinvites
asyncmove
defoverwrites_for
defpermissions_for
asyncset_permissions

class discord.abc.GuildChannel¶

An ABC that details the common operations on a Discord guild channel.

The following implement this ABC:

TextChannel
VoiceChannel
CategoryChannel
StageChannel
ForumChannel

This ABC must also implement Snowflake.

name¶

The channel name.

Type: str

guild¶

The guild the channel belongs to.

Type: Guild

position¶

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type: int

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property changed_roles¶

Returns a list of roles that have been overridden from their default values in the roles attribute.

Type: List[Role]

property mention¶

The string that allows you to mention the channel.

Type: str

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

overwrites_for(obj)¶

Returns the channel-specific overwrites for a member or a role.

Parameters: obj (Union[Role, User, Object]) – The role or user denoting whose overwrite to get.
Returns: The permission overwrites for this object.
Return type: PermissionOverwrite

property overwrites¶

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Changed in version 2.0: Overwrites can now be type-aware Object in case of cache lookup failure

Returns: The channel’s permission overwrites.
Return type: Dict[Union[Role, Member, Object], PermissionOverwrite]

property category¶

The category this channel belongs to.

If there is no category then this is None.

Type: Optional[CategoryChannel]

property permissions_synced¶

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type: bool

permissions_for(obj, /)¶

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

Guild owner
Guild roles
Channel overrides
Member overrides
Implicit permissions
Member timeout

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

The default role permissions
The permissions of the role used as a parameter
The default role permission overwrites
The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Changed in version 2.0: obj parameter is now positional-only.

Parameters: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Returns: The resolved permissions for the member or role.
Return type: Permissions

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the channel.

You must have manage_channels to do this.

Parameters

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

Raises

Forbidden – You do not have proper permissions to delete the channel.
NotFound – The channel was not found or was already deleted.
HTTPException – Deleting the channel failed.

await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)¶

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

The overwrite parameter, if given, must either be None or PermissionOverwrite. For convenience, you can pass in keyword arguments denoting Permissions attributes. If this is done, then you cannot mix the keyword arguments with the overwrite parameter.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have manage_roles to do this.

Note

This method replaces the old overwrites with the ones given.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, read_messages=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False
overwrite.read_messages = True
await channel.set_permissions(member, overwrite=overwrite)

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

target (Union[Member, Role]) – The member or role to overwrite permissions for.
overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.
**permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit channel specific permissions.
HTTPException – Editing channel specific permissions failed.
NotFound – The role or member being edited is not part of the guild.
TypeError – The overwrite parameter was invalid or the target type was not Role or Member.
ValueError – The overwrite parameter and positions parameters were both unset.

await clone(*, name=None, reason=None)¶

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have manage_channels to do this.

New in version 1.1.

Parameters

name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.
reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.

Returns

The channel that was created.

Return type

await move(**kwargs)¶

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have manage_channels to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.
end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.
before (Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.
offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.
category (Optional[Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.
sync_permissions (bool) – Whether to sync the permissions with the category (if given).
reason (str) – The reason for the move.

Raises

ValueError – An invalid position was given.
TypeError – A bad mix of arguments were passed.
Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, guest=False, target_type=None, target_user=None, target_application=None)¶

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have create_instant_invite to do this.

Changed in version 2.1: The validate parameter has been removed.

Parameters

max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.
max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.
temporary (bool) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
guest (bool) –
Denotes that the invite is a guest invite. Guest invites grant temporary membership for the purposes of joining a voice channel. Defaults to False.

New in version 2.1.
unique (bool) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.
target_type (Optional[InviteTarget]) –
The type of target for the voice channel invite, if any.

New in version 2.0.
target_user (Optional[User]) –
The user whose stream to display for this invite, required if target_type is InviteTarget.stream. The user must be streaming in the channel.

New in version 2.0.
target_application: –
Optional[Application]: The embedded application for the invite, required if target_type is InviteTarget.embedded_application.

New in version 2.0.
reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises

HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.
ValueError – target_type is not a creatable invite target type.

Returns

The invite that was created.

Return type

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have manage_channels to get this information.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

Messageable¶

Methods

asyncack
asyncack_pins
asyncapplication_commands
asyncfetch_message
asyncgreet
async forhistory
asyncpins
defsearch
asyncsend
defslash_commands
deftyping
asyncunack
asyncupload_files
defuser_commands

class discord.abc.Messageable¶

An ABC that details the common operations on a model that can send messages.

The following implement this ABC:

TextChannel
VoiceChannel
StageChannel
DMChannel
GroupChannel
User
Member
Context
Thread

async with typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

async for ... in slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

async for ... in user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

await send(content=None, *, tts=False, file=None, files=None, stickers=None, delete_after=None, nonce=..., allowed_mentions=None, reference=None, mention_author=None, suppress_embeds=False, silent=False)¶

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). If the content is set to None (the default), then a sticker or file must be sent.

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.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

await fetch_message(id, /)¶

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

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

search(content=..., *, limit=25, offset=0, before=..., after=..., authors=..., author_types=..., mentions=..., mention_everyone=..., pinned=..., has=..., embed_types=..., embed_providers=..., link_hostnames=..., attachment_filenames=..., attachment_extensions=..., application_commands=..., oldest_first=False, most_relevant=False)¶

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

Connectable¶

Methods

asyncconnect

class discord.abc.Connectable¶

An ABC that details the common operations on a channel that can connect to a voice server.

The following implement this ABC:

VoiceChannel
StageChannel
DMChannel
GroupChannel
User
Member

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

ApplicationCommand¶

Attributes

application
application_id
default_member_permissions
description
dm_permission
guild
guild_id
name
nsfw
target_channel
type

Methods

defis_group

class discord.abc.ApplicationCommand¶

An ABC that represents a usable application command.

The following implement this ABC:

UserCommand
MessageCommand
SlashCommand
SubCommand

New in version 2.0.

Changed in version 2.1: Removed default_permission attribute.

name¶

The command’s name.

Type: str

description¶

The command’s description, if any.

Type: str

type¶

The type of application command.

Type: ApplicationCommandType

dm_permission¶

Whether the command is enabled in DMs.

Type: bool

nsfw¶

Whether the command is marked NSFW and only available in NSFW channels.

Type: bool

application¶

The application this command belongs to. Only available if requested.

Type: Optional[IntegrationApplication]

application_id¶

The ID of the application this command belongs to.

Type: int

guild_id¶

The ID of the guild this command is registered in. A value of None denotes that it is a global command.

Type: Optional[int]

property guild¶

Returns the guild this command is registered to if it exists.

Type: Optional[Guild]

is_group()¶: bool: Whether this command is a group.

property target_channel¶

The channel this application command will be used on.

You can set this in order to use this command in a different channel without re-fetching it.

Type: Optional[abc.Messageable]

property default_member_permissions¶

The default permissions required to use this command.

Note

This may be overrided on a guild-by-guild basis.

Type: Optional[Permissions]

Discord Models¶

Models are classes that are received from Discord and are not meant to be created by the user of the library.

Danger

The classes listed below are not intended to be created by users and are also read-only.

For example, this means that you should not make your own User instances nor should you modify the User instance yourself.

If you want to get one of these model classes instances they’d have to be through the cache, and a common way of doing so is through the utils.find() function or attributes of model classes that you receive from the events specified in the Event Reference.

Note

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

User¶

class discord.ClientUser¶

Represents your Discord user.

x == y: Checks if two users are equal.

x != y: Checks if two users are not equal.

hash(x): Return the user’s hash.

str(x): Returns the user’s handle (e.g. name or name#discriminator).

Changed in version 2.0: Locale is now a Locale instead of a Optional[str].

name¶

The user’s username.

Type: str

id¶

The user’s unique ID.

Type: int

discriminator¶

The user’s discriminator. This is a legacy concept that is no longer used.

Type: str

bio¶

The user’s “about me” field. Could be None.

Type: Optional[str]

global_name¶

The user’s global nickname, taking precedence over the username in display.

New in version 2.1.

Type: Optional[str]

bot¶

Specifies if the user is a bot account.

Type: bool

system¶

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

New in version 1.3.

Type: bool

verified¶

Specifies if the user’s email is verified.

Type: bool

email¶

The email of the user.

Type: Optional[str]

phone¶

The phone number of the user.

New in version 1.9.

Changed in version 2.1: This now returns a str instead of an int to match the API.

Type: Optional[str]

mfa_enabled¶

Specifies if the user has MFA turned on and working.

Type: bool

premium_type¶

Specifies the type of premium a user has (i.e. Nitro, Nitro Classic, or Nitro Basic).

Changed in version 2.1: This is now PremiumType.none instead of None if the user is not premium.

Type: PremiumType

note¶

The user’s note. Not pre-fetched.

New in version 1.9.

Type: Note

nsfw_allowed¶

Specifies if the user should be allowed to access NSFW content. If None, then the user’s date of birth is not known.

New in version 2.0.

Type: Optional[bool]

desktop¶

Specifies whether the user has used a desktop client.

New in version 2.0.

Type: bool

mobile¶

Specifies whether the user has used a mobile client.

New in version 2.0.

Type: bool

property locale¶

The IETF language tag used to identify the language the user is using.

Type: Locale

property flags¶

Returns the user’s flags (including private).

New in version 2.0.

Type: PrivateUserFlags

property premium_usage_flags¶

Returns the user’s premium usage flags.

New in version 2.0.

Type: PremiumUsageFlags

property purchased_flags¶

Returns the user’s purchased flags.

New in version 2.0.

Type: PurchasedFlags

await edit(*, username=..., global_name=..., avatar=..., avatar_decoration=..., password=..., new_password=..., email=..., house=..., discriminator=..., banner=..., accent_colour=..., accent_color=..., bio=..., date_of_birth=..., pomelo=...)¶

This function is a coroutine.

Edits the current profile of the client.

Note

To upload an avatar, a bytes-like object must be passed in that represents the image being uploaded. If this is done through a file then the file must be opened via open('some_filename', 'rb') and the bytes-like object is given through the use of fp.read().

Changed in version 2.0: The edit is no longer in-place, instead the newly edited client user is returned.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

password (str) – The current password for the client’s account. Required for everything except avatar, banner, accent_colour, date_of_birth, global_name, and bio.
new_password (str) – The new password you wish to change to.
email (str) – The new email you wish to change to.
house (Optional[HypeSquadHouse]) – The hypesquad house you wish to change to. Could be None to leave the current house.
username (str) – The new username you wish to change to.
discriminator (int) – The new discriminator you wish to change to. This is a legacy concept that is no longer used. Can only be used if you have Nitro.
avatar (Optional[bytes]) – A bytes-like object representing the image to upload. Could be None to denote no avatar.
avatar_decoration (Optional[bytes]) –
A bytes-like object representing the image to upload. Could be None to denote no avatar decoration.

New in version 2.0.
banner (bytes) – A bytes-like object representing the image to upload. Could be None to denote no banner.
accent_colour (Colour) –
A Colour object of the colour you want to set your profile to.

New in version 2.0.
bio (str) –
Your “about me” section. Could be None to represent no bio.

New in version 2.0.
date_of_birth (datetime.datetime) –
Your date of birth. Can only ever be set once.

New in version 2.0.
pomelo (bool) –
Whether to migrate your account to Discord’s new unique username system.

Note

This change cannot be undone and requires you to be in the pomelo rollout.

New in version 2.1.
global_name (Optional[str]) –
The new global display name you wish to change to.

New in version 2.1.

Raises

HTTPException – Editing your profile failed. You are not in the pomelo rollout.
ValueError – Username was not passed when migrating to pomelo. Discriminator was passed when migrated to pomelo. Password was not passed when it was required. house field was not a HypeSquadHouse. date_of_birth field was not a datetime.datetime. accent_colo(u)r parameter was not a Colour.

Returns

The newly edited client user.

Return type

ClientUser

property accent_color¶

Returns the user’s accent color, if applicable.

A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

There is an alias for this named accent_colour.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

property accent_colour¶

Returns the user’s accent colour, if applicable.

A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

There is an alias for this named accent_color.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

property avatar¶

Returns an Asset for the avatar the user has.

If the user has not uploaded a global avatar, None is returned. If you want the avatar that a user has displayed, consider display_avatar.

Type: Optional[Asset]

property avatar_decoration¶

Returns an Asset for the avatar decoration the user has.

If the user does not have a avatar decoration, None is returned.

New in version 2.0.

Type: Optional[Asset]

property avatar_decoration_sku_id¶

Returns the avatar decoration’s SKU ID.

If the user does not have a preset avatar decoration, None is returned.

New in version 2.1.

Type: Optional[int]

property banner¶

Returns the user’s banner asset, if available.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Asset]

property color¶

A property that returns a color denoting the rendered color for the user. This always returns Colour.default().

There is an alias for this named colour.

Type: Colour

property colour¶

A property that returns a colour denoting the rendered colour for the user. This always returns Colour.default().

There is an alias for this named color.

Type: Colour

property created_at¶

Returns the user’s creation time in UTC.

This is when the user’s Discord account was created.

Type: datetime.datetime

property default_avatar¶

Returns the default avatar for a given user.

Type: Asset

property display_avatar¶

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

property display_banner¶

Returns the user’s banner asset, if available.

This is the same as banner and is here for compatibility.

New in version 2.0.

Type: Optional[Asset]

property display_name¶

Returns the user’s display name.

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

Type: str

await fetch_mutual_friends()¶

This function is a coroutine.

Fetches mutual friends with the user.

New in version 2.1.

Raises: HTTPException – Fetching the mutual friends failed.
Returns: The mutual friends with the user.
Return type: List[User]

is_blocked()¶: bool: Checks if the user is blocked.

is_friend()¶: bool: Checks if the user is your friend.

is_pomelo()¶: bool: Checks if the user has migrated to Discord’s new unique username system

New in version 2.1.

property mention¶

Returns a string that allows you to mention the given user.

Type: str

mentioned_in(message)¶

Checks if the user is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the user is mentioned in the message.
Return type: bool

property premium¶: Indicates if the user is a premium user (i.e. has Discord Nitro).

await profile(*, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

A shorthand method to retrieve a UserProfile for the user.

Parameters

with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in UserProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in UserProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in UserProfile.mutual_friends and UserProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

Forbidden – Not allowed to fetch this profile.
HTTPException – Fetching the profile failed.

Returns

The profile of the user.

Return type

property public_flags¶

The publicly available flags the user has.

Type: PublicUserFlags

property relationship¶

Returns the Relationship with this user if applicable, None otherwise.

Type: Optional[Relationship]

property voice¶

Returns the user’s current voice state.

Type: Optional[VoiceState]

Methods

asyncack
asyncack_pins
asyncapplication_commands
asyncblock
asyncconnect
asynccreate_dm
asyncfetch_message
asyncfetch_mutual_friends
asyncgreet
async forhistory
defis_blocked
defis_friend
defis_pomelo
defmentioned_in
asyncpins
asyncprofile
asyncremove_friend
defsearch
asyncsend
asyncsend_friend_request
defslash_commands
deftyping
asyncunack
asyncunblock
asyncupload_files
defuser_commands

class discord.User¶

Represents a Discord user.

x == y: Checks if two users are equal.

x != y: Checks if two users are not equal.

hash(x): Return the user’s hash.

str(x): Returns the user’s handle (e.g. name or name#discriminator).

name¶

The user’s username.

Type: str

id¶

The user’s unique ID.

Type: int

discriminator¶

The user’s discriminator. This is a legacy concept that is no longer used.

Type: str

global_name¶

The user’s global nickname, taking precedence over the username in display.

New in version 2.1.

Type: Optional[str]

bot¶

Specifies if the user is a bot account.

Type: bool

system¶

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

Type: bool

premium_type¶

Specifies the type of premium a user has (i.e. Nitro, Nitro Classic, or Nitro Basic).

Note

This information is only available in certain contexts.

New in version 2.1.

Type: Optional[PremiumType]

async with typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

async for ... in slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

async for ... in user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property dm_channel¶

Returns the channel associated with this user if it exists.

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

Type: Optional[DMChannel]

property call¶

Returns the call associated with this user if it exists.

Type: Optional[PrivateCall]

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await create_dm()¶

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

await block()¶

This function is a coroutine.

Blocks the user.

Raises

Forbidden – Not allowed to block this user.
HTTPException – Blocking the user failed.

await unblock()¶

This function is a coroutine.

Unblocks the user.

Raises

Forbidden – Not allowed to unblock this user.
HTTPException – Unblocking the user failed.

await remove_friend()¶

This function is a coroutine.

Removes the user as a friend.

Raises

Forbidden – Not allowed to remove this user as a friend.
HTTPException – Removing the user as a friend failed.

property accent_color¶

Returns the user’s accent color, if applicable.

A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

There is an alias for this named accent_colour.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

property accent_colour¶

Returns the user’s accent colour, if applicable.

A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

There is an alias for this named accent_color.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

property avatar¶

Returns an Asset for the avatar the user has.

If the user has not uploaded a global avatar, None is returned. If you want the avatar that a user has displayed, consider display_avatar.

Type: Optional[Asset]

property avatar_decoration¶

Returns an Asset for the avatar decoration the user has.

If the user does not have a avatar decoration, None is returned.

New in version 2.0.

Type: Optional[Asset]

property avatar_decoration_sku_id¶

Returns the avatar decoration’s SKU ID.

If the user does not have a preset avatar decoration, None is returned.

New in version 2.1.

Type: Optional[int]

property banner¶

Returns the user’s banner asset, if available.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Asset]

property color¶

A property that returns a color denoting the rendered color for the user. This always returns Colour.default().

There is an alias for this named colour.

Type: Colour

property colour¶

A property that returns a colour denoting the rendered colour for the user. This always returns Colour.default().

There is an alias for this named color.

Type: Colour

property created_at¶

Returns the user’s creation time in UTC.

This is when the user’s Discord account was created.

Type: datetime.datetime

property default_avatar¶

Returns the default avatar for a given user.

Type: Asset

property display_avatar¶

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

property display_banner¶

Returns the user’s banner asset, if available.

This is the same as banner and is here for compatibility.

New in version 2.0.

Type: Optional[Asset]

property display_name¶

Returns the user’s display name.

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

Type: str

await fetch_message(id, /)¶

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

await fetch_mutual_friends()¶

This function is a coroutine.

Fetches mutual friends with the user.

New in version 2.1.

Raises: HTTPException – Fetching the mutual friends failed.
Returns: The mutual friends with the user.
Return type: List[User]

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

is_blocked()¶: bool: Checks if the user is blocked.

is_friend()¶: bool: Checks if the user is your friend.

is_pomelo()¶: bool: Checks if the user has migrated to Discord’s new unique username system

New in version 2.1.

property mention¶

Returns a string that allows you to mention the given user.

Type: str

mentioned_in(message)¶

Checks if the user is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the user is mentioned in the message.
Return type: bool

note¶

Returns an object representing the user’s note.

New in version 2.0.

Note

The underlying note is cached and updated from gateway events.

Type: Note

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

property premium¶: Indicates if the user is a premium user (i.e. has Discord Nitro).

await profile(*, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

A shorthand method to retrieve a UserProfile for the user.

Parameters

with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in UserProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in UserProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in UserProfile.mutual_friends and UserProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

Forbidden – Not allowed to fetch this profile.
HTTPException – Fetching the profile failed.

Returns

The profile of the user.

Return type

property public_flags¶

The publicly available flags the user has.

Type: PublicUserFlags

property relationship¶

Returns the Relationship with this user if applicable, None otherwise.

Type: Optional[Relationship]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await send_friend_request()¶

This function is a coroutine.

Sends the user a friend request.

Raises

Forbidden – Not allowed to send a friend request to the user.
HTTPException – Sending the friend request failed.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

property voice¶

Returns the user’s current voice state.

Type: Optional[VoiceState]

Methods

asyncack
asyncack_pins
asyncapplication_commands
asyncblock
asyncconnect
asynccreate_dm
asyncfetch_message
asyncfetch_mutual_friends
asyncgreet
async forhistory
defis_blocked
defis_friend
defis_pomelo
defmentioned_in
asyncpins
asyncprofile
asyncremove_friend
defsearch
asyncsend
asyncsend_friend_request
defslash_commands
deftyping
asyncunack
asyncunblock
asyncupload_files
defuser_commands

class discord.UserProfile¶

Represents a Discord user’s profile.

This is a User with extended attributes.

x == y: Checks if two users are equal.

x != y: Checks if two users are not equal.

hash(x): Return the user’s hash.

str(x): Returns the user’s name with discriminator.

Note

Information may be missing or inaccurate if the user has blocked the client user.

New in version 2.0.

application¶

The application profile of the user, if it is a bot.

Type: Optional[ApplicationProfile]

metadata¶

The global profile metadata of the user.

New in version 2.1.

Type: ProfileMetadata

legacy_username¶

The user’s legacy username (Username#Discriminator), if public.

New in version 2.1.

Type: Optional[str]

bio¶

The user’s “about me” field. Could be None.

Type: Optional[str]

premium_type¶

Specifies the type of premium a user has (i.e. Nitro, Nitro Classic, or Nitro Basic).

Changed in version 2.1: This is now PremiumType.none instead of None if the user is not premium.

Type: Optional[PremiumType]

premium_since¶

An aware datetime object that specifies how long a user has been premium (had Nitro). None if the user is not a premium user.

Type: Optional[datetime.datetime]

premium_guild_since¶

An aware datetime object that specifies when a user first Nitro boosted a guild.

Type: Optional[datetime.datetime]

connections¶

The connected accounts that show up on the profile.

Type: Optional[List[PartialConnection]]

badges¶

A list of badge icons that the user has.

New in version 2.1.

Type: List[ProfileBadge]

mutual_guilds¶

A list of guilds that you share with the user. None if you didn’t fetch mutual guilds.

Type: Optional[List[MutualGuild]]

mutual_friends¶

A list of friends that you share with the user. None if you didn’t fetch mutual friends.

Type: Optional[List[User]]

property display_bio¶

Returns the user’s display bio.

This is the same as bio and is here for compatibility.

Type: Optional[str]

property accent_color¶

Returns the user’s accent color, if applicable.

A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

There is an alias for this named accent_colour.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

property accent_colour¶

Returns the user’s accent colour, if applicable.

A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

There is an alias for this named accent_color.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

property avatar¶

Returns an Asset for the avatar the user has.

If the user has not uploaded a global avatar, None is returned. If you want the avatar that a user has displayed, consider display_avatar.

Type: Optional[Asset]

property avatar_decoration¶

Returns an Asset for the avatar decoration the user has.

If the user does not have a avatar decoration, None is returned.

New in version 2.0.

Type: Optional[Asset]

property avatar_decoration_sku_id¶

Returns the avatar decoration’s SKU ID.

If the user does not have a preset avatar decoration, None is returned.

New in version 2.1.

Type: Optional[int]

property banner¶

Returns the user’s banner asset, if available.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Asset]

await block()¶

This function is a coroutine.

Blocks the user.

Raises

Forbidden – Not allowed to block this user.
HTTPException – Blocking the user failed.

property call¶

Returns the call associated with this user if it exists.

Type: Optional[PrivateCall]

property color¶

A property that returns a color denoting the rendered color for the user. This always returns Colour.default().

There is an alias for this named colour.

Type: Colour

property colour¶

A property that returns a colour denoting the rendered colour for the user. This always returns Colour.default().

There is an alias for this named color.

Type: Colour

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await create_dm()¶

This function is a coroutine.

Creates a DMChannel with this user.

This should be rarely called, as this is done transparently for most people.

Returns: The channel that was created.
Return type: DMChannel

property created_at¶

Returns the user’s creation time in UTC.

This is when the user’s Discord account was created.

Type: datetime.datetime

property default_avatar¶

Returns the default avatar for a given user.

Type: Asset

property display_avatar¶

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

property display_banner¶

Returns the user’s banner asset, if available.

This is the same as banner and is here for compatibility.

New in version 2.0.

Type: Optional[Asset]

property display_name¶

Returns the user’s display name.

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

Type: str

property dm_channel¶

Returns the channel associated with this user if it exists.

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

Type: Optional[DMChannel]

await fetch_message(id, /)¶

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

await fetch_mutual_friends()¶

This function is a coroutine.

Fetches mutual friends with the user.

New in version 2.1.

Raises: HTTPException – Fetching the mutual friends failed.
Returns: The mutual friends with the user.
Return type: List[User]

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

is_blocked()¶: bool: Checks if the user is blocked.

is_friend()¶: bool: Checks if the user is your friend.

is_pomelo()¶: bool: Checks if the user has migrated to Discord’s new unique username system

New in version 2.1.

property mention¶

Returns a string that allows you to mention the given user.

Type: str

mentioned_in(message)¶

Checks if the user is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the user is mentioned in the message.
Return type: bool

property mutual_friends_count¶

The number of mutual friends the user has with the client user.

Type: Optional[int]

note¶

Returns an object representing the user’s note.

New in version 2.0.

Note

The underlying note is cached and updated from gateway events.

Type: Note

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

property premium¶

Indicates if the user is a premium user.

Type: bool

await profile(*, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

A shorthand method to retrieve a UserProfile for the user.

Parameters

with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in UserProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in UserProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in UserProfile.mutual_friends and UserProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

Forbidden – Not allowed to fetch this profile.
HTTPException – Fetching the profile failed.

Returns

The profile of the user.

Return type

property public_flags¶

The publicly available flags the user has.

Type: PublicUserFlags

property relationship¶

Returns the Relationship with this user if applicable, None otherwise.

Type: Optional[Relationship]

await remove_friend()¶

This function is a coroutine.

Removes the user as a friend.

Raises

Forbidden – Not allowed to remove this user as a friend.
HTTPException – Removing the user as a friend failed.

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await send_friend_request()¶

This function is a coroutine.

Sends the user a friend request.

Raises

Forbidden – Not allowed to send a friend request to the user.
HTTPException – Sending the friend request failed.

slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await unblock()¶

This function is a coroutine.

Unblocks the user.

Raises

Forbidden – Not allowed to unblock this user.
HTTPException – Unblocking the user failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property voice¶

Returns the user’s current voice state.

Type: Optional[VoiceState]

Attributes

accent_color
accent_colour
banner
bio
effect_id
pronouns
theme_colors
theme_colours

class discord.ProfileMetadata¶

Represents global or per-user Discord profile metadata.

New in version 2.1.

bio¶

The profile’s “about me” field. Could be None.

Type: Optional[str]

pronouns¶

The profile’s pronouns, if any.

Type: Optional[str]

effect_id¶

The ID of the profile effect the user has, if any.

Type: Optional[int]

property banner¶

Returns the user’s banner asset, if available.

Type: Optional[Asset]

property accent_colour¶

Returns the profile’s accent colour, if applicable.

A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

There is an alias for this named accent_color.

Type: Optional[Colour]

property accent_color¶

Returns the profile’s accent color, if applicable.

A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

There is an alias for this named accent_colour.

Type: Optional[Colour]

property theme_colours¶

Returns the profile’s theme colours, if applicable.

The first colour is the user’s background colour and the second is the user’s foreground colour.

There is an alias for this named theme_colors.

Type: Optional[Tuple[Colour, Colour]]

property theme_colors¶

Returns the profile’s theme colors, if applicable.

The first color is the user’s background color and the second is the user’s foreground color.

There is an alias for this named theme_colours.

Type: Optional[Tuple[Colour, Colour]]

Attributes

animated
description
id
link
url

class discord.ProfileBadge¶

Represents a Discord profile badge.

x == y: Checks if two badges are equal.

x != y: Checks if two badges are not equal.

hash(x): Returns the badge’s hash.

str(x): Returns the badge’s description.

New in version 2.1.

id¶

The badge’s ID.

Type: str

description¶

The badge’s description.

Type: str

link¶

The link associated with the badge, if any.

Type: Optional[str]

property animated¶

Indicates if the badge is animated. Here for compatibility purposes.

Type: bool

property url¶

Returns the URL of the badge icon.

Type: str

Attributes

note
user
user_id
value

Methods

asyncdelete
asyncedit
asyncfetch

class discord.Note¶

Represents a Discord note.

x == y
Checks if two notes are equal.

x != y
Checks if two notes are not equal.

hash(x)
Returns the note's hash.

str(x)
Returns the note's content.
Raises :exc:`ClientException` if the note is not fetched.

bool(x)
Returns the note's content as a boolean.

len(x)
Returns the note's length.

New in version 1.9.

user_id¶

The user ID the note is for.

Type: int

property note¶

Returns the note.

There is an alias for this called value.

Raises: ClientException – Attempted to access note without fetching it.
Type: Optional[str]

property value¶

Returns the note.

This is an alias of note.

Raises: ClientException – Attempted to access note without fetching it.
Type: Optional[str]

property user¶

Returns the user the note belongs to.

Type: Optional[User]

await fetch()¶

This function is a coroutine.

Retrieves the note.

Raises: HTTPException – Fetching the note failed.
Returns: The note or None if it doesn’t exist.
Return type: Optional[str]

await edit(note)¶

This function is a coroutine.

Modifies the note. Can be at most 256 characters.

Raises: HTTPException – Changing the note failed.

await delete()¶

This function is a coroutine.

A shortcut to edit() that deletes the note.

Raises: HTTPException – Deleting the note failed.

Affinity¶

Attributes

affinity
id
user
user_id

class discord.UserAffinity¶

Represents a user’s affinity with another user.

User affinities that the current user has a mutual guild with are treated as implicit relationships, meaning that you get their user presence synced like a friend.

These implicit relationships are not real relationships, and are therefore not returned by the API. However, they are lazily added to cache by the library when detected.

x == y: Checks if two affinities are equal.

x != y: Checks if two affinities are not equal.

hash(x): Return the affinity’s hash.

New in version 2.0.

user_id¶

The ID of the user being compared.

Type: int

affinity¶

The affinity score.

Type: float

property id¶

The ID of the user being compared.

Type: int

property user¶

The user being compared.

Type: Optional[User]

Attributes

affinity
guild
guild_id
id

class discord.GuildAffinity¶

Represents a user’s affinity with a guild.

x == y: Checks if two affinities are equal.

x != y: Checks if two affinities are not equal.

hash(x): Return the affinity’s hash.

New in version 2.0.

guild_id¶

The ID of the guild being compared.

Type: int

affinity¶

The affinity score.

Type: float

property id¶

The ID of the guild being compared.

Type: int

property guild¶

The guild being compared.

Type: Optional[Guild]

Billing¶

Attributes

address
city
country
email
name
postal_code
state

Methods

asyncvalidate

class discord.BillingAddress¶

Represents a billing address.

x == y: Checks if two billing addresses are equal.

x != y: Checks if two billing addresses are not equal.

hash(x): Returns the address’ hash.

New in version 2.0.

name¶

The payment source’s name.

Type: str

address¶

The location’s address.

Type: str

postal_code¶

The location’s postal code.

Type: Optional[str]

city¶

The location’s city.

Type: str

state¶

The location’s state or province.

Type: Optional[str]

country¶

The location’s country.

Type: str

email¶

The email address associated with the payment source, if any.

Type: Optional[str]

await validate()¶

This function is a coroutine.

Validates the billing address.

Raises

TypeError – The billing address does not have state attached.
HTTPException – The billing address is invalid.

Returns

The billing address token.

Return type

Attributes

bank
billing_address
brand
country
default
email
expires_at
flags
id
invalid
partial_card_number
payment_gateway
type
username

Methods

asyncdelete
asyncedit

class discord.PaymentSource¶

Represents a payment source.

x == y: Checks if two payment sources are equal.

x != y: Checks if two payment sources are not equal.

hash(x): Returns the source’s hash.

New in version 2.0.

id¶

The ID of the payment source.

Type: int

brand¶

The brand of the payment source. This is only available for cards.

Type: Optional[str]

country¶

The country of the payment source. Not available in all contexts.

Type: Optional[str]

partial_card_number¶

The last four digits of the payment source. This is only available for cards.

Type: Optional[str]

billing_address¶

The billing address of the payment source. Not available in all contexts.

Type: Optional[BillingAddress]

type¶

The type of the payment source.

Type: PaymentSourceType

payment_gateway¶

The payment gateway of the payment source.

Type: PaymentGateway

default¶

Whether the payment source is the default payment source.

Type: bool

invalid¶

Whether the payment source is invalid.

Type: bool

expires_at¶

When the payment source expires. This is only available for cards.

Type: Optional[datetime.date]

email¶

The email address associated with the payment source, if any. This is only available for PayPal.

Type: Optional[str]

bank¶

The bank associated with the payment source, if any. This is only available for certain payment sources.

Type: Optional[str]

username¶

The username associated with the payment source, if any. This is only available for Venmo.

Type: Optional[str]

property flags¶

Returns the payment source’s flags.

Type: PaymentSourceFlags

await edit(*, billing_address=..., default=..., expires_at=...)¶

This function is a coroutine.

Edits the payment source.

Parameters

billing_address (BillingAddress) – The billing address of the payment source.
default (bool) – Whether the payment source is the default payment source.
expires_at (datetime.date) – When the payment source expires. This is only applicable to cards.

Raises

HTTPException – Editing the payment source failed.

await delete()¶

This function is a coroutine.

Deletes the payment source.

Raises: HTTPException – Deleting the payment source failed.

Attributes

animated_emojis
global_emojis
hd_hours_streamed
hd_streams
large_uploads
sticker_sends

class discord.PremiumUsage¶

Represents the usage of a user’s premium perks.

New in version 2.0.

sticker_sends¶

The number of premium sticker sends.

Type: int

animated_emojis¶

The number of animated emojis used.

Type: int

global_emojis¶

The number of global emojis used.

Type: int

large_uploads¶

The number of large uploads made.

Type: int

hd_streams¶

The number of HD streams.

Type: int

hd_hours_streamed¶

The number of hours streamed in HD.

Type: int

Connection¶

Attributes

access_token
friend_sync
integrations
metadata
metadata_visible
revoked
show_activity
two_way_link
url

Methods

asyncdelete
asyncedit
asyncfetch_access_token
asyncrefresh

class discord.Connection¶

Represents a Discord profile connection.

New in version 2.0.

x == y: Checks if two connections are equal.

x != y: Checks if two connections are not equal.

hash(x): Return the connection’s hash.

str(x): Returns the connection’s name.

revoked¶

Whether the connection is revoked.

Type: bool

friend_sync¶

Whether friends are synced over the connection.

Type: bool

show_activity¶

Whether activities from this connection will be shown in presences.

Type: bool

two_way_link¶

Whether the connection is authorized both ways (i.e. it’s both a connection and an authorization).

Type: bool

metadata_visible¶

Whether the connection’s metadata is visible.

Type: bool

metadata¶

Various metadata about the connection.

The contents of this are always subject to change.

Type: Optional[Metadata]

access_token¶

The OAuth2 access token for the account, if applicable.

Type: Optional[str]

integrations¶

The integrations attached to the connection.

Type: List[Integration]

await edit(*, name=..., visible=..., friend_sync=..., show_activity=..., metadata_visible=...)¶

This function is a coroutine.

Edit the connection.

All parameters are optional.

Parameters

name (str) – The new name of the connection. Only editable for certain connection types.
visible (bool) – Whether the connection is visible on your profile.
show_activity (bool) – Whether activities from this connection will be shown in presences.
friend_sync (bool) – Whether friends are synced over the connection.
metadata_visible (bool) – Whether the connection’s metadata is visible.

Raises

HTTPException – Editing the connection failed.

Returns

The edited connection.

Return type

Connection

await refresh()¶

This function is a coroutine.

Refreshes the connection. This updates the connection’s metadata.

Raises: HTTPException – Refreshing the connection failed.

await delete()¶

This function is a coroutine.

Removes the connection.

Raises: HTTPException – Deleting the connection failed.

await fetch_access_token()¶

This function is a coroutine.

Retrieves a new access token for the connection. Only applicable for connections of type:attr:ConnectionType.twitch, ConnectionType.youtube, and ConnectionType.spotify.

Raises: HTTPException – Retrieving the access token failed.
Returns: The new access token.
Return type: str

property url¶

Returns a URL linking to the connection’s profile, if available.

Type: Optional[str]

Attributes

id
metadata
name
type
url
verified
visible

class discord.PartialConnection¶

Represents a partial Discord profile connection.

This is the info you get for other users’ connections.

New in version 2.0.

x == y: Checks if two connections are equal.

x != y: Checks if two connections are not equal.

hash(x): Return the connection’s hash.

str(x): Returns the connection’s name.

id¶

The connection’s account ID.

Type: str

name¶

The connection’s account name.

Type: str

type¶

The connection service type (e.g. youtube, twitch, etc.).

Type: ConnectionType

verified¶

Whether the connection is verified.

Type: bool

visible¶

Whether the connection is visible on the user’s profile.

Type: bool

metadata¶

Various metadata about the connection.

The contents of this are always subject to change.

Type: Optional[Metadata]

property url¶

Returns a URL linking to the connection’s profile, if available.

Type: Optional[str]

Relationship¶

Attributes

activities
activity
desktop_status
id
mobile_status
nick
raw_status
since
status
type
user
web_status

Methods

asyncaccept
asyncdelete
asyncedit
defis_on_mobile

class discord.Relationship¶

Represents a relationship in Discord.

A relationship is like a friendship, a person who is blocked, etc.

x == y: Checks if two relationships are equal.

x != y: Checks if two relationships are not equal.

hash(x): Return the relationship’s hash.

user¶

The user you have the relationship with.

Type: User

type¶

The type of relationship you have.

Type: RelationshipType

nick¶

The user’s friend nickname (if applicable).

New in version 1.9.

Changed in version 2.0: Renamed nickname to nick.

Type: Optional[str]

since¶

When the relationship was created. Only available for type RelationshipType.incoming_request.

New in version 2.0.

Type: Optional[datetime.datetime]

property id¶

Returns the relationship’s ID.

Type: int

property status¶

The user’s overall status.

New in version 2.0.

Note

This is only reliably provided for type RelationshipType.friend.

Type: Status

property raw_status¶

The user’s overall status as a string value.

New in version 2.0.

Note

This is only reliably provided for type RelationshipType.friend.

Type: str

property mobile_status¶

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

New in version 2.0.

Note

This is only reliably provided for type RelationshipType.friend.

Type: Status

property desktop_status¶

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

New in version 2.0.

Note

This is only reliably provided for type RelationshipType.friend.

Type: Status

property web_status¶

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

New in version 2.0.

Note

This is only reliably provided for type RelationshipType.friend.

Type: Status

is_on_mobile()¶: bool: A helper function that determines if a user is active on a mobile device.

New in version 2.0.

Note

This is only reliably provided for type RelationshipType.friend.

property activities¶

Returns the activities that the user is currently doing.

New in version 2.0.

Note

This is only reliably provided for type RelationshipType.friend.

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 GH-1738 for more information.

Type: Tuple[Union[BaseActivity, Spotify]]

property activity¶

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

New in version 2.0.

Note

This is only reliably provided for type RelationshipType.friend.

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 GH-1738 for more information.

Note

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

Type: Optional[Union[BaseActivity, Spotify]]

await delete()¶

This function is a coroutine.

Deletes the relationship.

Depending on the type, this could mean unfriending or unblocking the user, denying an incoming friend request, discarding an outgoing friend request, etc.

Raises: HTTPException – Deleting the relationship failed.

await accept()¶

This function is a coroutine.

Accepts the relationship request. Only applicable for type RelationshipType.incoming_request.

Raises: HTTPException – Accepting the relationship failed.

await edit(nick=...)¶

This function is a coroutine.

Edits the relationship.

New in version 1.9.

Changed in version 2.0: Changed the name of the method to edit(). The edit is no longer in-place.

Parameters: nick (Optional[str]) – The nickname to change to. Can be None to denote no nickname.
Raises: HTTPException – Changing the nickname failed.

Attributes

from_user_contacts
reasons
user

Methods

asyncaccept
asyncdelete

class discord.FriendSuggestion¶

Represents a friend suggestion on Discord.

x == y: Checks if two friend suggestions are equal.

x != y: Checks if two friend suggestions are not equal.

hash(x): Return the suggestion’s hash.

New in version 2.1.

user¶

The suggested user.

Type: User

reasons¶

The reasons why the user was suggested.

Type: List[FriendSuggestionReason]

from_user_contacts¶

Whether the suggested user had the current user in their contacts.

Type: bool

await accept()¶

This function is a coroutine.

Accepts the friend suggestion. This creates a Relationship of type RelationshipType.outgoing_request.

Raises: HTTPException – Accepting the relationship failed.

await delete()¶

This function is a coroutine.

Ignores the friend suggestion.

Raises: HTTPException – Deleting the relationship failed.

Attributes

name
platform
type

class discord.FriendSuggestionReason¶

Represents a reason why a user was suggested as a friend to you.

New in version 2.1.

type¶

The type of friend suggestion reason.

Type: FriendSuggestionReasonType

platform¶

The platform the user was suggested from.

Type: ConnectionType

name¶

The user’s name on the platform.

Type: str

Settings¶

Attributes

activity_joining_restricted_guilds
activity_restricted_guilds
afk_timeout
allow_accessibility_detection
allow_activity_friend_joins
allow_activity_voice_channel_joins
always_preview_video
animate_emojis
animate_stickers
client_theme
client_version
collapsed_emoji_picker_sections
collapsed_sticker_picker_sections
contact_sync_enabled
convert_emoticons
custom_activity
data_version
default_guilds_activity_restricted
default_guilds_restricted
default_message_request_restricted
detect_platform_accounts
developer_mode
disable_games_tab
disable_mobile_redesign
dismissed_contents
diversity_surrogate
drops
enable_tts_command
explicit_content_filter
friend_discovery_flags
friend_source_flags
gif_auto_play
guild_folders
guild_positions
guild_progress_settings
home_auto_navigation
in_app_notifications
inbox_tab
inbox_tutorial_viewed
inline_attachment_media
inline_embed_media
install_shortcut_desktop
install_shortcut_start_menu
last_dismissed_promotion_start_date
locale
message_display_compact
message_request_restricted_guilds
native_phone_integration_enabled
nitro_basic_modal_dismissed_at
non_spam_retraining
notification_center_acked_before_id
passwordless
render_embeds
render_reactions
render_spoilers
restricted_guilds
rtc_panel_show_voice_states
send_stream_notifications
server_version
show_command_suggestions
show_current_game
show_expression_suggestions
soundboard_volume
status
stream_audio_settings
stream_notifications_enabled
theme
timezone_offset
use_legacy_chat_input
use_thread_sidebar
user_audio_settings
view_image_descriptions
view_nsfw_commands
view_nsfw_guilds

Methods

asyncedit

class discord.UserSettings¶

Represents the Discord client settings.

New in version 2.0.

property data_version¶

The version of the settings. Increases on every change.

Type: int

property client_version¶

The client version of the settings. Used for client-side data migrations.

Type: int

property server_version¶

The server version of the settings. Used for server-side data migrations.

Type: int

property inbox_tab¶

The current (last opened) inbox tab.

Type: InboxTab

property inbox_tutorial_viewed¶

Whether the inbox tutorial has been viewed.

Type: bool

property guild_progress_settings¶

A list of guild progress settings.

Type: List[GuildProgress]

property dismissed_contents¶

A list of enum values representing dismissable content in the app.

Note

For now, this just returns the raw values without converting to a proper enum, as the enum values change too often to be viably maintained.

Type: Tuple[int]

property last_dismissed_promotion_start_date¶

The date the last dismissed promotion started.

Type: Optional[datetime.datetime]

property nitro_basic_modal_dismissed_at¶

The date the Nitro Basic modal was dismissed.

Type: Optional[datetime.datetime]

property always_preview_video¶: Whether to always show the preview modal when the user turns on their camera.

property afk_timeout¶

How long (in seconds) the user needs to be AFK until Discord sends push notifications to mobile devices (30-600).

Type: int

property stream_notifications_enabled¶

Whether stream notifications for friends will be received.

Type: bool

property native_phone_integration_enabled¶

Whether to enable the Discord mobile Callkit.

Type: bool

property soundboard_volume¶

The volume of the soundboard (0-100).

Type: float

property diversity_surrogate¶

The unicode character used as the diversity surrogate for supported emojis (i.e. emoji skin tones, 🏻).

Type: Optional[str]

property use_thread_sidebar¶

Whether to open threads in split view.

Type: bool

property render_spoilers¶

When to show spoiler content.

Type: SpoilerRenderOptions

property collapsed_emoji_picker_sections¶

A list of emoji picker sections (including guild IDs) that are collapsed.

Type: Tuple[Union[EmojiPickerSection, Guild]]

property collapsed_sticker_picker_sections¶

A list of sticker picker sections (including guild and sticker pack IDs) that are collapsed.

Type: Tuple[Union[StickerPickerSection, Guild, Object]]

property view_image_descriptions¶

Whether to display the alt text of attachments.

Type: bool

property show_command_suggestions¶

Whether to show application command suggestions in-chat.

Type: bool

property inline_attachment_media¶

Whether to display attachments when they are uploaded in chat.

Type: bool

property inline_embed_media¶

Whether to display videos and images from links posted in chat.

Type: bool

property gif_auto_play¶

Whether to automatically play GIFs that are in the chat..

Type: bool

property render_embeds¶

Whether to render embeds that are sent in the chat.

Type: bool

property render_reactions¶

Whether to render reactions that are added to messages.

Type: bool

property animate_emojis¶

Whether to animate emojis in the chat.

Type: bool

property animate_stickers¶

Whether to animate stickers in the chat.

Type: StickerAnimationOptions

property enable_tts_command¶

Whether to allow TTS messages to be played/sent.

Type: bool

property message_display_compact¶

Whether to use the compact Discord display mode.

Type: bool

property explicit_content_filter¶

The filter for explicit content in all messages.

Type: UserContentFilter

property view_nsfw_guilds¶

Whether to show NSFW guilds on iOS.

Type: bool

property convert_emoticons¶

Whether to automatically convert emoticons into emojis (e.g. :) -> 😃).

Type: bool

property show_expression_suggestions¶

Whether to show expression (emoji/sticker/soundboard) suggestions in-chat.

Type: bool

property view_nsfw_commands¶

Whether to show NSFW application commands in DMs.

Type: bool

property use_legacy_chat_input¶

Whether to use the legacy chat input over the new rich input.

Type: bool

property in_app_notifications¶

Whether to show notifications directly in the app.

Type: bool

property send_stream_notifications¶

Whether to send notifications to friends when using the go live feature.

Type: bool

property notification_center_acked_before_id¶

The ID of the last notification that was acknowledged in the notification center.

Type: int

property allow_activity_friend_joins¶

Whether to allow friends to join your activity without sending a request.

Type: bool

property allow_activity_voice_channel_joins¶

Whether to allow people in the same voice channel as you to join your activity without sending a request. Does not apply to Community guilds.

Type: bool

property restricted_guilds¶

A list of guilds that you will not receive DMs from.

Type: List[Guild]

property default_guilds_restricted¶

Whether to automatically disable DMs between you and members of new guilds you join.

Type: bool

property allow_accessibility_detection¶

Whether to allow Discord to track screen reader usage.

Type: bool

property detect_platform_accounts¶

Whether to automatically detect accounts from services like Steam and Blizzard when you open the Discord client.

Type: bool

property passwordless¶

Whether to enable passwordless login.

Type: bool

property contact_sync_enabled¶

Whether to enable the contact sync on Discord mobile.

Type: bool

property friend_source_flags¶

Who can add you as a friend.

Type: FriendSourceFlags

property friend_discovery_flags¶

How you get recommended friends.

Type: FriendDiscoveryFlags

property activity_restricted_guilds¶

A list of guilds that your current activity will not be shown in.

Type: List[Guild]

property default_guilds_activity_restricted¶

Whether to automatically disable showing your current activity in new large (over 200 member) guilds you join.

Type: bool

property activity_joining_restricted_guilds¶

A list of guilds that will not be able to join your current activity.

Type: List[Guild]

property message_request_restricted_guilds¶

A list of guilds whose originating DMs will not be filtered into your message requests.

Type: List[Guild]

property default_message_request_restricted¶

Whether to automatically disable the message request system in new guilds you join.

Type: bool

property drops¶

Whether the Discord drops feature is enabled.

Type: bool

property non_spam_retraining¶

Whether to help improve Discord spam models when marking messages as non-spam; staff only.

Type: Optional[bool]

property rtc_panel_show_voice_states¶

Whether to show voice states in the RTC panel.

Type: bool

property install_shortcut_desktop¶

Whether to install a desktop shortcut for games.

Type: bool

property install_shortcut_start_menu¶

Whether to install a start menu shortcut for games.

Type: bool

property disable_games_tab¶

Whether to disable the showing of the Games tab.

Type: bool

property status¶

The configured status.

Type: Status

property custom_activity¶

The set custom activity.

Type: CustomActivity

property show_current_game¶

Whether to show the current game.

Type: bool

property locale¶

The RFC 3066 language identifier of the locale to use for the language of the Discord client.

Type: Locale

property timezone_offset¶

The timezone offset from UTC to use (in minutes).

Type: int

property theme¶

The overall theme of the Discord UI.

Type: Theme

property client_theme¶

The client theme settings, in order of primary color, gradient preset, and gradient angle.

Type: Optional[Tuple[int, int, float]]

property developer_mode¶

Whether to enable developer mode.

Type: bool

property disable_mobile_redesign¶

Whether to opt-out of the mobile redesign.

Type: bool

property guild_folders¶

A list of guild folders.

Type: List[GuildFolder]

property guild_positions¶

A list of guilds in order of the guild/guild icons that are on the left hand side of the UI.

Type: List[Guild]

property user_audio_settings¶

A list of audio context settings for users.

Type: List[AudioContext]

property stream_audio_settings¶

A list of audio context settings for streams.

Type: List[AudioContext]

property home_auto_navigation¶

Whether to automatically redirect to guild home for guilds that have not been accessed in a while.

Type: bool

await edit(*, require_version=False, **kwargs)¶

This function is a coroutine.

Edits the current user’s settings.

Note

Settings subsections are not idempotently updated. This means if you change one setting in a subsection* on an outdated instance of UserSettings then the other settings in that subsection* will be reset to the value of the instance.

When operating on the cached user settings (i.e. Client.settings), this should not be an issue. However, if you are operating on a fetched instance, consider using the require_version parameter to ensure you don’t overwrite newer settings.

Any field may be explicitly set to MISSING to reset it to the default value.

* A subsection is a group of settings that are stored in the same top-level protobuf message. Examples include Privacy, Text and Images, Voice and Video, etc.

Note

This method is ratelimited heavily. Updates should be batched together and sent at intervals.

Infrequent actions do not need a delay. Frequent actions should be delayed by 10 seconds and batched. Automated actions (such as migrations or frecency updates) should be delayed by 30 seconds and batched. Daily actions (things that change often and are not meaningful, such as emoji frencency) should be delayed by 1 day and batched.

Parameters

require_version (Union[bool, int]) – Whether to require the current version of the settings to be the same as the provided version. If this is True then the current version is used.
**kwargs – The settings to edit. Refer to the UserSettings properties for the valid fields. Unknown fields are ignored.

Raises

HTTPException – Editing the settings failed.
TypeError – At least one setting is required to edit.

Returns

The edited settings. Note that this is a new instance and not the same as the cached instance as mentioned above.

Return type

UserSettings

class discord.LegacyUserSettings¶

Represents the legacy Discord client settings.

New in version 1.9.

Deprecated since version 2.0.

Note

Discord has migrated user settings to a new protocol buffer format. While these legacy settings still exist, they are no longer sent to newer clients (so they will have to be fetched).

The new settings are available in UserSettings, and this class has been deprecated and renamed to LegacyUserSettings. All options in this class are available in the new format, and changes are reflected in both.

afk_timeout¶

How long (in seconds) the user needs to be AFK until Discord sends push notifications to mobile devices (30-600).

Type: int

allow_accessibility_detection¶

Whether to allow Discord to track screen reader usage.

Type: bool

animate_emojis¶

Whether to animate emojis in the chat.

Type: bool

contact_sync_enabled¶

Whether to enable the contact sync on Discord mobile.

Type: bool

convert_emoticons¶

Whether to automatically convert emoticons into emojis (e.g. :) -> 😃).

Type: bool

default_guilds_restricted¶

Whether to automatically disable DMs between you and members of new guilds you join.

Type: bool

detect_platform_accounts¶

Whether to automatically detect accounts from services like Steam and Blizzard when you open the Discord client.

Type: bool

developer_mode¶

Whether to enable developer mode.

Type: bool

disable_games_tab¶

Whether to disable the showing of the Games tab.

Type: bool

enable_tts_command¶

Whether to allow TTS messages to be played/sent.

Type: bool

gif_auto_play¶

Whether to automatically play GIFs that are in the chat.

Type: bool

inline_attachment_media¶

Whether to display attachments when they are uploaded in chat.

Type: bool

inline_embed_media¶

Whether to display videos and images from links posted in chat.

Type: bool

message_display_compact¶

Whether to use the compact Discord display mode.

Type: bool

native_phone_integration_enabled¶

Whether to enable the new Discord mobile phone number friend requesting features.

Type: bool

render_embeds¶

Whether to render embeds that are sent in the chat.

Type: bool

render_reactions¶

Whether to render reactions that are added to messages.

Type: bool

show_current_game¶

Whether to display the game that you are currently playing.

Type: bool

stream_notifications_enabled¶

Whether stream notifications for friends will be received.

Type: bool

timezone_offset¶

The timezone offset from UTC to use (in minutes).

Type: int

view_nsfw_commands¶

Whether to show NSFW application commands in DMs.

New in version 2.0.

Type: bool

view_nsfw_guilds¶

Whether to show NSFW guilds on iOS.

Type: bool

await edit(**kwargs)¶

This function is a coroutine.

Edits the client user’s settings.

Changed in version 2.0: The edit is no longer in-place, instead the newly edited settings are returned.

Deprecated since version 2.0.

Parameters

activity_restricted_guilds (List[Snowflake]) –
A list of guilds that your current activity will not be shown in.

New in version 2.0.
activity_joining_restricted_guilds (List[Snowflake]) –
A list of guilds that will not be able to join your current activity.

New in version 2.0.
afk_timeout (int) – How long (in seconds) the user needs to be AFK until Discord sends push notifications to mobile device (30-600).
allow_accessibility_detection (bool) – Whether to allow Discord to track screen reader usage.
animate_emojis (bool) – Whether to animate emojis in the chat.
animate_stickers (StickerAnimationOptions) – Whether to animate stickers in the chat.
contact_sync_enabled (bool) – Whether to enable the contact sync on Discord mobile.
convert_emoticons (bool) – Whether to automatically convert emoticons into emojis (e.g. :) -> 😃).
default_guilds_restricted (bool) – Whether to automatically disable DMs between you and members of new guilds you join.
detect_platform_accounts (bool) – Whether to automatically detect accounts from services like Steam and Blizzard when you open the Discord client.
developer_mode (bool) – Whether to enable developer mode.
disable_games_tab (bool) – Whether to disable the showing of the Games tab.
enable_tts_command (bool) – Whether to allow TTS messages to be played/sent.
explicit_content_filter (UserContentFilter) – The filter for explicit content in all messages.
friend_source_flags (FriendSourceFlags) – Who can add you as a friend.
friend_discovery_flags (FriendDiscoveryFlags) – How you get recommended friends.
gif_auto_play (bool) – Whether to automatically play GIFs that are in the chat.
guild_positions (List[Snowflake]) – A list of guilds in order of the guild/guild icons that are on the left hand side of the UI.
inline_attachment_media (bool) – Whether to display attachments when they are uploaded in chat.
inline_embed_media (bool) – Whether to display videos and images from links posted in chat.
locale (Locale) – The RFC 3066 language identifier of the locale to use for the language of the Discord client.
message_display_compact (bool) – Whether to use the compact Discord display mode.
native_phone_integration_enabled (bool) – Whether to enable the new Discord mobile phone number friend requesting features.
passwordless (bool) – Whether to enable passwordless login.
render_embeds (bool) – Whether to render embeds that are sent in the chat.
render_reactions (bool) – Whether to render reactions that are added to messages.
restricted_guilds (List[Snowflake]) – A list of guilds that you will not receive DMs from.
show_current_game (bool) – Whether to display the game that you are currently playing.
stream_notifications_enabled (bool) – Whether stream notifications for friends will be received.
theme (Theme) – The overall theme of the Discord UI.
timezone_offset (int) – The timezone offset to use.
view_nsfw_commands (bool) –
Whether to show NSFW application commands in DMs.

New in version 2.0.
view_nsfw_guilds (bool) –
Whether to show NSFW guilds on iOS.

New in version 2.0.

Raises

HTTPException – Editing the settings failed.

Returns

The client user’s updated settings.

Return type

UserSettings

property activity_restricted_guilds¶

A list of guilds that your current activity will not be shown in.

New in version 2.0.

Type: List[Guild]

property activity_joining_restricted_guilds¶

A list of guilds that will not be able to join your current activity.

New in version 2.0.

Type: List[Guild]

property animate_stickers¶

Whether to animate stickers in the chat.

Type: StickerAnimationOptions

property custom_activity¶

The set custom activity.

Type: Optional[CustomActivity]

property explicit_content_filter¶

The filter for explicit content in all messages.

Type: UserContentFilter

property friend_source_flags¶

Who can add you as a friend.

Type: FriendSourceFlags

property friend_discovery_flags¶

How you get recommended friends.

Type: FriendDiscoveryFlags

property guild_folders¶

A list of guild folders.

Type: List[GuildFolder]

property guild_positions¶

A list of guilds in order of the guild/guild icons that are on the left hand side of the UI.

Type: List[Guild]

property locale¶

The RFC 3066 language identifier of the locale to use for the language of the Discord client.

Changed in version 2.0: This now returns a Locale object instead of a string.

Type: Locale

property passwordless¶

Whether to enable passwordless login.

Type: bool

property restricted_guilds¶

A list of guilds that you will not receive DMs from.

Type: List[Guild]

property status¶

The configured status.

Type: Optional[Status]

property theme¶

The overall theme of the Discord UI.

Type: Theme

Attributes

channel_overrides
guild
hide_muted_channels
level
mobile_push
mute_scheduled_events
muted
notify_highlights
suppress_everyone
suppress_roles
version

Methods

asyncedit

class discord.GuildSettings¶

Represents a guild’s notification settings.

New in version 2.0.

level¶

The notification level for the guild.

Type: NotificationLevel

muted¶

The mute configuration for the guild.

Type: MuteConfig

suppress_everyone¶

Whether to suppress @everyone/@here notifications.

Type: bool

suppress_roles¶

Whether to suppress role notifications.

Type: bool

hide_muted_channels¶

Whether to hide muted channels.

Type: bool

mobile_push¶

Whether to enable mobile push notifications.

Type: bool

mute_scheduled_events¶

Whether to mute scheduled events.

Type: bool

notify_highlights¶

Whether to include highlights in notifications.

Type: HighlightLevel

version¶

The version of the guild’s settings.

Type: int

property guild¶

Returns the guild that these settings are for.

If the returned value is a ClientUser then the settings are for the user’s private channels.

Type: Union[Guild, ClientUser]

property channel_overrides¶

Returns a list of all the overrided channel notification settings.

Type: List[ChannelSettings

await edit(muted_until=..., level=..., suppress_everyone=..., suppress_roles=..., mobile_push=..., hide_muted_channels=..., mute_scheduled_events=..., notify_highlights=...)¶

This function is a coroutine.

Edits the guild’s notification settings.

All parameters are optional.

Parameters

muted_until (Optional[Union[datetime.datetime, bool]]) –
The date this guild’s mute should expire. This can be True to mute indefinitely, or False/None to unmute.

This must be a timezone-aware datetime object. Consider using utils.utcnow().
level (NotificationLevel) – Determines what level of notifications you receive for the guild.
suppress_everyone (bool) – Indicates if @everyone mentions should be suppressed for the guild.
suppress_roles (bool) – Indicates if role mentions should be suppressed for the guild.
mobile_push (bool) – Indicates if push notifications should be sent to mobile devices for this guild.
hide_muted_channels (bool) – Indicates if channels that are muted should be hidden from the sidebar.
mute_scheduled_events (bool) – Indicates if scheduled events should be muted.
notify_highlights (HighlightLevel) – Indicates if highlights should be included in notifications.

Raises

HTTPException – Editing the settings failed.

Returns

The new notification settings.

Return type

GuildSettings

Attributes

channel
collapsed
level
muted

Methods

asyncedit

class discord.ChannelSettings¶

Represents a channel’s notification settings.

New in version 2.0.

level¶

The notification level for the channel.

Type: NotificationLevel

muted¶

The mute configuration for the channel.

Type: MuteConfig

collapsed¶

Whether the channel is collapsed. Only applicable to channels of type ChannelType.category.

Type: bool

property channel¶

Returns the channel these settings are for.

Type: Union[abc.GuildChannel, abc.PrivateChannel]

await edit(*, muted_until=..., collapsed=..., level=...)¶

This function is a coroutine.

Edits the channel’s notification settings.

All parameters are optional.

Parameters

muted_until (Optional[Union[datetime.datetime, bool]]) –
The date this channel’s mute should expire. This can be True to mute indefinitely, or False/None to unmute.

This must be a timezone-aware datetime object. Consider using utils.utcnow().
collapsed (bool) – Indicates if the channel should be collapsed or not. Only applicable to channels of type ChannelType.category.
level (NotificationLevel) – Determines what level of notifications you receive for the channel.

Raises

HTTPException – Editing the settings failed.

Returns

The new notification settings.

Return type

ChannelSettings

Attributes

personalization
usage_statistics

Methods

asyncedit

class discord.TrackingSettings¶

Represents your Discord tracking settings.

New in version 2.0.

bool(x): Checks if any tracking settings are enabled.

personalization¶

Whether you have consented to your data being used for personalization.

Type: bool

usage_statistics¶

Whether you have consented to your data being used for usage statistics.

Type: bool

await edit(**kwargs)¶

This function is a coroutine.

Edits your tracking settings.

Parameters

personalization (bool) – Whether you have consented to your data being used for personalization.
usage_statistics (bool) – Whether you have consented to your data being used for usage statistics.

Attributes

communication
family_center_digest
initialized
recommendations_and_events
social
tips
updates_and_announcements

Methods

asyncedit

class discord.EmailSettings¶

Represents email communication preferences.

New in version 2.0.

initialized¶

Whether the email communication preferences have been initialized.

Type: bool

communication¶

Whether you want to receive emails for missed calls/messages.

Type: bool

social¶

Whether you want to receive emails for friend requests/suggestions or events.

Type: bool

recommendations_and_events¶

Whether you want to receive emails for recommended servers and events.

Type: bool

tips¶

Whether you want to receive emails for advice and tricks.

Type: bool

updates_and_announcements¶

Whether you want to receive emails for updates and new features.

Type: bool

family_center_digest¶

Whether you want to receive weekly emails for recent family activity.

New in version 2.1.

Type: bool

await edit(**kwargs)¶

This function is a coroutine.

Edits the email settings.

All parameters are optional.

Parameters

communication (bool) – Indicates if you want to receive communication emails.
social (bool) – Indicates if you want to receive social emails.
recommendations_and_events (bool) – Indicates if you want to receive recommendations and events emails.
tips (bool) – Indicates if you want to receive tips emails.
updates_and_announcements (bool) – Indicates if you want to receive updates and announcements emails.

Raises

HTTPException – Editing the settings failed.

Attributes

color
colour
guilds
id
name

Methods

defadd_guild
defclear_guilds
defcopy
definsert_guild_at
defremove_guild
defset_guild_at

class discord.GuildFolder¶

Represents a guild folder.

All properties have setters to faciliate editing the class for use with UserSettings.edit().

Note

Guilds not in folders are actually in folders API wise, with them being the only member.

These folders do not have an ID or name.

str(x): Returns the folder’s name.

len(x): Returns the number of guilds in the folder.

New in version 1.9.

Changed in version 2.0: Removed various operations and made id and name optional.

id¶

The ID of the folder. This is None for fake folders, as outlined in the note above.

Type: Optional[int]

name¶

The name of the folder.

Type: Optional[str]

copy()¶: Returns a shallow copy of the folder.

add_guild(guild)¶

Adds a guild to the folder.

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

New in version 2.0.

Parameters: guild (abc.Snowflake) – The guild to add to the folder.

insert_guild_at(index, guild)¶

Inserts a guild before a specified index to the folder.

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

New in version 2.0.

Parameters

index (int) – The index of where to insert the field.
guild (abc.Snowflake) – The guild to add to the folder.

clear_guilds()¶: Removes all guilds from this folder.

New in version 2.0.

remove_guild(index)¶

Removes a guild 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.

New in version 2.0.

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

set_guild_at(index, guild)¶

Modifies a guild to the guild object.

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

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

New in version 2.0.

Parameters

index (int) – The index of the field to modify.
guild (abc.Snowflake) – The guild to add to the folder.

Raises

IndexError – An invalid index was provided.

property guilds¶

The guilds in the folder. Always Object if state is not attached.

Type: List[Union[Guild, Object]]

property colour¶

The colour code of the folder. There is an alias for this named colour.

Type: Optional[Colour]

property color¶

The colour code of the folder. There is an alias for this named colour.

Type: Optional[Colour]

Attributes

collapsed_channels
dismissed_contents
guild
guild_id
hub_progress
onboarding_progress
recents_dismissed_at

Methods

defcopy

class discord.GuildProgress¶

Represents a guild’s settings revolving around upsells, promotions, and feature progress.

All properties have setters to faciliate editing the class for use with UserSettings.edit().

New in version 2.0.

guild_id¶

The ID of the guild.

Type: int

recents_dismissed_at¶

When the guild recents were last dismissed.

Type: Optional[datetime.datetime]

copy()¶: Returns a shallow copy of the progress settings.

property guild¶

The guild this progress belongs to. None if state is not attached.

Type: Optional[Guild]

property hub_progress¶

The hub’s usage and feature progress.

Type: HubProgressFlags

property onboarding_progress¶

The guild’s onboarding usage and feature progress.

Type: OnboardingProgressFlags

property dismissed_contents¶

A list of enum values representing per-guild dismissable content in the app.

Note

For now, this just returns the raw values without converting to a proper enum, as the enum values change too often to be viably maintained.

Type: Tuple[int]

property collapsed_channels¶

A list of guild channels that are collapsed in the inbox. Always Object if state is not attached.

Type: List[Union[abc.GuildChannel, Object]]

Attributes

modified_at
muted
user
user_id
volume

Methods

defcopy
defto_dict

class discord.AudioContext¶

Represents saved audio settings for a user or stream.

All properties have setters to faciliate editing the class for use with UserSettings.edit().

New in version 2.0.

user_id¶

The ID of the user.

Type: int

muted¶

Whether the user or stream is muted.

Type: bool

volume¶

The volume of the user or stream (0-100).

Type: float

modified_at¶

The time the settings were last modified.

Type: datetime.datetime

to_dict()¶: Converts the object to a dictionary.

copy()¶: Returns a shallow copy of the audio context.

property user¶

The user the settings are for. None if state is not attached.

Type: Optional[User]

Attributes

muted
until

class discord.MuteConfig¶

An object representing an object’s mute status.

x == y: Checks if two items are muted.

x != y: Checks if two items are not muted.

str(x): Returns the mute status as a string.

int(x): Returns the mute status as an int.

New in version 2.0.

muted¶

Indicates if the object is muted.

Type: bool

until¶

When the mute will expire.

Type: Optional[datetime.datetime]

Application¶

Methods

asyncachievements
asyncactivity_statistics
asyncassets
asyncbranches
asynccreate_achievement
asynccreate_asset
asynccreate_bot
asynccreate_branch
asynccreate_gift_batch
asynccreate_sku
asynccreate_store_asset
asyncedit
asyncedit_bot
asyncedit_embedded_activity_config
asyncentitlement_ticket
async forentitlements
asynceula
asyncfetch_achievement
asyncfetch_bot
asyncfetch_discoverability
asyncfetch_embedded_activity_config
asyncfetch_entitlement
asyncgift_batches
defhas_bot
defis_rpc_enabled
asyncmanifest_labels
asyncprimary_sku
asyncprimary_store_listing
asyncpublished_store_listings
asyncsecret
asyncskus
asyncstore_assets
asyncstore_listing_sku
asyncticket
asyncwhitelist
asyncwhitelisted

class discord.Application¶

Represents application info for an application you own.

x == y: Checks if two applications are equal.

x != y: Checks if two applications are not equal.

hash(x): Return the application’s hash.

str(x): Returns the application’s name.

New in version 2.0.

owner¶

The application owner. This may be a team user account.

Type: User

bot¶

The bot attached to the application, if any.

Type: Optional[ApplicationBot]

disabled¶

Whether the bot attached to this application is disabled by Discord.

New in version 2.1.

Type: bool

quarantined¶

Whether the bot attached to this application is quarantined by Discord.

Quarantined bots cannot join more guilds or start new direct messages.

New in version 2.1.

Type: bool

interactions_endpoint_url¶

The URL interactions will be sent to, if set.

Type: Optional[str]

interactions_version¶

The interactions version to use. Different versions have different payloads and supported features.

New in version 2.1.

Type: int

interactions_event_types¶

The interaction event types to subscribe to. Requires a valid interactions_endpoint_url and interactions_version 2 or higher.

New in version 2.1.

Type: List[str]

role_connections_verification_url¶

The application’s connection verification URL which will render the application as a verification method in the guild’s role verification configuration.

Type: Optional[str]

redirect_uris¶

A list of redirect URIs authorized for this application.

Type: List[str]

verification_state¶

The verification state of the application.

Type: ApplicationVerificationState

store_application_state¶

The approval state of the commerce application.

Type: StoreApplicationState

rpc_application_state¶

The approval state of the RPC usage application.

Type: RPCApplicationState

discoverability_state¶

The state of the application in the application directory.

Type: ApplicationDiscoverabilityState

approximate_guild_count¶

The approximate number of guilds this application is in.

New in version 2.1.

Type: int

property discovery_eligibility_flags¶

The directory eligibility flags for this application.

Type: ApplicationDiscoveryFlags

has_bot()¶: bool: Whether the application has an attached bot.

New in version 2.1.

await edit(*, name=..., description=..., icon=..., cover_image=..., tags=..., terms_of_service_url=..., privacy_policy_url=..., deeplink_uri=..., interactions_endpoint_url=..., interactions_version=..., interactions_event_types=..., role_connections_verification_url=..., redirect_uris=..., rpc_origins=..., public=..., require_code_grant=..., discoverable=..., max_participants=..., flags=..., custom_install_url=..., install_params=..., developers=..., publishers=..., guild=..., team=...)¶

This function is a coroutine.

Edits the application.

All parameters are optional.

Parameters

name (str) – The name of the application.
description (str) – The description of the application.
icon (Optional[bytes]) – The icon of the application.
cover_image (Optional[bytes]) – The cover image of the application.
tags (List[str]) – A list of tags that describe the application.
terms_of_service_url (Optional[str]) – The URL to the terms of service of the application.
privacy_policy_url (Optional[str]) – The URL to the privacy policy of the application.
deeplink_uri (Optional[str]) –
The deeplink URI of the application.

New in version 2.1.
interactions_endpoint_url (Optional[str]) – The URL interactions will be sent to, if set.
interactions_version (int) –
The interactions version to use. Different versions have different payloads and supported features.

New in version 2.1.
interactions_event_types (List[str]) –
The interaction event types to subscribe to. Requires a valid interactions_endpoint_url and interactions_version 2 or higher.

New in version 2.1.
role_connections_verification_url (Optional[str]) –
The connection verification URL for the application.

New in version 2.1.
redirect_uris (List[str]) – A list of redirect URIs authorized for this application.
rpc_origins (List[str]) – A list of RPC origins authorized for this application.
public (bool) – Whether the application is public or not.
require_code_grant (bool) – Whether the application requires a code grant or not.
discoverable (bool) –
Whether the application is listed in the app directory or not.

New in version 2.1.
max_participants (Optional[int]) –
The max number of people that can participate in the activity. Only available for embedded activities.

New in version 2.1.
flags (ApplicationFlags) – The flags of the application.
developers (List[Company]) – A list of companies that are the developers of the application.
publishers (List[Company]) – A list of companies that are the publishers of the application.
guild (Guild) – The guild to transfer the application to.
team (Team) – The team to transfer the application to.

Raises

Forbidden – You do not have permissions to edit this application.
HTTPException – Editing the application failed.

await fetch_bot()¶

This function is a coroutine.

Retrieves the bot attached to this application.

Raises

Forbidden – You do not have permissions to fetch the bot, or the application does not have a bot.
HTTPException – Fetching the bot failed.

Returns

The bot attached to this application.

Return type

ApplicationBot

await create_bot()¶

This function is a coroutine.

Creates a bot attached to this application.

Changed in version 2.1: This now returns the bot token (if applicable) instead of implicitly refetching the application to return the ApplicationBot.

Raises

Forbidden – You do not have permissions to create bots.
HTTPException – Creating the bot failed.

Returns

The bot’s token. This is only returned if a bot does not already exist.

Return type

Optional[str]

await edit_bot(*, username=..., avatar=..., bio=..., public=..., require_code_grant=...)¶

This function is a coroutine.

Edits the application’s bot.

All parameters are optional.

New in version 2.1.

Parameters

username (str) – The new username you wish to change the bot to.
avatar (Optional[bytes]) – A bytes-like object representing the image to upload. Could be None to denote no avatar.
bio (Optional[str]) – The bot’s ‘about me’ section. This is just the application description. Could be None to represent no ‘about me’.
public (bool) – Whether the bot is public or not.
require_code_grant (bool) – Whether the bot requires a code grant or not.

Raises

Forbidden – You are not allowed to edit this bot.
HTTPException – Editing the bot failed.

Returns

The newly edited bot.

Return type

ApplicationBot

await whitelisted()¶

This function is a coroutine.

Retrieves the list of whitelisted users (testers) for this application.

Raises

Forbidden – You do not have permissions to fetch the testers.
HTTPException – Fetching the testers failed.

Returns

The testers for this application.

Return type

List[ApplicationTester]

await whitelist(*args)¶

This function is a coroutine.

Whitelists a user (adds a tester) for this application.

This function can be used in multiple ways.

# Passing a user object:
await app.whitelist(user)

# Passing a username
await app.whitelist('jake')

# Passing a legacy user:
await app.whitelist('Jake#0001')

# Passing a legacy username and discriminator:
await app.whitelist('Jake', '0001')

Parameters

user (Union[User, str]) – The user to whitelist.
username (str) – The username of the user to whitelist.
discriminator (str) – The discriminator of the user to whitelist.

Raises

HTTPException – Inviting the user failed.
TypeError – More than 2 parameters or less than 1 parameter were passed.

Returns

The new whitelisted user.

Return type

ApplicationTester

await create_asset(name, image, *, type=<ApplicationAssetType.one: 1>)¶

This function is a coroutine.

Uploads an asset to this application.

Parameters

name (str) – The name of the asset.
image (bytes) – The image of the asset. Cannot be animated.

Raises

Forbidden – You do not have permissions to upload assets.
HTTPException – Uploading the asset failed.

Returns

The created asset.

Return type

ApplicationAsset

await store_assets()¶

This function is a coroutine.

Retrieves the store assets for this application.

Raises

Forbidden – You do not have permissions to store assets.
HTTPException – Storing the assets failed.

Returns

The store assets retrieved.

Return type

List[StoreAsset]

await create_store_asset(file, /)¶

This function is a coroutine.

Uploads a store asset to this application.

Parameters

file (File) – The file to upload. Must be a PNG, JPG, GIF, or MP4.

Raises

Forbidden – You do not have permissions to upload assets.
HTTPException – Uploading the asset failed.

Returns

The created asset.

Return type

StoreAsset

await skus(*, with_bundled_skus=True, localize=True)¶

This function is a coroutine.

Retrieves the SKUs for this application.

Parameters

with_bundled_skus (bool) – Whether to include bundled SKUs in the response.
localize (bool) – Whether to localize the SKU name and description to the current user’s locale. If False then all localizations are returned.

Raises

Forbidden – You do not have permissions to fetch SKUs.
HTTPException – Fetching the SKUs failed.

Returns

The SKUs retrieved.

Return type

List[SKU]

await primary_sku(*, localize=True)¶

This function is a coroutine.

Retrieves the primary SKU for this application if it exists.

Parameters

localize (bool) – Whether to localize the SKU name and description to the current user’s locale. If False then all localizations are returned.

Raises

Forbidden – You do not have permissions to fetch SKUs.
HTTPException – Fetching the SKUs failed.

Returns

The primary SKU retrieved.

Return type

Optional[SKU]

await store_listing_sku(*, localize=True)¶

This function is a coroutine.

Retrieves the store listing SKU for this application if it exists.

Parameters

localize (bool) – Whether to localize the SKU name and description to the current user’s locale. If False then all localizations are returned.

Raises

Forbidden – You do not have permissions to fetch SKUs.
HTTPException – Fetching the SKUs failed.

Returns

The store listing SKU retrieved.

Return type

Optional[SKU]

await create_sku(*, name, name_localizations=None, legal_notice=None, legal_notice_localizations=None, type, price_tier=None, price_overrides=None, sale_price_tier=None, sale_price_overrides=None, dependent_sku=None, access_level=None, features=None, locales=None, genres=None, content_ratings=None, system_requirements=None, release_date=None, bundled_skus=None, manifest_labels=None)¶

This function is a coroutine.

Creates a SKU for this application.

Parameters

name (str) – The SKU’s name.
name_localizations (Optional[Mapping[Locale, str]]) – The SKU’s name localized to other languages.
legal_notice (Optional[str]) – The SKU’s legal notice.
legal_notice_localizations (Optional[Mapping[Locale, str]]) – The SKU’s legal notice localized to other languages.
type (SKUType) – The SKU’s type.
price_tier (Optional[int]) – The price tier of the SKU. This is the base price in USD that other currencies will be calculated from.
price_overrides (Optional[Mapping[str, int]]) – A mapping of currency to price. These prices override the base price tier.
sale_price_tier (Optional[int]) – The sale price tier of the SKU. This is the base sale price in USD that other currencies will be calculated from.
sale_price_overrides (Optional[Mapping[str, int]]) – A mapping of currency to sale price. These prices override the base sale price tier.
dependent_sku (Optional[int]) – The ID of the SKU that this SKU is dependent on.
access_level (Optional[SKUAccessLevel]) – The access level of the SKU.
features (Optional[List[SKUFeature]]) – A list of features of the SKU.
locales (Optional[List[Locale]]) – A list of locales supported by the SKU.
genres (Optional[List[SKUGenre]]) – A list of genres of the SKU.
content_ratings (Optional[List[ContentRating]]) – A list of content ratings of the SKU.
system_requirements (Optional[List[SystemRequirements]]) – A list of system requirements of the SKU.
release_date (Optional[datetime.date]) – The release date of the SKU.
bundled_skus (Optional[List[SKU]]) – A list SKUs that are bundled with this SKU.
manifest_labels (Optional[List[ManifestLabel]]) – A list of manifest labels for the SKU.

Raises

Forbidden – You do not have permissions to create SKUs.
HTTPException – Creating the SKU failed.

Returns

The SKU created.

Return type

SKU

await fetch_achievement(achievement_id)¶

This function is a coroutine.

Retrieves an achievement for this application.

Parameters

achievement_id (int) – The ID of the achievement to fetch.

Raises

Forbidden – You do not have permissions to fetch the achievement.
HTTPException – Fetching the achievement failed.

Returns

The achievement retrieved.

Return type

Achievement

await create_achievement(*, name, name_localizations=None, description, description_localizations=None, icon, secure=False, secret=False)¶

This function is a coroutine.

Creates an achievement for this application.

Parameters

name (str) – The name of the achievement.
name_localizations (Mapping[Locale, str]) – The localized names of the achievement.
description (str) – The description of the achievement.
description_localizations (Mapping[Locale, str]) – The localized descriptions of the achievement.
icon (bytes) – The icon of the achievement.
secure (bool) – Whether the achievement is secure.
secret (bool) – Whether the achievement is secret.

Raises

Forbidden – You do not have permissions to create achievements.
HTTPException – Creating the achievement failed.

Returns

The created achievement.

Return type

Achievement

async for ... in entitlements(*, user=None, guild=None, skus=None, limit=100, before=None, after=None, oldest_first=..., with_payments=False, exclude_ended=False)¶

Returns an asynchronous iterator that enables receiving this application’s entitlements.

Examples

Usage

counter = 0
async for entitlement in application.entitlements(limit=200, user=client.user):
    if entitlement.consumed:
        counter += 1

Flattening into a list:

entitlements = [entitlement async for entitlement in application.entitlements(limit=123)]
# entitlements is now a list of Entitlement...

All parameters are optional.

Parameters

user (Optional[User]) – The user to retrieve entitlements for.
guild (Optional[Guild]) – The guild to retrieve entitlements for.
skus (Optional[List[SKU]]) – The SKUs to retrieve entitlements for.
limit (Optional[int]) – The number of payments to retrieve. If None, retrieves every entitlement the application has. Note, however, that this would make it a slow operation.
before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve entitlements before this date or entitlement. 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 entitlements after this date or entitlement. 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.
oldest_first (bool) – If set to True, return entitlements in oldest->newest order. Defaults to True if after is specified, otherwise False.
with_payments (bool) – Whether to include partial payment info in the response.
exclude_ended (bool) – Whether to exclude entitlements that have ended.

Raises

HTTPException – The request to get payments failed.

Yields

Entitlement – The entitlement retrieved.

await fetch_entitlement(entitlement_id, /)¶

This function is a coroutine.

Retrieves an entitlement from this application.

Parameters: entitlement_id (int) – The ID of the entitlement to fetch.
Raises: HTTPException – Fetching the entitlement failed.
Returns: The entitlement retrieved.
Return type: Entitlement

await gift_batches()¶

This function is a coroutine.

Retrieves the gift batches for this application.

Raises: HTTPException – Fetching the gift batches failed.
Returns: The gift batches retrieved.
Return type: List[GiftBatch]

await create_gift_batch(sku, *, amount, description, entitlement_branches=None, entitlement_starts_at=None, entitlement_ends_at=None)¶

This function is a coroutine.

Creates a gift batch for the specified SKU.

Parameters

sku (SKU) – The SKU to create the gift batch for.
amount (int) – The amount of gifts to create in the batch.
description (str) – The description of the gift batch.
entitlement_branches (List[ApplicationBranch]) – The branches to grant in the gifts.
entitlement_starts_at (datetime.date) – When the entitlement is valid from.
entitlement_ends_at (datetime.date) – When the entitlement is valid until.

Raises

Forbidden – You do not have permissions to create a gift batch.
HTTPException – Creating the gift batch failed.

Returns

The gift batch created.

Return type

GiftBatch

await branches()¶

This function is a coroutine.

Retrieves the branches for this application.

Raises: HTTPException – Fetching the branches failed.
Returns: The branches retrieved.
Return type: List[ApplicationBranch]

await create_branch(name)¶

This function is a coroutine.

Creates a branch for this application.

Note

The first branch created will always be called master and share the same ID as the application.

Parameters: name (str) – The name of the branch.
Raises: HTTPException – Creating the branch failed.
Returns: The branch created.
Return type: ApplicationBranch

await manifest_labels()¶

This function is a coroutine.

Retrieves the manifest labels for this application.

Raises: HTTPException – Fetching the manifest labels failed.
Returns: The manifest labels retrieved.
Return type: List[ManifestLabel]

await fetch_discoverability()¶

This function is a coroutine.

Retrieves the discoverability state for this application.

Note

This method is an API call. For general usage, consider discoverability_state and discovery_eligibility_flags instead.

Raises: HTTPException – Fetching the discoverability failed.
Returns: The discoverability retrieved.
Return type: Tuple[ApplicationDiscoverabilityState, ApplicationDiscoveryFlags]

await fetch_embedded_activity_config()¶

This function is a coroutine.

Retrieves the embedded activity configuration for this application.

Note

This method is an API call. For general usage, consider PartialApplication.embedded_activity_config instead.

Raises

Forbidden – You do not have permissions to fetch the embedded activity config.
HTTPException – Fetching the embedded activity config failed.

Returns

The embedded activity config retrieved.

Return type

EmbeddedActivityConfig

await edit_embedded_activity_config(*, supported_platforms=..., platform_configs=..., orientation_lock_state=..., tablet_orientation_lock_state=..., requires_age_gate=..., shelf_rank=..., free_period_starts_at=..., free_period_ends_at=..., preview_video_asset=...)¶

This function is a coroutine.

Edits the application’s embedded activity configuration.

Parameters

supported_platforms (List[EmbeddedActivityPlatform]) – A list of platforms that the activity supports.
platform_configs (List[EmbeddedActivityPlatformConfig]) –
A list of configurations for each supported activity platform.

New in version 2.1.
orientation_lock_state (EmbeddedActivityOrientation) – The mobile orientation lock state of the activity.
tablet_orientation_lock_state (EmbeddedActivityOrientation) – The mobile orientation lock state of the activity on tablets.
requires_age_gate (bool) – Whether the activity should be blocked from underage users.
shelf_rank (int) – The sorting rank of the activity in the activity shelf.
free_period_starts_at (Optional[datetime.datetime]) – When the activity’s free availability period starts.
free_period_ends_at (Optional[datetime.datetime]) – When the activity’s free availability period ends.
preview_video_asset (Optional[ApplicationAsset]) – The preview video asset of the activity.

Raises

Forbidden – You are not allowed to edit this application’s configuration.
HTTPException – Editing the configuration failed.

Returns

The edited configuration.

Return type

EmbeddedActivityConfig

await secret()¶

This function is a coroutine.

Gets the application’s secret.

This revokes all previous secrets.

Raises

Forbidden – You do not have permissions to reset the secret.
HTTPException – Getting the secret failed.

Returns

The new secret.

Return type

await achievements(completed=True)¶

This function is a coroutine.

Retrieves the achievements for this application.

Parameters

completed (bool) –

Whether to only include achievements the user has completed or can access. This means secret achievements that are not yet unlocked will not be included.

If False, then you require access to the application.

Raises

Forbidden – You do not have permissions to fetch achievements.
HTTPException – Fetching the achievements failed.

Returns

The achievements retrieved.

Return type

List[Achievement]

await activity_statistics()¶

This function is a coroutine.

Retrieves the activity usage statistics for this application.

Raises: HTTPException – Retrieving the statistics failed.
Returns: The statistics retrieved.
Return type: List[ApplicationActivityStatistics]

await assets()¶

This function is a coroutine.

Retrieves the assets of this application.

Raises: HTTPException – Retrieving the assets failed.
Returns: The application’s assets.
Return type: List[ApplicationAsset]

property cover_image¶

Retrieves the application’s cover image, if any.

Type: Optional[Asset]

property created_at¶

Returns the application’s creation time in UTC.

New in version 2.1.

Type: datetime.datetime

await entitlement_ticket()¶

This function is a coroutine.

Retrieves the entitlement ticket for this application.

Raises: HTTPException – Retrieving the ticket failed.
Returns: The ticket retrieved.
Return type: str

await eula()¶

This function is a coroutine.

Retrieves the EULA for this application.

Raises: HTTPException – Retrieving the EULA failed.
Returns: The EULA retrieved, if any.
Return type: Optional[EULA]

property flags¶

The flags of this application.

Type: ApplicationFlags

property guild¶

The guild linked to the application, if any and available.

Type: Optional[Guild]

property icon¶

Retrieves the application’s icon asset, if any.

Type: Optional[Asset]

property install_url¶

The URL to install the application.

Type: str

is_rpc_enabled()¶: bool: Whether the application has the ability to access the client RPC server.

New in version 2.1.

property primary_sku_url¶

The URL to the primary SKU of the application, if any.

Type: str

await primary_store_listing(*, localize=True)¶

This function is a coroutine.

Retrieves the primary store listing of this application.

This is the public store listing of the primary SKU.

Parameters

localize (bool) – Whether to localize the store listing to the current user’s locale. If False then all localizations are returned.

Raises

NotFound – The application does not have a primary SKU.
HTTPException – Retrieving the store listing failed.

Returns

The application’s primary store listing, if any.

Return type

await published_store_listings(*, localize=True)¶

This function is a coroutine.

Retrieves all published store listings for this application.

Parameters: localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.
Raises: HTTPException – Retrieving the listings failed.
Returns: The store listings.
Return type: List[StoreListing]

property splash¶

Retrieves the application’s splash, if any.

New in version 2.1.

Type: Optional[Asset]

property store_listing_sku_url¶

The URL to the store listing SKU of the application, if any.

Type: str

await ticket()¶

This function is a coroutine.

Retrieves the license ticket for this application.

Raises: HTTPException – Retrieving the ticket failed.
Returns: The ticket retrieved.
Return type: str

class discord.PartialApplication¶

Represents a partial Application.

x == y: Checks if two applications are equal.

x != y: Checks if two applications are not equal.

hash(x): Return the application’s hash.

str(x): Returns the application’s name.

New in version 2.0.

id¶

The application ID.

Type: int

name¶

The application name.

Type: str

description¶

The application description.

Type: str

rpc_origins¶

A list of RPC origin URLs, if RPC is enabled.

Changed in version 2.1: The type of this attribute has changed to Optional[List[str]].

Type: Optional[List[str]]

verify_key¶

The hex encoded key for verification in interactions and the GameSDK’s https://discord.com/developers/docs/GetTicket <game-sdk/applications#getticket.

Type: str

terms_of_service_url¶

The application’s terms of service URL, if set.

Type: Optional[str]

privacy_policy_url¶

The application’s privacy policy URL, if set.

Type: Optional[str]

deeplink_uri¶

The application’s deeplink URI, if set.

New in version 2.1.

Type: Optional[str]

public¶

Whether the integration can be invited by anyone or if it is locked to the application owner.

Type: bool

require_code_grant¶

Whether the integration requires the completion of the full OAuth2 code grant flow to join

Type: bool

max_participants¶

The max number of people that can participate in the activity. Only available for embedded activities.

Type: Optional[int]

type¶

The type of application.

Type: Optional[ApplicationType]

tags¶

A list of tags that describe the application.

Type: List[str]

overlay¶

Whether the application has a Discord overlay or not.

Type: bool

guild_id¶

The ID of the guild the application is attached to, if any.

Type: Optional[int]

primary_sku_id¶

The application’s primary SKU ID, if any. This can be an application’s game SKU, subscription SKU, etc.

Type: Optional[int]

store_listing_sku_id¶

The application’s store listing SKU ID, if any. If exists, this SKU ID should be used for checks.

Type: Optional[int]

slug¶

The slug for the application’s primary SKU, if any.

Type: Optional[str]

eula_id¶

The ID of the EULA for the application, if any.

Type: Optional[int]

aliases¶

A list of aliases that can be used to identify the application.

Type: List[str]

developers¶

A list of developers that developed the application.

Type: List[Company]

publishers¶

A list of publishers that published the application.

Type: List[Company]

executables¶

A list of executables that are the application’s.

Type: List[ApplicationExecutable]

third_party_skus¶

A list of third party platforms the SKU is available at.

Type: List[ThirdPartySKU]

custom_install_url¶

The custom URL to use for authorizing the application, if specified.

Type: Optional[str]

install_params¶

The parameters to use for authorizing the application, if specified.

Type: Optional[ApplicationInstallParams]

embedded_activity_config¶

The application’s embedded activity configuration, if any.

Type: Optional[EmbeddedActivityConfig]

owner¶

The application owner. This may be a team user account.

Note

In almost all cases, this is not available for partial applications.

Type: Optional[User]

team¶

The team that owns the application.

Note

In almost all cases, this is not available.

Type: Optional[Team]

property created_at¶

Returns the application’s creation time in UTC.

New in version 2.1.

Type: datetime.datetime

property icon¶

Retrieves the application’s icon asset, if any.

Type: Optional[Asset]

property cover_image¶

Retrieves the application’s cover image, if any.

Type: Optional[Asset]

property splash¶

Retrieves the application’s splash, if any.

New in version 2.1.

Type: Optional[Asset]

property flags¶

The flags of this application.

Type: ApplicationFlags

property install_url¶

The URL to install the application.

Type: str

property primary_sku_url¶

The URL to the primary SKU of the application, if any.

Type: str

property store_listing_sku_url¶

The URL to the store listing SKU of the application, if any.

Type: str

property guild¶

The guild linked to the application, if any and available.

Type: Optional[Guild]

has_bot()¶: bool: Whether the application has an attached bot.

New in version 2.1.

is_rpc_enabled()¶: bool: Whether the application has the ability to access the client RPC server.

New in version 2.1.

await assets()¶

This function is a coroutine.

Retrieves the assets of this application.

Raises: HTTPException – Retrieving the assets failed.
Returns: The application’s assets.
Return type: List[ApplicationAsset]

await published_store_listings(*, localize=True)¶

This function is a coroutine.

Retrieves all published store listings for this application.

Parameters: localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.
Raises: HTTPException – Retrieving the listings failed.
Returns: The store listings.
Return type: List[StoreListing]

await primary_store_listing(*, localize=True)¶

This function is a coroutine.

Retrieves the primary store listing of this application.

This is the public store listing of the primary SKU.

Parameters

localize (bool) – Whether to localize the store listing to the current user’s locale. If False then all localizations are returned.

Raises

NotFound – The application does not have a primary SKU.
HTTPException – Retrieving the store listing failed.

Returns

The application’s primary store listing, if any.

Return type

await achievements(completed=True)¶

This function is a coroutine.

Retrieves the achievements for this application.

Parameters

completed (bool) –

Whether to only include achievements the user has completed or can access. This means secret achievements that are not yet unlocked will not be included.

If False, then you require access to the application.

Raises

Forbidden – You do not have permissions to fetch achievements.
HTTPException – Fetching the achievements failed.

Returns

The achievements retrieved.

Return type

List[Achievement]

await entitlements(*, exclude_consumed=True)¶

This function is a coroutine.

Retrieves the entitlements this account has granted for this application.

Parameters: exclude_consumed (bool) – Whether to exclude consumed entitlements.
Raises: HTTPException – Fetching the entitlements failed.
Returns: The entitlements retrieved.
Return type: List[Entitlement]

await eula()¶

This function is a coroutine.

Retrieves the EULA for this application.

Raises: HTTPException – Retrieving the EULA failed.
Returns: The EULA retrieved, if any.
Return type: Optional[EULA]

await ticket()¶

This function is a coroutine.

Retrieves the license ticket for this application.

Raises: HTTPException – Retrieving the ticket failed.
Returns: The ticket retrieved.
Return type: str

await entitlement_ticket()¶

This function is a coroutine.

Retrieves the entitlement ticket for this application.

Raises: HTTPException – Retrieving the ticket failed.
Returns: The ticket retrieved.
Return type: str

await activity_statistics()¶

This function is a coroutine.

Retrieves the activity usage statistics for this application.

Raises: HTTPException – Retrieving the statistics failed.
Returns: The statistics retrieved.
Return type: List[ApplicationActivityStatistics]

Attributes

created_at
custom_install_url
flags
id
install_params
install_url
popular_application_command_ids
primary_sku_id
primary_sku_url
verified

class discord.ApplicationProfile¶

Represents a Discord application profile.

x == y: Checks if two applications are equal.

x != y: Checks if two applications are not equal.

hash(x): Return the applications’s hash.

New in version 2.0.

id¶

The application’s ID.

Type: int

verified¶

Indicates if the application is verified.

Type: bool

popular_application_command_ids¶

A list of the IDs of the application’s popular commands.

Type: List[int]

primary_sku_id¶

The application’s primary SKU ID, if any. This can be an application’s game SKU, subscription SKU, etc.

Type: Optional[int]

custom_install_url¶

The custom URL to use for authorizing the application, if specified.

Type: Optional[str]

install_params¶

The parameters to use for authorizing the application, if specified.

Type: Optional[ApplicationInstallParams]

property created_at¶

Returns the application’s creation time in UTC.

New in version 2.1.

Type: datetime.datetime

property flags¶

The flags of this application.

Type: ApplicationFlags

property install_url¶

The URL to install the application.

Type: str

property primary_sku_url¶

The URL to the primary SKU of the application, if any.

Type: str

Methods

asyncack
asyncack_pins
asyncapplication_commands
asyncblock
asyncconnect
asynccreate_dm
asyncedit
asyncfetch_message
asyncfetch_mutual_friends
asyncgreet
async forhistory
defis_blocked
defis_friend
defis_pomelo
defmentioned_in
asyncpins
asyncprofile
asyncremove_friend
defsearch
asyncsend
asyncsend_friend_request
defslash_commands
asynctoken
deftyping
asyncunack
asyncunblock
asyncupload_files
defuser_commands

class discord.ApplicationBot¶

Represents a bot attached to an application.

x == y: Checks if two bots are equal.

x != y: Checks if two bots are not equal.

hash(x): Return the bot’s hash.

str(x): Returns the bot’s name with discriminator.

New in version 2.0.

application¶

The application that the bot is attached to.

Type: Application

property public¶

Whether the bot can be invited by anyone or if it is locked to the application owner.

Type: bool

property require_code_grant¶

Whether the bot requires the completion of the full OAuth2 code grant flow to join.

Type: bool

property disabled¶

Whether the bot is disabled by Discord.

New in version 2.1.

Type: bool

property quarantined¶

Whether the bot is quarantined by Discord.

Quarantined bots cannot join more guilds or start new direct messages.

New in version 2.1.

Type: bool

property bio¶

Returns the bot’s ‘about me’ section.

Type: Optional[str]

property mfa_enabled¶

Whether the bot has MFA turned on and working. This follows the bot owner’s value.

Type: bool

property verified¶

Whether the bot’s email has been verified. This follows the bot owner’s value.

Type: bool

await edit(*, username=..., avatar=..., bio=..., public=..., require_code_grant=...)¶

This function is a coroutine.

Edits the bot.

All parameters are optional.

Parameters

username (str) – The new username you wish to change the bot to.
avatar (Optional[bytes]) – A bytes-like object representing the image to upload. Could be None to denote no avatar.
bio (Optional[str]) – The bot’s ‘about me’ section. This is just the application description. Could be None to represent no ‘about me’.
public (bool) – Whether the bot is public or not.
require_code_grant (bool) – Whether the bot requires a code grant or not.

Raises

Forbidden – You are not allowed to edit this bot.
HTTPException – Editing the bot failed.

await token()¶

This function is a coroutine.

Gets the bot’s token.

This revokes all previous tokens.

Raises

Forbidden – You are not allowed to reset the token.
HTTPException – Resetting the token failed.

Returns

The new token.

Return type

property accent_color¶

Returns the user’s accent color, if applicable.

A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

There is an alias for this named accent_colour.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

property accent_colour¶

Returns the user’s accent colour, if applicable.

A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

There is an alias for this named accent_color.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

property avatar¶

Returns an Asset for the avatar the user has.

If the user has not uploaded a global avatar, None is returned. If you want the avatar that a user has displayed, consider display_avatar.

Type: Optional[Asset]

property avatar_decoration¶

Returns an Asset for the avatar decoration the user has.

If the user does not have a avatar decoration, None is returned.

New in version 2.0.

Type: Optional[Asset]

property avatar_decoration_sku_id¶

Returns the avatar decoration’s SKU ID.

If the user does not have a preset avatar decoration, None is returned.

New in version 2.1.

Type: Optional[int]

property banner¶

Returns the user’s banner asset, if available.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Asset]

await block()¶

This function is a coroutine.

Blocks the user.

Raises

Forbidden – Not allowed to block this user.
HTTPException – Blocking the user failed.

property call¶

Returns the call associated with this user if it exists.

Type: Optional[PrivateCall]

property color¶

A property that returns a color denoting the rendered color for the user. This always returns Colour.default().

There is an alias for this named colour.

Type: Colour

property colour¶

A property that returns a colour denoting the rendered colour for the user. This always returns Colour.default().

There is an alias for this named color.

Type: Colour

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await create_dm()¶

This function is a coroutine.

Creates a DMChannel with this user.

This should be rarely called, as this is done transparently for most people.

Returns: The channel that was created.
Return type: DMChannel

property created_at¶

Returns the user’s creation time in UTC.

This is when the user’s Discord account was created.

Type: datetime.datetime

property default_avatar¶

Returns the default avatar for a given user.

Type: Asset

property display_avatar¶

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

property display_banner¶

Returns the user’s banner asset, if available.

This is the same as banner and is here for compatibility.

New in version 2.0.

Type: Optional[Asset]

property display_name¶

Returns the user’s display name.

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

Type: str

property dm_channel¶

Returns the channel associated with this user if it exists.

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

Type: Optional[DMChannel]

await fetch_message(id, /)¶

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

await fetch_mutual_friends()¶

This function is a coroutine.

Fetches mutual friends with the user.

New in version 2.1.

Raises: HTTPException – Fetching the mutual friends failed.
Returns: The mutual friends with the user.
Return type: List[User]

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

is_blocked()¶: bool: Checks if the user is blocked.

is_friend()¶: bool: Checks if the user is your friend.

is_pomelo()¶: bool: Checks if the user has migrated to Discord’s new unique username system

New in version 2.1.

property mention¶

Returns a string that allows you to mention the given user.

Type: str

mentioned_in(message)¶

Checks if the user is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the user is mentioned in the message.
Return type: bool

note¶

Returns an object representing the user’s note.

New in version 2.0.

Note

The underlying note is cached and updated from gateway events.

Type: Note

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

property premium¶: Indicates if the user is a premium user (i.e. has Discord Nitro).

await profile(*, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

A shorthand method to retrieve a UserProfile for the user.

Parameters

with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in UserProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in UserProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in UserProfile.mutual_friends and UserProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

Forbidden – Not allowed to fetch this profile.
HTTPException – Fetching the profile failed.

Returns

The profile of the user.

Return type

property public_flags¶

The publicly available flags the user has.

Type: PublicUserFlags

property relationship¶

Returns the Relationship with this user if applicable, None otherwise.

Type: Optional[Relationship]

await remove_friend()¶

This function is a coroutine.

Removes the user as a friend.

Raises

Forbidden – Not allowed to remove this user as a friend.
HTTPException – Removing the user as a friend failed.

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await send_friend_request()¶

This function is a coroutine.

Sends the user a friend request.

Raises

Forbidden – Not allowed to send a friend request to the user.
HTTPException – Sending the friend request failed.

slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await unblock()¶

This function is a coroutine.

Unblocks the user.

Raises

Forbidden – Not allowed to unblock this user.
HTTPException – Unblocking the user failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property voice¶

Returns the user’s current voice state.

Type: Optional[VoiceState]

Attributes

application
launcher
name
os

class discord.ApplicationExecutable¶

Represents an application executable.

str(x): Returns the executable’s name.

New in version 2.0.

name¶

The name of the executable.

Type: str

os¶

The operating system the executable is for.

Changed in version 2.1: The type of this attribute has changed to OperatingSystem.

Type: OperatingSystem

launcher¶

Whether the executable is a launcher or not.

Type: bool

application¶

The application that the executable is for.

Type: PartialApplication

Attributes

application_id
permissions
scopes
url

class discord.ApplicationInstallParams¶

Represents an application’s authorization parameters.

str(x): Returns the authorization URL.

New in version 2.0.

application_id¶

The ID of the application to be authorized.

Type: int

scopes¶

The list of OAuth2 scopes to add the application with.

Type: List[str]

permissions¶

The permissions to grant to the added bot.

Type: Permissions

property url¶

The URL to add the application with the parameters.

Type: str

Attributes

animated
application
id
name
url

Methods

asyncdelete

class discord.ApplicationAsset¶

Represents an application asset.

x == y: Checks if two assets are equal.

x != y: Checks if two assets are not equal.

hash(x): Return the asset’s hash.

str(x): Returns the asset’s name.

New in version 2.0.

application¶

The application that the asset is for.

Type: Union[PartialApplication, IntegrationApplication]

id¶

The asset’s ID.

Type: int

name¶

The asset’s name.

Type: str

property animated¶

Indicates if the asset is animated. Here for compatibility purposes.

Type: bool

property url¶

Returns the URL of the asset.

Type: str

await delete()¶

This function is a coroutine.

Deletes the asset.

Raises

Forbidden – You are not allowed to delete this asset.
HTTPException – Deleting the asset failed.

Attributes

application_id
duration
sku_duration
updated_at
user
user_id

Methods

asyncapplication

class discord.ApplicationActivityStatistics¶

Represents an application’s activity usage statistics for a particular user.

New in version 2.0.

application_id¶

The ID of the application.

Type: int

user_id¶

The ID of the user.

Type: int

duration¶

How long the user has ever played the game in seconds.

Type: int

sku_duration¶

How long the user has ever played the game on Discord in seconds.

Type: int

updated_at¶

When the user last played the game.

Type: datetime.datetime

property user¶

Returns the user associated with the statistics, if available.

Type: Optional[User]

await application()¶

This function is a coroutine.

Returns the application associated with the statistics.

Raises: HTTPException – Fetching the application failed.

Attributes

application
state

Methods

asyncremove

class discord.ApplicationTester¶

Represents a user whitelisted for an application.

x == y: Checks if two testers are equal.

x != y: Checks if two testers are not equal.

hash(x): Return the tester’s hash.

str(x): Returns the tester’s name with discriminator.

New in version 2.0.

application¶

The application the tester is whitelisted for.

Type: Application

state¶

The state of the tester (i.e. invited or accepted)

Type: ApplicationMembershipState

await remove()¶

This function is a coroutine.

Removes the user from the whitelist.

Raises: HTTPException – Removing the user failed.

Attributes

application
free_period_ends_at
free_period_starts_at
orientation_lock_state
platform_configs
premium_tier_requirement
preview_video_asset
requires_age_gate
shelf_rank
supported_platforms
tablet_orientation_lock_state

Methods

asyncedit

class discord.EmbeddedActivityConfig¶

Represents an application’s embedded activity configuration.

New in version 2.0.

application¶

The application that the configuration is for.

Type: PartialApplication

supported_platforms¶

A list of platforms that the activity supports.

Type: List[EmbeddedActivityPlatform]

platform_configs¶

A list of configurations for each supported activity platform.

New in version 2.1.

Type: List[EmbeddedActivityPlatformConfig]

orientation_lock_state¶

The mobile orientation lock state of the activity.

Type: EmbeddedActivityOrientation

tablet_orientation_lock_state¶

The mobile orientation lock state of the activity on tablets.

Type: EmbeddedActivityOrientation

premium_tier_requirement¶

The guild premium tier required to use the activity.

Type: int

requires_age_gate¶

Whether the activity should be blocked from underage users.

Type: bool

shelf_rank¶

The sorting rank of the activity in the activity shelf.

Type: int

free_period_starts_at¶

When the activity’s free availability period starts.

Type: Optional[datetime.datetime]

free_period_ends_at¶

When the activity’s free availability period ends.

Type: Optional[datetime.datetime]

property preview_video_asset¶

The preview video asset of the activity, if available.

Type: Optional[ApplicationAsset]

await edit(*, supported_platforms=..., platform_configs=..., orientation_lock_state=..., tablet_orientation_lock_state=..., requires_age_gate=..., shelf_rank=..., free_period_starts_at=..., free_period_ends_at=..., preview_video_asset=...)¶

This function is a coroutine.

Edits the application’s embedded activity configuration.

Parameters

supported_platforms (List[EmbeddedActivityPlatform]) – A list of platforms that the activity supports.
platform_configs (List[EmbeddedActivityPlatformConfig]) –
A list of configurations for each supported activity platform.

New in version 2.1.
orientation_lock_state (EmbeddedActivityOrientation) – The mobile orientation lock state of the activity.
tablet_orientation_lock_state (EmbeddedActivityOrientation) – The mobile orientation lock state of the activity on tablets.
requires_age_gate (bool) – Whether the activity should be blocked from underage users.
shelf_rank (int) – The sorting rank of the activity in the activity shelf.
free_period_starts_at (Optional[datetime.datetime]) – When the activity’s free availability period starts.
free_period_ends_at (Optional[datetime.datetime]) – When the activity’s free availability period ends.
preview_video_asset (Optional[ApplicationAsset]) – The preview video asset of the activity.

Raises

Forbidden – You are not allowed to edit this application’s configuration.
HTTPException – Editing the configuration failed.

Attributes

label_type
label_until
platform
release_phase

class discord.EmbeddedActivityPlatformConfig¶

Represents an application’s embedded activity configuration for a specific platform.

New in version 2.1.

platform¶

The platform that the configuration is for.

Type: EmbeddedActivityPlatform

label_type¶

The current label shown on the activity.

Type: EmbeddedActivityLabelType

label_until¶

When the current label expires.

Type: Optional[datetime.datetime]

release_phase¶

The current release phase of the activity.

Type: EmbeddedActivityReleasePhase

Attributes

hash
missing_data
name

class discord.UnverifiedApplication¶

Represents an unverified application (a game not detected by the Discord client) that has been reported to Discord.

x == y: Checks if two applications are equal.

x != y: Checks if two applications are not equal.

hash(x): Return the application’s hash.

str(x): Returns the application’s name.

New in version 2.1.

name¶

The name of the application.

Type: str

hash¶

The hash of the application.

Type: str

missing_data¶

Data missing from the unverified application report.

Note

Client.report_unverified_application() will automatically upload the unverified application’s icon, if missing.

Type: List[str]

ApplicationBranch¶

Attributes

application_id
created_at
id
live_build_id
name

Methods

asyncbuilds
asynccreate_build
asyncdelete
asyncfetch_build
asyncfetch_live_build_id
defis_master
asynclatest_build
asynclive_build
asyncpromote

class discord.ApplicationBranch¶

Represents an application branch.

x == y: Checks if two branches are equal.

x != y: Checks if two branches are not equal.

hash(x): Return the branch’s hash.

str(x): Returns the branch’s name.

New in version 2.0.

id¶

The branch ID.

Type: int

application_id¶

The ID of the application the branch belongs to.

Type: int

live_build_id¶

The ID of the live build, if it exists and is provided.

Type: Optional[int]

name¶

The branch name, if known.

Type: str

property created_at¶

Returns the branch’s creation time in UTC.

Note

This may be inaccurate for the master branch if the data is not provided, as the ID is shared with the application ID.

Type: datetime.datetime

is_master()¶: bool: Indicates if this is the master branch.

await builds()¶

This function is a coroutine.

Retrieves the builds of the branch.

Raises

Forbidden – You are not allowed to manage this application.
HTTPException – Fetching the builds failed.

await fetch_build(build_id, /)¶

This function is a coroutine.

Retrieves a build of the branch with the given ID.

Parameters

build_id (int) – The ID of the build to fetch.

Raises

NotFound – The build does not exist.
Forbidden – You are not allowed to manage this application.
HTTPException – Fetching the build failed.

await fetch_live_build_id()¶

This function is a coroutine.

Retrieves and caches the ID of the live build of the branch.

Raises: HTTPException – Fetching the build failed.
Returns: The ID of the live build, if it exists.
Return type: Optional[int]

await live_build(*, locale=..., platform)¶

This function is a coroutine.

Retrieves the live build of the branch.

Parameters

locale (Locale) – The locale to fetch the build for. Defaults to the current user locale.
platform (str) – The platform to fetch the build for. Usually one of win32, win64, macos, or linux.

Raises

NotFound – The branch does not have a live build.
HTTPException – Fetching the build failed.

await latest_build()¶

This function is a coroutine.

Retrieves the latest successful build of the branch.

Raises

NotFound – The branch does not have a successful build.
Forbidden – You are not allowed to manage this application.
HTTPException – Fetching the build failed.

await create_build(*, built_with='DISPATCH', manifests, source_build=None)¶

This function is a coroutine.

Creates a build for the branch.

Parameters

manifests (List[Mapping[str, Any]]) – A list of dict-like objects representing the manifests.
source_build (Optional[ApplicationBuild]) – The source build of the build, if any.

Raises

Forbidden – You are not allowed to manage this application.
HTTPException – Creating the build failed.

Returns

The created build and manifest uploads.

Return type

Tuple[ApplicationBuild, List[Manifest]]

await promote(branch, /)¶

This function is a coroutine.

Promotes this branch’s live build to the given branch.

Parameters

branch (ApplicationBranch) – The target branch to promote the build to.

Raises

Forbidden – You are not allowed to manage this application.
HTTPException – Promoting the branch failed.

await delete()¶

This function is a coroutine.

Deletes the branch.

Raises

Forbidden – You are not allowed to manage this application.
HTTPException – Deleting the branch failed.

Attributes

application_id
branch
created_at
id
source_build_id
status
version

Methods

asyncdelete
asyncdownload_urls
asyncedit
asyncpublish
asyncsize
asyncupload_files

class discord.ApplicationBuild¶

Represents a build of an ApplicationBranch.

x == y: Checks if two builds are equal.

x != y: Checks if two builds are not equal.

hash(x): Return the build’s hash.

New in version 2.0.

id¶

The build ID.

Type: int

application_id¶

The ID of the application the build belongs to.

Type: int

branch¶

The branch the build belongs to.

Type: ApplicationBranch

created_at¶

When the build was created.

Type: datetime.datetime

status¶

The status of the build.

Type: ApplicationBuildStatus

source_build_id¶

The ID of the source build, if any.

Type: Optional[int]

version¶

The version of the build, if any.

Type: Optional[str]

await size(manifests=...)¶

This function is a coroutine.

Retrieves the storage space used by the build.

Parameters: manifests (List[Manifest]) – The manifests to fetch the storage space for. Defaults to all the build’s manifests.
Raises: HTTPException – Fetching the storage space failed.
Returns: The storage space used by the build in kilobytes.
Return type: float

await download_urls(manifest_labels=...)¶

This function is a coroutine.

Retrieves the download URLs of the build.

These download URLs are for the manifest metadata, which can be used to download the artifacts.

Note

The download URLs are signed and valid for roughly 7 days.

Parameters

manifest_labels (List[ManifestLabel]) – The manifest labels to fetch the download URLs for. Defaults to all the build’s manifest labels.

Raises

NotFound – The build was not found or you are not entitled to it.
Forbidden – You are not allowed to manage this application.
HTTPException – Fetching the download URLs failed.

Returns

The download URLs of the build.

Return type

List[str]

await edit(status)¶

This function is a coroutine.

Edits the build.

Parameters

status (ApplicationBuildStatus) – The new status of the build.

Raises

Forbidden – You are not allowed to manage this application.
HTTPException – Editing the build failed.

await upload_files(*files, hash=True)¶

This function is a coroutine.

Uploads files to the build.

Note

This should only be used for builds with a status of ApplicationBuildStatus.uploading.

Warning

This does not account for chunking large files.

Parameters

*files (discord.File) – The files to upload.
hash (bool) – Whether to calculate the MD5 hash of the files before upload.

Raises

Forbidden – You are not allowed to manage this application.
HTTPException – Uploading the files failed.

await publish()¶

This function is a coroutine.

Publishes the build.

This can only be done on builds with an status of ApplicationBuildStatus.ready.

Raises

Forbidden – You are not allowed to manage this application.
HTTPException – Publishing the build failed.

await delete()¶

This function is a coroutine.

Deletes the build.

Raises

Forbidden – You are not allowed to manage this application.
HTTPException – Deleting the build failed.

Attributes

application_id
id
name

class discord.ManifestLabel¶

Represents an application manifest label.

x == y: Checks if two manifest labels are equal.

x != y: Checks if two manifest labels are not equal.

hash(x): Return the manifest label’s hash.

str(x): Returns the manifest label’s name.

New in version 2.0.

id¶

The ID of the label.

Type: int

application_id¶

The ID of the application the label is for.

Type: int

name¶

The name of the label.

Type: str

Attributes

application_id
id
label
label_id
redistributable_label_ids
url

Methods

asyncupload

class discord.Manifest¶

Represents an application manifest.

x == y: Checks if two manifests are equal.

x != y: Checks if two manifests are not equal.

hash(x): Return the manifest’s hash.

New in version 2.0.

id¶

The ID of the manifest.

Type: int

application_id¶

The ID of the application the manifest is for.

Type: int

label_id¶

The ID of the manifest’s label.

Type: int

label¶

The manifest’s label, if available.

Type: Optional[ManifestLabel]

redistributable_label_ids¶

The label IDs of the manifest’s redistributables, if available.

Type: List[int]

url¶

The URL of the manifest.

Type: Optional[str]

await upload(manifest, /)¶

This function is a coroutine.

Uploads the manifest object to the manifest.

Note

This should only be used for builds with a status of ApplicationBuildStatus.uploading.

Additionally, it requires that url is set to the uploadable URL (populated on uploadable manifest objects returned from ApplicationBranch.create_build()).

Parameters

manifest (Mapping[str, Any]) – A dict-like object representing the manifest to upload.

Raises

ValueError – Upload URL is not set.
Forbidden – Upload URL invalid.
HTTPException – Uploading the manifest failed.

Team¶

Attributes

default_icon
display_icon
icon
id
members
name
owner
owner_id
payout_account_status
stripe_connect_account_id

Methods

asyncapplications
asynccreate_company
asyncdelete
asyncedit
asyncfetch_members
asyncinvite_member
asyncleave
async forpayouts

class discord.Team¶

Represents an application team.

x == y: Checks if two teams are equal.

x != y: Checks if two teams are not equal.

hash(x): Return the team’s hash.

str(x): Returns the team’s name.

New in version 2.0.

id¶

The team ID.

Type: int

name¶

The team name.

Type: str

owner_id¶

The team’s owner ID.

Type: int

members¶

The team’s members.

Note

In almost all cases, a call to fetch_members() is required to populate this list past (sometimes) the owner.

Type: List[TeamMember]

payout_account_status¶

The team’s payout account status, if any and available.

Type: Optional[PayoutAccountStatus]

stripe_connect_account_id¶

The account ID representing the Stripe Connect account the team’s payout account is linked to, if any and available.

Type: Optional[str]

property icon¶

Retrieves the team’s icon asset, if any.

Type: Optional[Asset]

property default_icon¶

Returns the default icon for the team. This is calculated by the team’s ID.

Type: Asset

property display_icon¶

Returns the team’s display icon.

For regular teams this is just their default icon or uploaded icon.

Type: Asset

property owner¶

The team’s owner, if available.

Type: Optional[TeamMember]

await edit(*, name=..., icon=..., owner=...)¶

This function is a coroutine.

Edits the team.

All parameters are optional.

Parameters

name (str) – The name of the team.
icon (Optional[bytes]) – The icon of the team.
owner (User) – The team’s owner.

Raises

Forbidden – You do not have permissions to edit the team.
HTTPException – Editing the team failed.

await applications()¶

This function is a coroutine.

Retrieves the team’s applications.

Returns

The team’s applications.

Return type

List[TeamMember]

Raises

Forbidden – You do not have permissions to fetch the team’s applications.
HTTPException – Retrieving the team applications failed.

await fetch_members()¶

This function is a coroutine.

Retrieves and caches the team’s members.

Returns

The team’s members.

Return type

List[TeamMember]

Raises

Forbidden – You do not have permissions to fetch the team’s members.
HTTPException – Retrieving the team members failed.

await invite_member(*args)¶

This function is a coroutine.

Invites a member to the team.

This function can be used in multiple ways.

# Passing a user object:
await team.invite_member(user)

# Passing a username
await team.invite_member('jake')

# Passing a legacy user:
await team.invite_member('Jake#0001')

# Passing a legacy username and discriminator:
await team.invite_member('Jake', '0001')

Parameters

user (Union[User, str]) – The user to invite.
username (str) – The username of the user to invite.
discriminator (str) – The discriminator of the user to invite.

Raises

Forbidden – You do not have permissions to invite the user.
HTTPException – Inviting the user failed.
TypeError – More than 2 parameters or less than 1 parameter were passed.

Returns

The new member.

Return type

TeamMember

await create_company(name, /)¶

This function is a coroutine.

Creates a company for the team.

Parameters

name (str) – The name of the company.

Raises

Forbidden – You do not have permissions to create a company.
HTTPException – Creating the company failed.

Returns

The created company.

Return type

Company

async for ... in payouts(*, limit=96, before=None)¶

Returns an asynchronous iterator that enables receiving your team payouts.

New in version 2.0.

Examples

Usage

total = 0
async for payout in team.payouts():
    if payout.period_end:
        total += payout.amount

Flattening into a list:

payments = [payout async for payout in team.payouts(limit=123)]
# payments is now a list of TeamPayout...

All parameters are optional.

Parameters

limit (Optional[int]) – The number of payouts to retrieve. If None, retrieves every payout you have. Note, however, that this would make it a slow operation.
before (Optional[Union[Snowflake, datetime.datetime]]) – Retrieve payments before this date or payout. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time.

Raises

HTTPException – The request to get team payouts failed.

Yields

TeamPayout – The payout received.

await leave()¶

This function is a coroutine.

Leaves the team.

Note

You cannot leave a team that you own, you must delete it instead via delete().

Raises

Forbidden – You do not have permissions to leave the team.
HTTPException – Leaving the team failed.

await delete()¶

This function is a coroutine.

Deletes the team.

Raises

Forbidden – You do not have permissions to delete the team.
HTTPException – Deleting the team failed.

Methods

asyncack
asyncack_pins
asyncapplication_commands
asyncblock
asyncconnect
asynccreate_dm
asyncfetch_message
asyncfetch_mutual_friends
asyncgreet
async forhistory
defis_blocked
defis_friend
defis_pomelo
defmentioned_in
asyncpins
asyncprofile
asyncremove
asyncremove_friend
defsearch
asyncsend
asyncsend_friend_request
defslash_commands
deftyping
asyncunack
asyncunblock
asyncupload_files
defuser_commands

class discord.TeamMember¶

Represents a team member in a team.

x == y: Checks if two team members are equal.

x != y: Checks if two team members are not equal.

hash(x): Return the team member’s hash.

str(x): Returns the team member’s handle (e.g. name or name#discriminator).

New in version 1.3.

team¶

The team that the member is from.

Type: Team

membership_state¶

The membership state of the member (i.e. invited or accepted)

Type: ApplicationMembershipState

permissions¶

The permissions of the team member. This is always “*”.

Type: List[str]

await remove()¶

This function is a coroutine.

Removes the member from the team.

Raises

Forbidden – You do not have permissions to remove the member.
HTTPException – Removing the member failed.

property accent_color¶

Returns the user’s accent color, if applicable.

A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

There is an alias for this named accent_colour.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

property accent_colour¶

Returns the user’s accent colour, if applicable.

A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

There is an alias for this named accent_color.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

property avatar¶

Returns an Asset for the avatar the user has.

If the user has not uploaded a global avatar, None is returned. If you want the avatar that a user has displayed, consider display_avatar.

Type: Optional[Asset]

property avatar_decoration¶

Returns an Asset for the avatar decoration the user has.

If the user does not have a avatar decoration, None is returned.

New in version 2.0.

Type: Optional[Asset]

property avatar_decoration_sku_id¶

Returns the avatar decoration’s SKU ID.

If the user does not have a preset avatar decoration, None is returned.

New in version 2.1.

Type: Optional[int]

property banner¶

Returns the user’s banner asset, if available.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Asset]

await block()¶

This function is a coroutine.

Blocks the user.

Raises

Forbidden – Not allowed to block this user.
HTTPException – Blocking the user failed.

property call¶

Returns the call associated with this user if it exists.

Type: Optional[PrivateCall]

property color¶

A property that returns a color denoting the rendered color for the user. This always returns Colour.default().

There is an alias for this named colour.

Type: Colour

property colour¶

A property that returns a colour denoting the rendered colour for the user. This always returns Colour.default().

There is an alias for this named color.

Type: Colour

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await create_dm()¶

This function is a coroutine.

Creates a DMChannel with this user.

This should be rarely called, as this is done transparently for most people.

Returns: The channel that was created.
Return type: DMChannel

property created_at¶

Returns the user’s creation time in UTC.

This is when the user’s Discord account was created.

Type: datetime.datetime

property default_avatar¶

Returns the default avatar for a given user.

Type: Asset

property display_avatar¶

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

property display_banner¶

Returns the user’s banner asset, if available.

This is the same as banner and is here for compatibility.

New in version 2.0.

Type: Optional[Asset]

property display_name¶

Returns the user’s display name.

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

Type: str

property dm_channel¶

Returns the channel associated with this user if it exists.

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

Type: Optional[DMChannel]

await fetch_message(id, /)¶

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

await fetch_mutual_friends()¶

This function is a coroutine.

Fetches mutual friends with the user.

New in version 2.1.

Raises: HTTPException – Fetching the mutual friends failed.
Returns: The mutual friends with the user.
Return type: List[User]

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

is_blocked()¶: bool: Checks if the user is blocked.

is_friend()¶: bool: Checks if the user is your friend.

is_pomelo()¶: bool: Checks if the user has migrated to Discord’s new unique username system

New in version 2.1.

property mention¶

Returns a string that allows you to mention the given user.

Type: str

mentioned_in(message)¶

Checks if the user is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the user is mentioned in the message.
Return type: bool

note¶

Returns an object representing the user’s note.

New in version 2.0.

Note

The underlying note is cached and updated from gateway events.

Type: Note

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

property premium¶: Indicates if the user is a premium user (i.e. has Discord Nitro).

await profile(*, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

A shorthand method to retrieve a UserProfile for the user.

Parameters

with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in UserProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in UserProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in UserProfile.mutual_friends and UserProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

Forbidden – Not allowed to fetch this profile.
HTTPException – Fetching the profile failed.

Returns

The profile of the user.

Return type

property public_flags¶

The publicly available flags the user has.

Type: PublicUserFlags

property relationship¶

Returns the Relationship with this user if applicable, None otherwise.

Type: Optional[Relationship]

await remove_friend()¶

This function is a coroutine.

Removes the user as a friend.

Raises

Forbidden – Not allowed to remove this user as a friend.
HTTPException – Removing the user as a friend failed.

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await send_friend_request()¶

This function is a coroutine.

Sends the user a friend request.

Raises

Forbidden – Not allowed to send a friend request to the user.
HTTPException – Sending the friend request failed.

slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await unblock()¶

This function is a coroutine.

Unblocks the user.

Raises

Forbidden – Not allowed to unblock this user.
HTTPException – Unblocking the user failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property voice¶

Returns the user’s current voice state.

Type: Optional[VoiceState]

Attributes

amount
id
payout_date
period_end
period_start
status
tipalti_submission_response
user_id

Methods

asyncreport

class discord.TeamPayout¶

Represents a team payout.

x == y: Checks if two team payouts are equal.

x != y: Checks if two team payouts are not equal.

hash(x): Return the team payout’s hash.

New in version 2.0.

id¶

The ID of the payout.

Type: int

user_id¶

The ID of the user who is to be receiving the payout.

Type: int

status¶

The status of the payout.

Type: PayoutStatus

amount¶

The amount of the payout.

Type: int

period_start¶

The start of the payout period.

Type: datetime.date

period_end¶

The end of the payout period, if ended.

Type: Optional[datetime.date]

payout_date¶

The date the payout was made, if made.

Type: Optional[datetime.date]

tipalti_submission_response¶

The latest response from Tipalti, if exists.

Type: Optional[Metadata]

await report(type)¶

This function is a coroutine.

Returns the report for the payout in CSV format.

Parameters

type (PayoutReportType) – The type of report to get the URL for.

Raises

Forbidden – You do not have permissions to get the report URL.
HTTPException – Getting the report URL failed.

Returns

The report content.

Return type

Attributes

id
name

class discord.Company¶

Represents a Discord company. This is usually the developer or publisher of an application.

x == y: Checks if two companies are equal.

x != y: Checks if two companies are not equal.

hash(x): Return the company’s hash.

str(x): Returns the company’s name.

New in version 2.0.

id¶

The company’s ID.

Type: int

name¶

The company’s name.

Type: str

Attributes

content
id
name

class discord.EULA¶

Represents the EULA for an application.

This is usually found on applications that are a game.

x == y: Checks if two EULAs are equal.

x != y: Checks if two EULAs are not equal.

hash(x): Returns the EULA’s hash.

str(x): Returns the EULA’s name.

New in version 2.0.

id¶

The EULA’s ID.

Type: int

name¶

The EULA’s name.

Type: str

content¶

The EULA’s content.

Type: str

Entitlement¶

Methods

asyncconsume
asyncdelete
defis_active
defis_giftable
asyncsubscription

class discord.Entitlement¶

Represents a Discord entitlement.

x == y: Checks if two entitlements are equal.

x != y: Checks if two entitlements are not equal.

hash(x): Returns the entitlement’s hash.

bool(x): Checks if the entitlement is active.

New in version 2.0.

id¶

The ID of the entitlement.

Type: int

type¶

The type of entitlement.

Type: EntitlementType

user_id¶

The ID of the user the entitlement is for.

Type: int

sku_id¶

The ID of the SKU the entitlement grants.

Type: int

application_id¶

The ID of the application that owns the SKU the entitlement grants.

Type: int

promotion_id¶

The ID of the promotion the entitlement is from.

Type: Optional[int]

parent_id¶

The ID of the entitlement’s parent.

Type: Optional[int]

guild_id¶

The ID of the guild the entitlement is for.

Type: Optional[int]

branches¶

The IDs of the branches the entitlement grants.

Type: List[int]

gifter_id¶

The ID of the user that gifted the entitlement.

Type: Optional[int]

gift_style¶

The style of the gift attached to this entitlement.

Type: Optional[GiftStyle]

gift_batch_id¶

The ID of the batch the gift attached to this entitlement is from.

Type: Optional[int]

deleted¶

Whether the entitlement is deleted.

Type: bool

consumed¶

Whether the entitlement is consumed.

Type: bool

starts_at¶

When the entitlement period starts.

Type: Optional[datetime.datetime]

ends_at¶

When the entitlement period ends.

Type: Optional[datetime.datetime]

subscription_id¶

The ID of the subscription the entitlement is from.

Type: Optional[int]

subscription_plan¶

The subscription plan the entitlement is for.

Note

This is a partial object without price information.

Type: Optional[SubscriptionPlan]

sku¶

The SKU the entitlement grants.

Type: Optional[SKU]

payment¶

The payment made for the entitlement. Not available in some contexts.

Type: Optional[EntitlementPayment]

property guild¶

Returns the guild the entitlement is for, if accessible.

Type: Guild

property premium_type¶

The premium type this entitlement grants, if it is for a premium subscription.

Type: Optional[PremiumType]

property gift_flags¶

Returns the flags for the gift this entitlement is attached to.

Type: GiftFlags

is_giftable()¶: bool: Whether the entitlement is giftable.

is_active()¶: bool: Whether the entitlement is active and offering perks.

await subscription()¶

This function is a coroutine.

Retrieves the subscription this entitlement is attached to, if applicable.

Raises

NotFound – You cannot access this subscription.
HTTPException – Fetching the subscription failed.

Returns

The retrieved subscription, if applicable.

Return type

Optional[Subscription]

await consume()¶

This function is a coroutine.

Consumes the entitlement. This marks a given user entitlement as expended, and removes the entitlement from the user’s active entitlements.

This should be called after the user has received the relevant item, and only works on entitlements for SKUs of type SKUType.consumable.

Raises

Forbidden – You do not have permissions to access this application.
HTTPException – Consuming the entitlement failed.

await delete()¶

This function is a coroutine.

Deletes the entitlement. This removes the entitlement from the user’s entitlements, and is irreversible.

This is only useable on entitlements of type EntitlementType.test_mode_purchase.

Raises

Forbidden – You do not have permissions to access this application.
HTTPException – Deleting the entitlement failed.

Attributes

amount
currency
entitlement
id
tax
tax_inclusive

class discord.EntitlementPayment¶

Represents a partial payment for an entitlement.

x == y: Checks if two payments are equal.

x != y: Checks if two payments are not equal.

hash(x): Returns the payment’s hash.

New in version 2.0.

entitlement¶

The entitlement the payment is for.

Type: Entitlement

id¶

The ID of the payment.

Type: int

amount¶

The amount of the payment.

Type: int

tax¶

The amount of tax paid.

Type: int

tax_inclusive¶

Whether the amount is inclusive of all taxes.

Type: bool

currency¶

The currency the payment was made in.

Type: str

class discord.Gift¶

Represents a Discord gift.

x == y: Checks if two gifts are equal.

x != y: Checks if two gifts are not equal.

hash(x): Returns the gift’s hash.

New in version 2.0.

code¶

The gift’s code.

Type: str

expires_at¶

When the gift expires.

Type: Optional[datetime.datetime]

application_id¶

The ID of the application that owns the SKU the gift is for. Not available in all contexts.

Type: Optional[int]

batch_id¶

The ID of the batch the gift is from.

Type: Optional[int]

sku_id¶

The ID of the SKU the gift is for.

Type: int

entitlement_branches¶

A list of entitlements the gift is for.

Type: List[int]

gift_style¶

The style of the gift.

Type: Optional[GiftStyle]

max_uses¶

The maximum number of times the gift can be used.

Type: int

uses¶

The number of times the gift has been used.

Type: int

redeemed¶

Whether the user has redeemed the gift.

Type: bool

revoked¶

Whether the gift has been revoked.

Type: bool

guild_id¶

The ID of the guild the gift was redeemed in. Not available in all contexts.

Type: Optional[int]

channel_id¶

The ID of the channel the gift was redeemed in. Not available in all contexts.

Type: Optional[int]

store_listing¶

The store listing for the SKU the gift is for. Not available in all contexts.

Type: Optional[StoreListing]

promotion¶

The promotion the gift is a part of, if any.

Type: Optional[Promotion]

subscription_trial¶

The subscription trial the gift is a part of, if any.

Type: Optional[SubscriptionTrial]

subscription_plan_id¶

The ID of the subscription plan the gift is for, if any.

Type: Optional[int]

subscription_plan¶

The subscription plan the gift is for, if any.

Type: Optional[SubscriptionPlan]

user¶

The user who created the gift, if applicable.

Type: Optional[User]

property id¶

Returns the code portion of the gift.

Type: str

property url¶

Returns the gift’s URL.

Type: str

property remaining_uses¶

Returns the number of remaining uses for the gift.

Type: int

property flags¶

Returns the gift’s flags.

Type: GiftFlags

property premium_type¶

The premium type this gift grants, if it is for a premium subscription.

Type: Optional[PremiumType]

is_claimed()¶: bool: Checks if the gift has been used up.

is_expired()¶: bool: Checks if the gift has expired.

is_subscription()¶: bool: Checks if the gift is for a subscription.

is_premium_subscription()¶: bool: Checks if the gift is for a premium subscription.

await redeem(payment_source=None, *, channel=None, gateway_checkout_context=None)¶

This function is a coroutine.

Redeems the gift.

Parameters

payment_source (Optional[PaymentSource]) – The payment source to use for the redemption. Only required if the gift’s flags have GiftFlags.payment_source_required set to True.
channel (Optional[Union[TextChannel, VoiceChannel, StageChannel, Thread, DMChannel, GroupChannel]]) – The channel to redeem the gift in. This is usually the channel the gift was sent in. While this is optional, it is recommended to pass this in.
gateway_checkout_context (Optional[str]) – The current checkout context.

Raises

HTTPException – The gift failed to redeem.

Returns

The entitlement that was created from redeeming the gift.

Return type

Entitlement

await delete()¶

This function is a coroutine.

Revokes the gift.

This is only possible for gifts the current account has created.

Raises

NotFound – The owned gift was not found.
HTTPException – The gift failed to delete.

Attributes

amount
application_id
description
entitlement_branches
entitlement_ends_at
entitlement_starts_at
id
sku_id

Methods

asyncdownload
defis_valid

class discord.GiftBatch¶

Represents a batch of gifts for an SKU.

x == y: Checks if two gift batches are equal.

x != y: Checks if two gift batches are not equal.

hash(x): Returns the gift batch’s hash.

str(x): Returns the gift batch’s description.

New in version 2.0.

id¶

The ID of the gift batch.

Type: int

application_id¶

The ID of the application the gift batch is for.

Type: int

sku_id¶

The ID of the SKU the gift batch is for.

Type: int

amount¶

The amount of gifts in the batch.

Type: int

description¶

The description of the gift batch.

Type: str

entitlement_branches¶

The entitlement branches the gift batch is for.

Type: List[int]

entitlement_starts_at¶

When the entitlement is valid from.

Type: Optional[datetime.datetime]

entitlement_ends_at¶

When the entitlement is valid until.

Type: Optional[datetime.datetime]

is_valid()¶: bool: Checks if the gift batch is valid.

await download()¶

This function is a coroutine.

Returns the gifts in the gift batch in CSV format.

Raises

Forbidden – You do not have permissions to download the batch.
HTTPException – Downloading the batch failed.

Returns

The report content.

Return type

Attributes

application_id
description
description_localizations
icon
id
name
name_localizations
secret
secure

Methods

asyncdelete
asyncedit
asyncupdate

class discord.Achievement¶

Represents a Discord application achievement.

x == y: Checks if two achievements are equal.

x != y: Checks if two achievements are not equal.

hash(x): Return the achievement’s hash.

str(x): Returns the achievement’s name.

New in version 2.0.

id¶

The achievement’s ID.

Type: int

name¶

The achievement’s name.

Type: str

name_localizations¶

The achievement’s name localized to other languages, if available.

Type: Dict[Locale, str]

description¶

The achievement’s description.

Type: str

description_localizations¶

The achievement’s description localized to other languages, if available.

Type: Dict[Locale, str]

application_id¶

The application ID that the achievement belongs to.

Type: int

secure¶

Whether the achievement is secure.

Type: bool

secret¶

Whether the achievement is secret.

Type: bool

property icon¶

Returns the achievement’s icon.

Type: Asset

await edit(*, name=..., name_localizations=..., description=..., description_localizations=..., icon=..., secure=..., secret=...)¶

This function is a coroutine.

Edits the achievement.

All parameters are optional.

Parameters

name (str) – The achievement’s name.
name_localizations (Mapping[Locale, str]) – The achievement’s name localized to other languages.
description (str) – The achievement’s description.
description_localizations (Mapping[Locale, str]) – The achievement’s description localized to other languages.
icon (bytes) – A bytes-like object representing the new icon.
secure (bool) – Whether the achievement is secure.
secret (bool) – Whether the achievement is secret.

Raises

Forbidden – You do not have permissions to edit the achievement.
HTTPException – Editing the achievement failed.

await update(user, percent_complete)¶

This function is a coroutine.

Updates the achievement progress for a specific user.

Parameters

user (User) – The user to update the achievement for.
percent_complete (int) – The percent complete for the achievement.

Raises

Forbidden – You do not have permissions to update the achievement.
HTTPException – Updating the achievement failed.

await delete()¶

This function is a coroutine.

Deletes the achievement.

Raises

Forbidden – You do not have permissions to delete the achievement.
HTTPException – Deleting the achievement failed.

Library¶

Attributes

application
branch
branch_id
created_at
entitlements
flags
icon
name
sku
sku_id

Methods

asyncactivity_statistics
asyncdelete
asyncedit
asyncmark_installed

class discord.LibraryApplication¶

Represents a library entry.

x == y: Checks if two library entries are equal.

x != y: Checks if two library entries are not equal.

hash(x): Returns the library entry’s hash.

str(x): Returns the library entry’s name.

New in version 2.0.

created_at¶

When this library entry was created.

Type: datetime.datetime

application¶

The application that this library entry is for.

Type: PartialApplication

sku_id¶

The ID of the SKU that this library entry is for.

Type: int

sku¶

The SKU that this library entry is for.

Type: LibrarySKU

entitlements¶

The entitlements that this library entry has.

Type: List[Entitlement]

branch_id¶

The ID of the branch that this library entry installs.

Type: int

branch¶

The branch that this library entry installs.

Type: ApplicationBranch

property name¶

The library entry’s name.

Type: str

property icon¶

The library entry’s icon asset, if any.

Type: Asset

property flags¶

The library entry’s flags.

Type: LibraryApplicationFlags

await activity_statistics()¶

This function is a coroutine.

Gets the activity statistics for this library entry.

Raises: HTTPException – Getting the activity statistics failed.
Returns: The activity statistics for this library entry.
Return type: ApplicationActivityStatistics

await mark_installed()¶

This function is a coroutine.

Marks the library entry as installed.

Raises: HTTPException – Marking the library entry as installed failed.

await edit(*, flags=...)¶

This function is a coroutine.

Edits the library entry.

All parameters are optional.

Parameters: flags (LibraryApplicationFlags) – The new flags to set for the library entry.
Raises: HTTPException – Editing the library entry failed.

await delete()¶

This function is a coroutine.

Deletes the library entry.

Raises: HTTPException – Deleting the library entry failed.

Attributes

id
premium
preorder_release_date
preorder_released_at
type

class discord.LibrarySKU¶

Represents a partial store SKU for a library entry.

x == y: Checks if two library SKUs are equal.

x != y: Checks if two library SKUs are not equal.

hash(x): Returns the library SKU’s hash.

New in version 2.0.

id¶

The SKU’s ID.

Type: int

type¶

The type of the SKU.

Type: SKUType

preorder_release_date¶

The approximate date that the SKU will released for pre-order, if any.

Type: Optional[datetime.date]

preorder_released_at¶

The date that the SKU was released for pre-order, if any.

Type: Optional[datetime.datetime]

premium¶

Whether this SKU is provided for free to premium users.

Type: bool

OAuth2¶

Attributes

application
authorized
id
scopes

Methods

asyncrevoke

class discord.OAuth2Token¶

Represents an authorized OAuth2 application for a user.

x == y: Checks if two authorizations are equal.

x != y: Checks if two authorizations are not equal.

hash(x): Return the authorizations’s hash.

str(x): Returns the authorizations’s name.

New in version 2.1.

id¶

The ID of the authorization.

Type: int

application¶

The application that the authorization is for.

Type: PartialApplication

scopes¶

The scopes that the authorization has.

Type: List[str]

property authorized¶

Whether the user has already authorized the application.

This is here for compatibility purposes and is always True.

Type: bool

await revoke()¶

This function is a coroutine.

Revokes the application’s authorization.

Raises: HTTPException – Deauthorizing the application failed.

Attributes

application
approximate_guild_count
authorized
bot
code_challenge
code_challenge_method
guilds
redirect_uri
response_type
scopes
state

Methods

asyncauthorize

class discord.OAuth2Authorization¶

Represents a Discord OAuth2 application authorization.

New in version 2.1.

scopes¶

The scopes that the authorization has.

Type: List[str]

response_type¶

The response type that will be used for the authorization, if using the full OAuth2 flow.

Type: Optional[str]

code_challenge_method¶

The code challenge method that will be used for the PKCE authorization, if using the full OAuth2 flow.

Type: Optional[str]

code_challenge¶

The code challenge that will be used for the PKCE authorization, if using the full OAuth2 flow.

Type: Optional[str]

state¶

The state that will be used for authorization security.

Type: Optional[str]

authorized¶

Whether the user has already authorized the application.

Type: bool

application¶

The application that the authorization is for.

Type: PartialApplication

bot¶

The bot user associated with the application, provided if authorizing with the bot scope.

Type: Optional[User]

approximate_guild_count¶

The approximate number of guilds the bot is in, provided if authorizing with the bot scope.

Type: Optional[int]

guilds¶

The guilds the current user is in, provided if authorizing with the bot scope.

Type: List[UserGuild]

redirect_uri¶

The redirect URI that will be used for the authorization, if using the full OAuth2 flow and a redirect URI exists.

Type: Optional[str]

await authorize(*, guild=..., channel=..., permissions=...)¶

This function is a coroutine.

Authorizes the application for the user. A shortcut for Client.create_authorization().

Parameters

guild (Guild) – The guild to authorize for, if authorizing with the applications.commands or bot scopes.
channel (Union[TextChannel, VoiceChannel, StageChannel]) – The channel to authorize for, if authorizing with the webhooks.incoming scope. See Guild.webhook_channels().
permissions (Permissions) – The permissions to grant, if authorizing with the bot scope.

Raises

HTTPException – Authorizing the application failed.

Returns

The URL to redirect the user to. May be an error page.

Return type

Promotion¶

Attributes

claimed_at
code
ends_at
flags
id
inbound_description
inbound_link
inbound_restricted_countries
inbound_title
outbound_description
outbound_link
outbound_restricted_countries
outbound_title
starts_at
terms_and_conditions
trial_id

Methods

asyncclaim
defis_active
defis_claimed

class discord.Promotion¶

Represents a Discord promotion.

x == y: Checks if two promotions are equal.

x != y: Checks if two promotions are not equal.

hash(x): Returns the promotion’s hash.

str(x): Returns the outbound promotion’s name.

New in version 2.0.

id¶

The promotion ID.

Type: int

trial_id¶

The trial ID of the inbound promotion, if applicable.

Type: Optional[int]

starts_at¶

When the promotion starts.

Type: datetime.datetime

ends_at¶

When the promotion ends.

Type: datetime.datetime

claimed_at¶

When the promotion was claimed. Only available for claimed promotions.

Type: Optional[datetime.datetime]

code¶

The promotion’s claim code. Only available for claimed promotions.

Type: Optional[str]

outbound_title¶

The title of the outbound promotion.

Type: str

outbound_description¶

The description of the outbound promotion.

Type: str

outbound_link¶

The redemption page of the outbound promotion, used to claim it.

Type: str

outbound_restricted_countries¶

The countries that the outbound promotion is not available in.

Type: List[str]

inbound_title¶

The title of the inbound promotion. This is usually Discord Nitro.

Type: Optional[str]

inbound_description¶

The description of the inbound promotion.

Type: Optional[str]

inbound_link¶

The Discord help center link of the inbound promotion.

Type: Optional[str]

inbound_restricted_countries¶

The countries that the inbound promotion is not available in.

Type: List[str]

terms_and_conditions¶

The terms and conditions of the promotion.

Type: str

property flags¶

Returns the promotion’s flags.

Type: PromotionFlags

is_claimed()¶

bool: Checks if the promotion has been claimed.

Only accurate if the promotion was fetched from Client.promotions() with claimed set to True or claim() was just called.

is_active()¶: bool: Checks if the promotion is active.

await claim()¶

This function is a coroutine.

Claims the promotion.

Sets claimed_at and code.

Raises

Forbidden – You are not allowed to claim the promotion.
HTTPException – Claiming the promotion failed.

Returns

The claim code for the outbound promotion.

Return type

Attributes

amount
country_code
currency
payment_source_types
subscription_plan_id

class discord.PricingPromotion¶

Represents a Discord localized pricing promotion.

New in version 2.0.

subscription_plan_id¶

The ID of the subscription plan the promotion is for.

Type: int

country_code¶

The country code the promotion applies to.

Type: str

payment_source_types¶

The payment source types the promotion is restricted to.

Type: List[PaymentSourceType]

amount¶

The discounted price of the subscription plan.

Type: int

currency¶

The currency of the discounted price.

Type: str

Attributes

expires_at
id
trial
trial_id

Methods

asyncack
defis_acked

class discord.TrialOffer¶

Represents a Discord user trial offer.

x == y: Checks if two trial offers are equal.

x != y: Checks if two trial offers are not equal.

hash(x): Returns the trial offer’s hash.

New in version 2.0.

id¶

The ID of the trial offer.

Type: int

expires_at¶

When the trial offer expires, if it has been acknowledged.

Type: Optional[datetime.datetime]

trial_id¶

The ID of the trial.

Type: int

trial¶

The trial offered.

Type: SubscriptionTrial

is_acked()¶: bool: Checks if the trial offer has been acknowledged.

New in version 2.1.

await ack()¶

This function is a coroutine.

Acknowledges the trial offer.

Raises: HTTPException – Acknowledging the trial offer failed.

Subscription¶

class discord.Subscription¶

Represents a Discord subscription.

x == y: Checks if two premium subscriptions are equal.

x != y: Checks if two premium subscriptions are not equal.

hash(x): Returns the subscription’s hash.

len(x): Returns the number of items in the subscription, including quantity.

bool(x): Checks if the subscription is currently active and offering perks.

New in version 2.0.

id¶

The ID of the subscription.

Type: int

type¶

The type of the subscription.

Type: SubscriptionType

status¶

The status of the subscription. This is None for fake subscriptions.

Type: Optional[SubscriptionStatus]

payment_gateway¶

The payment gateway used to bill the subscription.

Type: Optional[PaymentGateway]

country_code¶

The country code the subscription is billed in, if applicable.

New in version 2.1.

Type: Optional[str]

currency¶

The currency the subscription is billed in.

Type: str

items¶

The items in the subscription.

Type: List[SubscriptionItem]

renewal_mutations¶

The mutations to the subscription that will occur after renewal.

Type: SubscriptionRenewalMutations

trial_id¶

The ID of the trial the subscription is from, if applicable.

Type: Optional[int]

payment_source_id¶

The ID of the payment source the subscription is paid with, if applicable.

Type: Optional[int]

payment_gateway_plan_id¶

The payment gateway’s plan ID for the subscription, if applicable.

Type: Optional[str]

payment_gateway_subscription_id¶

The payment gateway’s subscription ID for the subscription, if applicable.

Type: Optional[str]

price¶

The price of the subscription. This is only available for certain third-party subscriptions.

New in version 2.1.

Type: Optional[int]

created_at¶

When the subscription was created.

Type: datetime.datetime

canceled_at¶

When the subscription was canceled. This is only available for subscriptions with a status of SubscriptionStatus.canceled.

Type: Optional[datetime.datetime]

current_period_start¶

When the current billing period started.

Type: datetime.datetime

current_period_end¶

When the current billing period ends.

Type: datetime.datetime

trial_ends_at¶

When the trial ends, if applicable.

Type: Optional[datetime.datetime]

streak_started_at¶

When the current subscription streak started.

Type: Optional[datetime.datetime]

use_storekit_resubscribe¶

Whether the subscription should be managed through StoreKit.

New in version 2.1.

Type: bool

ended_at¶

When the subscription finally ended.

Type: Optional[datetime.datetime]

metadata¶

Extra metadata about the subscription.

Type: Metadata

latest_invoice¶

The latest invoice for the subscription, if applicable.

Type: Optional[SubscriptionInvoice]

property cancelled_at¶

When the subscription was canceled. This is only available for subscriptions with a status of SubscriptionStatus.canceled.

This is an alias of canceled_at.

Type: Optional[datetime.datetime]

property guild¶

The guild the subscription’s entitlements apply to, if applicable.

Type: Optional[Guild]

property grace_period¶

How many days past the renewal date the user has available to pay outstanding invoices.

Note

This is a static value and does not change based on the subscription’s status. For that, see remaining.

Changed in version 2.1: This is now a datetime.timedelta instead of an int.

Type: datetime.timedelta

property remaining¶

The remaining time until the subscription ends.

Type: datetime.timedelta

property trial_remaining¶

The remaining time until the trial applied to the subscription ends.

Type: datetime.timedelta

is_active()¶: bool: Indicates if the subscription is currently active and providing perks.

is_trial()¶: bool: Indicates if the subscription is a trial.

await edit(items=..., payment_source=..., currency=..., *, status=..., payment_source_token=None)¶

This function is a coroutine.

Edits the subscription.

All parameters are optional.

Parameters

items (List[SubscriptionItem]) – The new subscription items to use.
payment_source (int) – The new payment source for payment.
currency (str) – The new currency to use for payment.
status (SubscriptionStatus) – The new status of the subscription.
payment_source_token (Optional[str]) – The token used to authorize with the payment source.

Raises

Forbidden – You do not have permissions to edit the subscription.
HTTPException – Editing the subscription failed.

await delete()¶

This function is a coroutine.

Deletes the subscription.

There is an alias of this called cancel().

Raises: HTTPException – Deleting the subscription failed.

await cancel()¶

This function is a coroutine.

Deletes the subscription.

Alias of delete().

Raises: HTTPException – Deleting the subscription failed.

await preview_invoice(*, items=..., payment_source=..., currency=..., apply_entitlements=..., renewal=...)¶

This function is a coroutine.

Preview an invoice for the subscription with the given parameters.

All parameters are optional and default to the current subscription values.

Parameters

items (List[SubscriptionItem]) – The items the previewed invoice should have.
payment_source (PaymentSource) – The payment source the previewed invoice should be paid with.
currency (str) – The currency the previewed invoice should be paid in.
apply_entitlements (bool) – Whether to apply entitlements (credits) to the previewed invoice.
renewal (bool) – Whether the previewed invoice should be a renewal.

Raises

HTTPException – Failed to preview the invoice.

Returns

The previewed invoice.

Return type

SubscriptionInvoice

await payment_source()¶

This function is a coroutine.

Retrieves the payment source the subscription is paid with, if applicable.

Raises

NotFound – The payment source could not be found.
HTTPException – Retrieving the payment source failed.

Returns

The payment source the subscription is paid with, if applicable.

Return type

Optional[PaymentSource]

await invoices()¶

This function is a coroutine.

Retrieves all invoices for the subscription.

Raises

NotFound – The payment source or invoices could not be found.
HTTPException – Retrieving the invoices failed.

Returns

The invoices.

Return type

List[SubscriptionInvoice]

Attributes

id
plan_id
quantity

class discord.SubscriptionItem¶

Represents a Discord subscription item.

x == y: Checks if two subscription items are equal.

x != y: Checks if two subscription items are not equal.

hash(x): Returns the item’s hash.

len(x): Returns the quantity of the subscription item.

New in version 2.0.

id¶

The ID of the subscription item. Always available when received from the API.

Type: Optional[int]

quantity¶

How many of the item have been/are being purchased.

Type: int

plan_id¶

The ID of the plan the item is for.

Type: int

Attributes

amount
type

class discord.SubscriptionDiscount¶

Represents a discount on a Discord subscription item.

int(x): Returns the discount’s amount.

New in version 2.0.

type¶

The type of the discount.

Type: SubscriptionDiscountType

amount¶

How much the discount is.

Type: int

Attributes

applied_discount_ids
currency
current_period_end
current_period_start
id
items
status
subscription
subtotal
tax
tax_inclusive
total

Methods

defis_discounted
defis_preview
asyncpay

class discord.SubscriptionInvoice¶

Represents an invoice for a Discord subscription.

x == y: Checks if two invoices are equal.

x != y: Checks if two invoices are not equal.

hash(x): Returns the invoice’s hash.

New in version 2.0.

subscription¶

The subscription the invoice is for. Not available for new subscription previews.

Type: Optional[Subscription]

id¶

The ID of the invoice.

Type: int

status¶

The status of the invoice. Not available for subscription previews.

Type: Optional[SubscriptionInvoiceStatus]

currency¶

The currency the invoice is in.

Type: str

subtotal¶

The subtotal of the invoice.

Type: int

tax¶

The tax applied to the invoice.

Type: int

total¶

The total of the invoice.

Type: int

tax_inclusive¶

Whether the subtotal is inclusive of all taxes.

Type: bool

items¶

The items in the invoice.

Type: List[SubscriptionInvoiceItem]

current_period_start¶

When the current billing period started.

Type: datetime.datetime

current_period_end¶

When the current billing period ends.

Type: datetime.datetime

applied_discount_ids¶

The IDs of the discounts applied to the invoice.

New in version 2.1.

Type: List[int]

is_discounted()¶: bool: Indicates if the invoice has a discount.

is_preview()¶: bool: Indicates if the invoice is a preview and not real.

await pay(payment_source=None, currency='usd', *, payment_source_token=None, return_url=None)¶

This function is a coroutine.

Pays the invoice.

Parameters

payment_source (Optional[PaymentSource]) – The payment source the invoice should be paid with.
currency (str) – The currency to pay with.
payment_source_token (Optional[str]) – The token used to authorize with the payment source.
return_url (Optional[str]) – The URL to return to after the payment is complete.

Raises

TypeError – The invoice is a preview and not real.
NotFound – The invoice is not open or found.
HTTPException – Paying the invoice failed.

Attributes

amount
discounts
id
metadata
plan_id
plan_price
proration
quantity
savings

Methods

defis_discounted
defis_trial

class discord.SubscriptionInvoiceItem¶

Represents an invoice item.

x == y: Checks if two invoice items are equal.

x != y: Checks if two invoice items are not equal.

hash(x): Returns the invoice’s hash.

len(x): Returns the quantity of the invoice item.

New in version 2.0.

id¶

The ID of the invoice item.

Type: int

quantity¶

How many of the item have been/are being purchased.

Type: int

amount¶

The price of the item. This includes discounts.

Type: int

proration¶

Whether the item is prorated.

Type: bool

plan_id¶

The ID of the subscription plan the item represents.

Type: int

plan_price¶

The price of the subscription plan the item represents. This does not include discounts.

Type: int

discounts¶

A list of discounts applied to the item.

Type: List[SubscriptionDiscount]

metadata¶

Extra metadata about the invoice item.

New in version 2.1.

Type: Metadata

property savings¶

The total amount of discounts on the invoice item.

Type: int

is_discounted()¶: bool: Indicates if the invoice item has a discount.

is_trial()¶: bool: Indicates if the invoice item is a trial.

Attributes

items
payment_gateway_plan_id

Methods

defis_mutated

class discord.SubscriptionRenewalMutations¶

Represents a subscription renewal mutation.

This represents changes to a subscription that will occur after renewal.

len(x): Returns the number of items in the changed subscription, including quantity.

bool(x): Returns whether any mutations are present.

New in version 2.0.

payment_gateway_plan_id¶

The payment gateway’s new plan ID for the subscription. This signifies an external plan change.

Type: Optional[str]

items¶

The new items of the subscription.

Type: Optional[List[SubscriptionItem]]

is_mutated()¶: bool: Checks if any renewal mutations exist.

Attributes

duration
id
interval
interval_count

class discord.SubscriptionTrial¶

Represents a subscription trial.

x == y: Checks if two trials are equal.

x != y: Checks if two trials are not equal.

hash(x): Returns the trial’s hash.

New in version 2.0.

id¶

The ID of the trial.

Type: int

interval¶

The interval of the trial.

Type: SubscriptionInterval

interval_count¶

How many counts of the interval the trial provides.

Type: int

property duration¶

How long the trial lasts.

Type: datetime.timedelta

PremiumGuildSubscription¶

Attributes

ended
ends_at
guild
guild_id
id
remaining
user
user_id

Methods

asyncdelete

class discord.PremiumGuildSubscription¶

Represents a premium guild subscription (boost).

x == y: Checks if two premium guild subscriptions are equal.

x != y: Checks if two premium guild subscriptions are not equal.

hash(x): Returns the premium guild subscription’s hash.

New in version 2.0.

id¶

The ID of the guild premium subscription.

Type: int

guild_id¶

The ID of the guild this guild premium subscription belongs to.

Type: int

user_id¶

The ID of the user this guild premium subscription belongs to.

Type: int

user¶

The user this guild premium subscription belongs to.

Type: User

ended¶

Whether the guild premium subscription has ended.

Type: bool

ends_at¶

When the guild premium subscription ends.

Type: Optional[datetime.datetime]

property guild¶

The guild this guild premium subscription belongs to, if available.

Type: Optional[Guild]

property remaining¶

The remaining time for this guild premium subscription.

This is None if the subscription is not ending.

Type: Optional[datetime.timedelta]

await delete()¶

This function is a coroutine.

Deletes this guild premium subscription.

Raises

Forbidden – You do not have permissions to delete this guild premium subscription.
HTTPException – Deleting the guild premium subscription failed.

Attributes

canceled
cancelled
cooldown_ends_at
cooldown_remaining
id
premium_guild_subscription
subscription_id

Methods

asyncapply
asynccancel
defis_available
defis_on_cooldown
asyncsubscription
asyncuncancel

class discord.PremiumGuildSubscriptionSlot¶

Represents a premium guild subscription (boost) slot.

This is a slot that can be used on a guild (to boost it).

x == y: Checks if two subscription slots are equal.

x != y: Checks if two subscription slots are not equal.

hash(x): Returns the subscription slot’s hash.

New in version 2.0.

id¶

The ID of the guild subscription slot.

Type: int

subscription_id¶

The ID of the guild subscription this slot belongs to.

Type: int

canceled¶

Whether the slot is canceled.

Type: bool

cooldown_ends_at¶

When the cooldown for this guild subscription slot ends.

Type: Optional[datetime.datetime]

premium_guild_subscription¶

The subscription this slot belongs to.

Type: Optional[PremiumGuildSubscription]

is_available()¶: bool: Indicates if the slot is available for use.

is_on_cooldown()¶: bool: Indicates if the slot is on cooldown.

property cancelled¶

Whether the slot is cancelled.

This is an alias of canceled.

Type: bool

property cooldown_remaining¶

The cooldown remaining for this boost slot.

This is None if the cooldown has ended.

Type: Optional[datetime.timedelta]

await subscription()¶

This function is a coroutine.

Retrieves the subscription this guild subscription slot is attached to.

Raises

NotFound – You cannot access this subscription.
HTTPException – Fetching the subscription failed.

Returns

The retrieved subscription, if applicable.

Return type

Subscription

await apply(guild)¶

This function is a coroutine.

Applies the premium guild subscription slot to a guild.

Parameters: guild (Guild) – The guild to apply the slot to.
Raises: HTTPException – Applying the slot failed.
Returns: The premium guild subscription that was created.
Return type: PremiumGuildSubscription

await cancel()¶

This function is a coroutine.

Cancels the guild subscription slot.

Raises: HTTPException – Cancelling the slot failed.

await uncancel()¶

This function is a coroutine.

Uncancels the guild subscription slot.

Raises: HTTPException – Uncancelling the slot failed.

Attributes

ends_at
limit
remaining

class discord.PremiumGuildSubscriptionCooldown¶

Represents a premium guild subscription cooldown.

This is a cooldown that is applied to your guild subscription slot changes (boosting and unboosting).

New in version 2.0.

ends_at¶

When the cooldown resets.

Type: datetime.datetime

limit¶

The maximum number of changes that can be made before the cooldown is applied.

Type: int

remaining¶

The number of changes remaining before the cooldown is applied.

Type: int

SubscriptionPlan¶

Attributes

currency
discount_price
duration
fallback_currency
fallback_discount_price
fallback_price
id
interval
interval_count
name
premium_type
price
prices
sku_id
tax_inclusive

Methods

asynccreate_gift
asyncgifts
asyncpreview_purchase
asyncpurchase

class discord.SubscriptionPlan¶

Represents a subscription plan for a SKU.

x == y: Checks if two subscription plans are equal.

x != y: Checks if two subscription plans are not equal.

hash(x): Returns the subscription plan’s hash.

str(x): Returns the subscription plan’s name.

New in version 2.0.

id¶

The ID of the subscription plan.

Type: int

name¶

The name of the subscription plan.

Type: str

sku_id¶

The ID of the SKU that this subscription plan is for.

Type: int

interval¶

The interval of the subscription plan.

Type: SubscriptionInterval

interval_count¶

The number of intervals that make up a subscription period.

Type: int

tax_inclusive¶

Whether the subscription plan price is tax inclusive.

Type: bool

prices¶

The different prices of the subscription plan. Not available in some contexts.

Type: Dict[SubscriptionPlanPurchaseType, SubscriptionPlanPrices]

currency¶

The currency of the subscription plan’s price. Not available in some contexts.

Type: Optional[str]

price¶

The price of the subscription plan. Not available in some contexts.

Type: Optional[int]

discount_price¶

The discounted price of the subscription plan. This price is the one premium subscribers will pay, and is only available for premium subscribers.

Type: Optional[int]

fallback_currency¶

The fallback currency of the subscription plan’s price. This is the currency that will be used for gifting if the user’s currency is not giftable.

Type: Optional[str]

fallback_price¶

The fallback price of the subscription plan. This is the price that will be used for gifting if the user’s currency is not giftable.

Type: Optional[int]

fallback_discount_price¶

The fallback discounted price of the subscription plan. This is the discounted price that will be used for gifting if the user’s currency is not giftable.

Type: Optional[int]

property duration¶

How long the subscription plan lasts.

Type: datetime.timedelta

property premium_type¶

The premium type of the subscription plan, if it is a premium subscription.

Type: Optional[PremiumType]

await gifts()¶

This function is a coroutine.

Retrieves the gifts purchased for this subscription plan.

Raises: HTTPException – Retrieving the gifts failed.
Returns: The gifts that have been purchased for this SKU.
Return type: List[Gift]

await create_gift(*, gift_style=None)¶

This function is a coroutine.

Creates a gift for this subscription plan.

You must have a giftable entitlement for this subscription plan to create a gift.

Parameters

gift_style (Optional[GiftStyle]) – The style of the gift.

Raises

Forbidden – You do not have permissions to create a gift.
HTTPException – Creating the gift failed.

Returns

The gift created.

Return type

Gift

await preview_purchase(payment_source, *, test_mode=False)¶

This function is a coroutine.

Previews a purchase of this subscription plan.

Parameters

payment_source (PaymentSource) – The payment source to use for the purchase.
test_mode (bool) – Whether to preview the purchase in test mode.

Raises

HTTPException – Previewing the purchase failed.

Returns

The previewed purchase price.

Return type

SKUPrice

await purchase(payment_source=None, *, expected_amount=None, expected_currency=None, gift=False, gift_style=None, test_mode=False, payment_source_token=None, purchase_token=None, return_url=None, gateway_checkout_context=None)¶

This function is a coroutine.

Purchases this subscription plan.

This can only be used on premium subscription plans.

Parameters

payment_source (Optional[PaymentSource]) – The payment source to use for the purchase. Not required for free subscription plans.
expected_amount (Optional[int]) –
The expected amount of the purchase. This can be gotten from price or preview_purchase().

If the value passed here does not match the actual purchase amount, the purchase will error.
expected_currency (Optional[str]) –
The expected currency of the purchase. This can be gotten from price or preview_purchase().

If the value passed here does not match the actual purchase currency, the purchase will error.
gift (bool) – Whether to purchase the subscription plan as a gift. Certain requirements must be met for this to be possible.
gift_style (Optional[GiftStyle]) – The style of the gift. Only applicable if gift is True.
test_mode (bool) – Whether to purchase the subscription plan in test mode.
payment_source_token (Optional[str]) – The token used to authorize with the payment source.
purchase_token (Optional[str]) – The purchase token to use.
return_url (Optional[str]) – The URL to return to after the payment is complete.
gateway_checkout_context (Optional[str]) – The current checkout context.

Raises

TypeError – gift_style was passed but gift was not True.
HTTPException – Purchasing the subscription plan failed.

Returns

The purchased entitlements, the library entries created, and the gift created (if any).

Return type

Tuple[List[Entitlement], List[LibraryApplication], Optional[Gift]]

Attributes

country_code
country_prices
payment_source_prices

class discord.SubscriptionPlanPrices¶

Represents the different prices for a SubscriptionPlan.

New in version 2.0.

country_code¶

The country code the country prices are for.

Type: str

country_prices¶

The prices for the country the plan is being purchased in.

Type: List[SKUPrice]

payment_source_prices¶

A mapping of payment source IDs to the prices for that payment source.

Type: Dict[int, List[SKUPrice]]

Payment¶

class discord.Payment¶

Represents a payment to Discord.

x == y: Checks if two payments are equal.

x != y: Checks if two payments are not equal.

hash(x): Returns the payment’s hash.

str(x): Returns the payment’s description.

New in version 2.0.

id¶

The ID of the payment.

Type: int

amount¶

The amount of the payment.

Type: int

amount_refunded¶

The amount refunded from the payment, if any.

Type: int

tax¶

The amount of tax paid.

Type: int

tax_inclusive¶

Whether the amount is inclusive of all taxes.

Type: bool

currency¶

The currency the payment was made in.

Type: str

description¶

What the payment was for.

Type: str

status¶

The status of the payment.

Type: PaymentStatus

created_at¶

The time the payment was made.

Type: datetime.datetime

sku¶

The SKU the payment was for, if applicable.

Type: Optional[SKU]

sku_id¶

The ID of the SKU the payment was for, if applicable.

Type: Optional[int]

sku_price¶

The price of the SKU the payment was for, if applicable.

Type: Optional[int]

subscription_plan_id¶

The ID of the subscription plan the payment was for, if applicable.

Type: Optional[int]

subscription¶

The subscription the payment was for, if applicable.

Type: Optional[Subscription]

payment_source¶

The payment source the payment was made with.

Type: Optional[PaymentSource]

payment_gateway¶

The payment gateway the payment was made with, if applicable.

Type: Optional[PaymentGateway]

payment_gateway_payment_id¶

The ID of the payment on the payment gateway, if any.

Type: Optional[str]

invoice_url¶

The URL to download the VAT invoice for this payment, if available.

Type: Optional[str]

refund_invoices_urls¶

A list of URLs to download VAT credit notices for refunds on this payment, if available.

Type: List[str]

refund_disqualification_reasons¶

A list of reasons why the payment cannot be refunded, if any.

Type: List[RefundDisqualificationReason]

is_subscription()¶: bool: Whether the payment was for a subscription.

is_premium_subscription()¶: bool: Whether the payment was for a Discord premium subscription.

is_premium_subscription_gift()¶: bool: Whether the payment was for a Discord premium subscription gift.

is_purchased_externally()¶: bool: Whether the payment was made externally.

property flags¶

Returns the payment’s flags.

Type: PaymentFlags

await void()¶

This function is a coroutine.

Void the payment. Only applicable for payments of status PaymentStatus.pending.

Raises: HTTPException – Voiding the payment failed.

await refund(reason=<RefundReason.other: 0>)¶

This function is a coroutine.

Refund the payment. Refunds can only be made for payments less than 5 days old.

Parameters

reason (RefundReason) –

The reason for the refund.

New in version 2.1.

Raises

HTTPException – Refunding the payment failed.

SKU¶

Methods

asynccreate_discount
asynccreate_gift
asynccreate_gift_batch
asynccreate_store_listing
asyncdelete_discount
asyncedit
asyncgifts
defis_free
defis_game_awards_winner
defis_giftable
defis_paid
defis_premium_perk
defis_premium_subscription
defis_preorder
defis_released
asyncpreview_purchase
asyncpurchase
asyncstore_listings
asyncsubscription_plans

class discord.SKU¶

Represents a store SKU.

x == y: Checks if two SKUs are equal.

x != y: Checks if two SKUs are not equal.

hash(x): Returns the SKU’s hash.

str(x): Returns the SKU’s name.

New in version 2.0.

id¶

The SKU’s ID.

Type: int

name¶

The name of the SKU.

Type: str

name_localizations¶

The name of the SKU localized to different languages.

Type: Dict[Locale, str]

summary¶

The SKU’s summary, if any.

Type: Optional[str]

summary_localizations¶

The summary of the SKU localized to different languages.

Type: Dict[Locale, str]

legal_notice¶

The SKU’s legal notice, if any.

Type: Optional[str]

legal_notice_localizations¶

The legal notice of the SKU localized to different languages.

Type: Dict[Locale, str]

type¶

The type of the SKU.

Type: SKUType

product_line¶

The product line of the SKU, if any.

New in version 2.1.

Type: Optional[SKUProductLine]

slug¶

The URL slug of the SKU.

Type: str

dependent_sku_id¶

The ID of the SKU that this SKU is dependent on, if any.

Type: Optional[int]

application_id¶

The ID of the application that owns this SKU.

Type: int

application¶

The application that owns this SKU, if available.

Type: Optional[PartialApplication]

price_tier¶

The price tier of the SKU. This is the base price in USD. Not available for public SKUs.

Type: Optional[int]

price_overrides¶

Price overrides for specific currencies. These override the base price tier. Not available for public SKUs.

Type: Dict[str, int]

sale_price_tier¶

The sale price tier of the SKU. This is the base sale price in USD. Not available for public SKUs.

Type: Optional[int]

sale_price_overrides¶

Sale price overrides for specific currencies. These override the base sale price tier.

Type: Dict[str, int]

price¶

The price of the SKU.

Type: SKUPrice

access_level¶

The access level of the SKU.

Type: SKUAccessLevel

features¶

A list of features that this SKU has.

Type: List[SKUFeature]

locales¶

The locales that this SKU is available in.

Type: List[Locale]

genres¶

The genres that apply to this SKU.

Type: List[SKUGenre]

available_regions¶

The regions that this SKU is available in. If this is None, then the SKU is available everywhere.

Type: Optional[List[str]]

content_ratings¶

The content ratings of the SKU, if any. For public SKUs, only the rating of your region is returned.

Type: List[ContentRating]

system_requirements¶

The system requirements of the SKU by operating system, if any.

Type: List[SystemRequirements]

release_date¶

The date that the SKU will released, if any.

Type: Optional[datetime.date]

preorder_release_date¶

The approximate date that the SKU will released for pre-order, if any.

Type: Optional[datetime.date]

preorder_released_at¶

The date that the SKU was released for pre-order, if any.

Type: Optional[datetime.datetime]

external_purchase_url¶

An external URL to purchase the SKU at, if applicable.

Type: Optional[str]

premium¶

Whether this SKU is provided for free to premium users.

Type: bool

restricted¶

Whether this SKU is restricted.

Type: bool

exclusive¶

Whether this SKU is exclusive to Discord.

Type: bool

deleted¶

Whether this SKU has been soft-deleted.

New in version 2.1.

Type: bool

show_age_gate¶

Whether the client should prompt the user to verify their age.

Type: bool

bundled_skus¶

A list of SKUs bundled with this SKU. These are SKUs that the user will be entitled to after purchasing this parent SKU.

Type: List[SKU]

manifest_label_ids¶

A list of manifest label IDs that this SKU is associated with.

Type: List[int]

is_free()¶: bool: Checks if the SKU is free.

is_paid()¶: bool: Checks if the SKU requires payment.

is_preorder()¶: bool: Checks if this SKU is a preorder.

is_released()¶: bool: Checks if the SKU is released.

is_giftable()¶: bool: Checks if this SKU is giftable.

is_premium_perk()¶: bool: Checks if the SKU is a perk for premium users.

is_premium_subscription()¶: bool: Checks if the SKU is a premium subscription (e.g. Nitro or Server Boosts).

is_game_awards_winner()¶: bool: Checks if the SKU is a winner of The Game Awards.

property url¶

Returns the URL of the SKU.

Type: str

property flags¶

Returns the SKU’s flags.

Type: SKUFlags

property supported_operating_systems¶

A list of supported operating systems.

Type: List[OperatingSystem]

await edit(name=..., name_localizations=..., legal_notice=..., legal_notice_localizations=..., price_tier=..., price_overrides=..., sale_price_tier=..., sale_price_overrides=..., dependent_sku=..., flags=..., access_level=..., features=..., locales=..., genres=..., content_ratings=..., system_requirements=..., release_date=..., bundled_skus=..., manifest_labels=...)¶

This function is a coroutine.

Edits the SKU.

All parameters are optional.

Parameters

name (str) – The SKU’s name.
name_localizations (Mapping[Locale, str]) – The SKU’s name localized to other languages.
legal_notice (Optional[str]) – The SKU’s legal notice.
legal_notice_localizations (Mapping[Locale, str]) – The SKU’s legal notice localized to other languages.
price_tier (Optional[int]) – The price tier of the SKU. This is the base price in USD that other currencies will be calculated from.
price_overrides (Mapping[str, int]) – A mapping of currency to price. These prices override the base price tier.
sale_price_tier (Optional[int]) – The sale price tier of the SKU. This is the base sale price in USD that other currencies will be calculated from.
sale_price_overrides (Mapping[str, int]) – A mapping of currency to sale price. These prices override the base sale price tier.
dependent_sku (Optional[SKU]) – The ID of the SKU that this SKU is dependent on.
flags (SKUFlags) – The SKU’s flags.
access_level (SKUAccessLevel) – The access level of the SKU.
features (List[SKUFeature]) – A list of features of the SKU.
locales (List[Locale]) – A list of locales supported by the SKU.
genres (List[SKUGenre]) – A list of genres of the SKU.
content_ratings (List[ContentRating]) – A list of content ratings of the SKU.
system_requirements (List[SystemRequirements]) – A list of system requirements of the SKU.
release_date (Optional[datetime.date]) – The release date of the SKU.
bundled_skus (List[SKU]) – A list SKUs that are bundled with this SKU.
manifest_labels (List[ManifestLabel]) – A list of manifest labels for the SKU.

Raises

Forbidden – You do not have access to edit the SKU.
HTTPException – Editing the SKU failed.

await subscription_plans(*, country_code=..., payment_source=..., with_unpublished=False)¶

This function is a coroutine.

Returns a list of SubscriptionPlans for this SKU.

New in version 2.0.

Parameters

country_code (str) – The country code to retrieve the subscription plan prices for. Defaults to the country code of the current user.
payment_source (PaymentSource) – The specific payment source to retrieve the subscription plan prices for. Defaults to all payment sources of the current user.
with_unpublished (bool) –
Whether to include unpublished subscription plans.

If True, then you require access to the application.

Raises

HTTPException – Retrieving the subscription plans failed.

Returns

The subscription plans for this SKU.

Return type

List[SubscriptionPlan]

await store_listings(localize=True)¶

This function is a coroutine.

Returns a list of StoreListings for this SKU.

Parameters

localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.

Raises

Forbidden – You do not have access to fetch store listings.
HTTPException – Retrieving the store listings failed.

Returns

The store listings for this SKU.

Return type

List[StoreListing]

await create_store_listing(*, summary, summary_localizations=None, description, description_localizations=None, tagline=None, tagline_localizations=None, child_skus=None, guild=None, published=False, carousel_items=None, preview_video=None, header_background=None, hero_background=None, hero_video=None, box_art=None, thumbnail=None, header_logo_light=None, header_logo_dark=None)¶

This function is a coroutine.

Creates a a store listing for this SKU.

Parameters

summary (str) – The summary of the store listing.
summary_localizations (Optional[Mapping[Locale, str]]) – The summary of the store listing localized to different languages.
description (str) – The description of the store listing.
description_localizations (Optional[Mapping[Locale, str]]) – The description of the store listing localized to different languages.
tagline (Optional[str]) – The tagline of the store listing.
tagline_localizations (Optional[Mapping[Locale, str]]) – The tagline of the store listing localized to different languages.
child_skus (Optional[List[SKU]]) – The child SKUs of the store listing.
guild (Optional[Guild]) – The guild that the store listing is for.
published (bool) – Whether the store listing is published.
carousel_items (Optional[List[Union[StoreAsset, str]]]) – A list of carousel items to add to the store listing. These can be store assets or YouTube video IDs.
preview_video (Optional[StoreAsset]) – The preview video of the store listing.
header_background (Optional[StoreAsset]) – The header background of the store listing.
hero_background (Optional[StoreAsset]) – The hero background of the store listing.
hero_video (Optional[StoreAsset]) – The hero video of the store listing.
box_art (Optional[StoreAsset]) – The box art of the store listing.
thumbnail (Optional[StoreAsset]) – The thumbnail of the store listing.
header_logo_light (Optional[StoreAsset]) – The header logo image for light backgrounds.
header_logo_dark (Optional[StoreAsset]) – The header logo image for dark backgrounds.

Raises

Forbidden – You do not have permissions to edit the store listing.
HTTPException – Editing the store listing failed.

await create_discount(user, percent_off, *, ttl=3600)¶

This function is a coroutine.

Creates a discount for this SKU for a user.

This discount will be applied to the user’s next purchase of this SKU.

Parameters

user (User) – The user to create the discount for.
percent_off (int) – The discount in the form of a percentage off the price to give the user.
ttl (int) – How long the discount should last for in seconds. Minimum 60 seconds, maximum 3600 seconds.

Raises

Forbidden – You do not have permissions to create the discount.
HTTPException – Creating the discount failed.

await delete_discount(user)¶

This function is a coroutine.

Deletes a discount for this SKU for a user.

You do not need to call this after a discounted purchase has been made, as the discount will be automatically consumed and deleted.

Parameters

user (User) – The user to delete the discount for.

Raises

Forbidden – You do not have permissions to delete the discount.
HTTPException – Deleting the discount failed.

await create_gift_batch(*, amount, description, entitlement_branches=None, entitlement_starts_at=None, entitlement_ends_at=None)¶

This function is a coroutine.

Creates a gift batch for this SKU.

Parameters

amount (int) – The amount of gifts to create in the batch.
description (str) – The description of the gift batch.
entitlement_branches (List[ApplicationBranch]) – The branches to grant in the gifts.
entitlement_starts_at (datetime.date) – When the entitlement is valid from.
entitlement_ends_at (datetime.date) – When the entitlement is valid until.

Raises

Forbidden – You do not have permissions to create a gift batch.
HTTPException – Creating the gift batch failed.

Returns

The gift batch created.

Return type

GiftBatch

await gifts(subscription_plan=None)¶

This function is a coroutine.

Retrieves the gifts purchased for this SKU.

Parameters: subscription_plan (Optional[SubscriptionPlan]) – The subscription plan to retrieve the gifts for.
Raises: HTTPException – Retrieving the gifts failed.
Returns: The gifts that have been purchased for this SKU.
Return type: List[Gift]

await create_gift(*, subscription_plan=None, gift_style=None)¶

This function is a coroutine.

Creates a gift for this SKU.

You must have a giftable entitlement for this SKU to create a gift.

Parameters

subscription_plan (Optional[SubscriptionPlan]) – The subscription plan to gift.
gift_style (Optional[GiftStyle]) – The style of the gift.

Raises

Forbidden – You do not have permissions to create a gift.
HTTPException – Creating the gift failed.

Returns

The gift created.

Return type

Gift

await preview_purchase(payment_source, *, subscription_plan=None, test_mode=False)¶

This function is a coroutine.

Previews a purchase of this SKU.

Parameters

payment_source (PaymentSource) – The payment source to use for the purchase.
subscription_plan (Optional[SubscriptionPlan]) – The subscription plan being purchased.
test_mode (bool) – Whether to preview the purchase in test mode.

Raises

HTTPException – Previewing the purchase failed.

Returns

The previewed purchase price.

Return type

SKUPrice

await purchase(payment_source=None, *, subscription_plan=None, expected_amount=None, expected_currency=None, gift=False, gift_style=None, test_mode=False, payment_source_token=None, purchase_token=None, return_url=None, gateway_checkout_context=None)¶

This function is a coroutine.

Purchases this SKU.

Parameters

payment_source (Optional[PaymentSource]) – The payment source to use for the purchase. Not required for free SKUs.
subscription_plan (Optional[SubscriptionPlan]) – The subscription plan to purchase. Can only be used for premium subscription SKUs.
expected_amount (Optional[int]) –
The expected amount of the purchase. This can be gotten from price or preview_purchase().

If the value passed here does not match the actual purchase amount, the purchase will error.
expected_currency (Optional[str]) –
The expected currency of the purchase. This can be gotten from price or preview_purchase().

If the value passed here does not match the actual purchase currency, the purchase will error.
gift (bool) – Whether to purchase the SKU as a gift. Certain requirements must be met for this to be possible.
gift_style (Optional[GiftStyle]) – The style of the gift. Only applicable if gift is True.
test_mode (bool) – Whether to purchase the SKU in test mode.
payment_source_token (Optional[str]) – The token used to authorize with the payment source.
purchase_token (Optional[str]) – The purchase token to use.
return_url (Optional[str]) – The URL to return to after the payment is complete.
gateway_checkout_context (Optional[str]) – The current checkout context.

Raises

TypeError – gift_style was passed but gift was not True.
HTTPException – Purchasing the SKU failed.

Returns

The purchased entitlements, the library entries created, and the gift created (if any).

Return type

Tuple[List[Entitlement], List[LibraryApplication], Optional[Gift]]

Attributes

application
distributor
id
sku_id
url

class discord.ThirdPartySKU¶

Represents an application’s primary SKU on third-party platforms.

New in version 2.0.

application¶

The application that the SKU belongs to.

Type: Union[PartialApplication, IntegrationApplication]

distributor¶

The distributor of the SKU.

Type: Distributor

id¶

The product ID.

Type: Optional[str]

sku_id¶

The SKU ID.

Type: Optional[str]

property url¶

Returns the URL of the SKU, if available.

New in version 2.1.

Type: str

Attributes

amount
currency
discounts
exponent
premium
sale_amount
sale_percentage

Methods

defis_discounted
defis_free

class discord.SKUPrice¶

Represents a SKU’s price.

bool(x): Checks if a SKU costs anything.

int(x): Returns the price of the SKU.

New in version 2.0.

currency¶

The currency of the price.

Type: str

amount¶

The price of the SKU.

Type: int

sale_amount¶

The price of the SKU with discounts applied, if any.

Type: Optional[int]

sale_percentage¶

The percentage of the price discounted, if any.

Type: int

exponent¶

The offset of the currency’s decimal point. For example, if the price is 1000 and the exponent is 2, the price is $10.00.

New in version 2.1.

Type: int

premium¶

Special SKU prices for premium (Nitro) users.

New in version 2.1.

Type: Dict[PremiumType, SKUPrice]

is_discounted()¶: bool: Checks whether the SKU is discounted.

is_free()¶: bool: Checks whether the SKU is free.

Changed in version 2.1: This now also checks the sale_amount to see if the SKU is free with discounts applied.

property discounts¶

Returns the amount of discounts applied to the SKU price.

Type: int

class discord.StoreListing¶

Represents a store listing.

x == y: Checks if two listings are equal.

x != y: Checks if two listings are not equal.

hash(x): Returns the listing’s hash.

str(x): Returns the listing’s summary.

New in version 2.0.

id¶

The listing’s ID.

Type: int

summary¶

The listing’s summary.

Type: Optional[str]

summary_localizations¶

The listing’s summary localized to different languages.

Type: Dict[Locale, str]

description¶

The listing’s description.

Type: Optional[str]

description_localizations¶

The listing’s description localized to different languages.

Type: Dict[Locale, str]

tagline¶

The listing’s tagline.

Type: Optional[str]

tagline_localizations¶

The listing’s tagline localized to different languages.

Type: Dict[Locale, str]

flavor¶

The listing’s flavor text.

Type: Optional[str]

sku¶

The SKU attached to this listing.

Type: SKU

child_skus¶

The child SKUs attached to this listing.

Type: List[SKU]

alternative_skus¶

Alternative SKUs to the one attached to this listing.

Type: List[SKU]

guild¶

The guild tied to this listing, if any.

Type: Optional[Guild]

published¶

Whether the listing is published and publicly visible.

Type: bool

published_at¶

When the listing was published, if available.

Note

This data is not available for all listings.

New in version 2.1.

Type: Optional[datetime.datetime]

unpublished_at¶

When the listing was last unpublished, if available. If this is a future date, the listing will be unpublished at that time.

New in version 2.1.

Type: Optional[datetime.datetime]

staff_note¶

The staff note attached to this listing.

Type: Optional[StoreNote]

assets¶

A list of assets used in this listing.

Type: List[StoreAsset]

carousel_items¶

A list of assets and YouTube videos displayed in the carousel.

Type: List[StoreAsset]

preview_video¶

The preview video of the store listing.

Type: Optional[StoreAsset]

header_background¶

The header background image.

Type: Optional[StoreAsset]

hero_background¶

The hero background image.

Type: Optional[StoreAsset]

box_art¶

The box art of the product.

Type: Optional[StoreAsset]

thumbnail¶

The listing’s thumbnail.

Type: Optional[StoreAsset]

header_logo_light¶

The header logo image for light backgrounds.

Type: Optional[StoreAsset]

header_logo_dark¶

The header logo image for dark backgrounds.

Type: Optional[StoreAsset]

await edit(*, summary=..., summary_localizations=..., description=..., description_localizations=..., tagline=..., tagline_localizations=..., child_skus=..., guild=..., published=..., carousel_items=..., preview_video=..., header_background=..., hero_background=..., hero_video=..., box_art=..., thumbnail=..., header_logo_light=..., header_logo_dark=...)¶

This function is a coroutine.

Edits the store listing.

All parameters are optional.

Parameters

summary (Optional[str]) – The summary of the store listing.
summary_localizations (Mapping[Locale, str]) – The summary of the store listing localized to different languages.
description (Optional[str]) – The description of the store listing.
description_localizations (Mapping[Locale, str]) – The description of the store listing localized to different languages.
tagline (Optional[str]) – The tagline of the store listing.
tagline_localizations (Mapping[Locale, str]) – The tagline of the store listing localized to different languages.
child_skus (List[SKU]) – The child SKUs of the store listing.
guild (Optional[Guild]) – The guild that the store listing is for.
published (bool) – Whether the store listing is published.
carousel_items (List[Union[StoreAsset, str]]) – A list of carousel items to add to the store listing. These can be store assets or YouTube video IDs.
preview_video (Optional[StoreAsset]) – The preview video of the store listing.
header_background (Optional[StoreAsset]) – The header background of the store listing.
hero_background (Optional[StoreAsset]) – The hero background of the store listing.
hero_video (Optional[StoreAsset]) – The hero video of the store listing.
box_art (Optional[StoreAsset]) – The box art of the store listing.
thumbnail (Optional[StoreAsset]) – The thumbnail of the store listing.
header_logo_light (Optional[StoreAsset]) – The header logo image for light backgrounds.
header_logo_dark (Optional[StoreAsset]) – The header logo image for dark backgrounds.

Raises

Forbidden – You do not have permissions to edit the store listing.
HTTPException – Editing the store listing failed.

property url¶

Returns the URL of the store listing. This is the URL of the primary SKU.

Type: str

Attributes

animated
application_id
height
id
mime_type
parent
size
url
width

Methods

asyncdelete
defis_youtube_video
asyncread

class discord.StoreAsset¶

Represents an application store asset.

x == y: Checks if two assets are equal.

x != y: Checks if two assets are not equal.

hash(x): Returns the asset’s hash.

New in version 2.0.

parent¶

The store listing or application that this asset belongs to.

Type: Union[StoreListing, Application]

id¶

The asset’s ID or YouTube video ID.

Type: Union[int, str]

size¶

The asset’s size in bytes, or 0 if it’s a YouTube video.

Type: int

height¶

The asset’s height in pixels, or 0 if it’s a YouTube video.

Type: int

width¶

The asset’s width in pixels, or 0 if it’s a YouTube video.

Type: int

mime_type¶

The asset’s mime type, or “video/youtube” if it is a YouTube video.

Type: str

property application_id¶

Returns the application ID that this asset belongs to.

Type: int

property animated¶

Indicates if the store asset is animated.

Type: bool

property url¶

Returns the URL of the store asset.

Type: str

is_youtube_video()¶: bool: Indicates if the asset is a YouTube video.

await read()¶

This function is a coroutine.

Retrieves the content of this asset as a bytes object.

Raises

ValueError – The asset is a YouTube video.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The content of the asset.

Return type

await delete()¶

This function is a coroutine.

Deletes the asset.

Raises

ValueError – The asset is a YouTube video.
Forbidden – You are not allowed to delete this asset.
HTTPException – Deleting the asset failed.

Attributes

content
user

class discord.StoreNote¶

Represents a note for a store listing.

str(x): Returns the note’s content.

New in version 2.0.

user¶

The user who wrote the note.

Type: Optional[User]

content¶

The note content.

Type: str

Attributes

agency
descriptors
rating

class discord.ContentRating¶

Represents a SKU’s content rating.

New in version 2.0.

agency¶

The agency that rated the content.

Type: ContentRatingAgency

rating¶

The rating of the content.

Type: Union[ESRBRating, PEGIRating]

descriptors¶

Extra descriptors for the content rating.

Type: Union[List[ESRBContentDescriptor], List[PEGIContentDescriptor]

Attributes

minimum_cpu
minimum_directx
minimum_disk
minimum_gpu
minimum_network
minimum_notes
minimum_os_version
minimum_ram
minimum_sound_card
os
recommended_cpu
recommended_directx
recommended_disk
recommended_gpu
recommended_network
recommended_notes
recommended_os_version
recommended_ram
recommended_sound_card

class discord.SystemRequirements¶

Represents system requirements.

New in version 2.0.

os¶

The operating system these requirements apply to.

Type: OperatingSystem

minimum_os_version¶

The minimum operating system version required.

Type: str

recommended_os_version¶

The recommended operating system version.

Type: str

minimum_cpu¶

The minimum CPU specifications required.

Type: str

recommended_cpu¶

The recommended CPU specifications.

Type: str

minimum_gpu¶

The minimum GPU specifications required.

Type: str

recommended_gpu¶

The recommended GPU specifications.

Type: str

minimum_ram¶

The minimum RAM size in megabytes.

Type: int

recommended_ram¶

The recommended RAM size in megabytes.

Type: int

minimum_disk¶

The minimum free storage space in megabytes.

Type: int

recommended_disk¶

The recommended free storage space in megabytes.

Type: int

minimum_sound_card¶

The minimum sound card specifications required, if any.

Type: Optional[str]

recommended_sound_card¶

The recommended sound card specifications, if any.

Type: Optional[str]

minimum_directx¶

The minimum DirectX version required, if any.

Type: Optional[str]

recommended_directx¶

The recommended DirectX version, if any.

Type: Optional[str]

minimum_network¶

The minimum network specifications required, if any.

Type: Optional[str]

recommended_network¶

The recommended network specifications, if any.

Type: Optional[str]

minimum_notes¶

Any extra notes on minimum requirements.

Type: Optional[str]

recommended_notes¶

Any extra notes on recommended requirements.

Type: Optional[str]

Metadata¶

Methods

defitems
defkeys
defvalues

class discord.Metadata¶

Represents a raw model from Discord.

Because of how unstable and wildly varying some metadata in Discord can be, this is a simple class that just provides access to the raw data using dot notation. This means that None is returned for unknown attributes instead of raising an exception. This class can be used similarly to a dictionary.

New in version 2.0.

x == y: Checks if two metadata objects are equal.

x != y: Checks if two metadata objects are not equal.

x[key]: Returns a metadata value if it is found, otherwise raises a KeyError.

key in x: Checks if a metadata value is present.

len(x): Returns the number of metadata values present.

iter(x)
Returns an iterator of ``(field, value)`` pairs. This allows this class
to be used as an iterable in list/dict/etc constructions.

keys()¶: A set-like object providing a view on the metadata’s keys.

values()¶: A set-like object providing a view on the metadata’s values.

items()¶: A set-like object providing a view on the metadata’s items.

ReadState¶

Attributes

acked_pin_timestamp
badge_count
flags
id
last_acked_id
last_entity_id
last_pin_timestamp
last_viewed
resource
type

Methods

asyncack
asyncdelete

class discord.ReadState¶

Represents the read state of a resource.

This is a purposefuly very low-level object.

x == y: Checks if two read states are equal.

x != y: Checks if two read states are not equal.

hash(x): Returns the read state’s hash.

New in version 2.1.

id¶

The ID of the resource.

Type: int

type¶

The type of the read state.

Type: ReadStateType

last_acked_id¶

The ID of the last acknowledged resource (e.g. message) in the read state. It may not point to an existing or valid resource.

Type: int

acked_pin_timestamp¶

When the channel’s pins were last acknowledged.

Type: Optional[datetime.datetime]

badge_count¶

The number of badges in the read state (e.g. mentions).

Type: int

last_viewed¶

When the resource was last viewed. Only tracked for read states of type ReadStateType.channel.

Type: Optional[datetime.date]

property flags¶

The read state’s flags.

Type: ReadStateFlags

property resource¶

The entity associated with the read state.

Type: Union[ClientUser, Guild, TextChannel, StageChannel, VoiceChannel, Thread, DMChannel, GroupChannel, PartialMessageable]

property last_entity_id¶

The ID of the last resource (e.g. message) in the read state. It may not point to an existing or valid resource.

Type: int

property last_pin_timestamp¶

When the last pinned message was pinned in the channel.

Type: Optional[datetime.datetime]

await ack(entity_id, *, manual=False, mention_count=None, last_viewed=...)¶

This function is a coroutine.

Updates the read state. This is a purposefully low-level function.

Parameters

entity_id (int) – The ID of the entity to set the read state to.
manual (bool) – Whether the read state was manually set by the user. Only for read states of type ReadStateType.channel.
mention_count (Optional[int]) – The number of mentions to set the read state to. Only applicable for manual acknowledgements. Only for read states of type ReadStateType.channel.
last_viewed (Optional[datetime.date]) – The last day the user viewed the channel. Defaults to today for non-manual acknowledgements. Only for read states of type ReadStateType.channel.

Raises

ValueError – Invalid parameters were passed.
HTTPException – Updating the read state failed.

await delete()¶

This function is a coroutine.

Deletes the read state.

Raises: HTTPException – Deleting the read state failed.

Asset¶

Attributes

Methods

defis_animated
defis_passthrough
asyncread
defreplace
asyncsave
asyncto_file
defwith_format
defwith_size
defwith_static_format

class discord.Asset¶

Represents a CDN asset on Discord.

str(x): Returns the URL of the CDN asset.

len(x): Returns the length of the CDN asset’s URL.

x == y: Checks if the asset is equal to another asset.

x != y: Checks if the asset is not equal to another asset.

hash(x): Returns the hash of the asset.

property url¶

Returns the underlying URL of the asset.

Type: str

property key¶

Returns the identifying key of the asset.

Type: str

is_animated()¶: bool: Returns whether the asset is animated.

is_passthrough()¶: bool: Returns whether the asset is passed through.

New in version 2.0.

replace(*, size=..., format=..., static_format=..., passthrough=..., keep_aspect_ratio=False)¶

Returns a new asset with the passed components replaced.

Changed in version 2.0: static_format is now preferred over format if both are present and the asset is not animated.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

size (int) – The new size of the asset.
format (str) – The new format to change it to. Must be either ‘webp’, ‘jpeg’, ‘jpg’, ‘png’, or ‘gif’ if it’s animated.
static_format (str) – The new format to change it to if the asset isn’t animated. Must be either ‘webp’, ‘jpeg’, ‘jpg’, or ‘png’.
passthrough (bool) –
Whether to return the asset in the original, Discord-defined quality and format (usually APNG). This only has an affect on specific asset types. This will cause the format and size parameters to be ignored by the CDN. By default, this is set to False if a size or format parameter is passed and the asset is marked as passed through, else untouched. A value of None will unconditionally omit the parameter from the query string.

New in version 2.0.
keep_aspect_ratio (bool) –
Whether to return the original aspect ratio of the asset instead of having it resized to the endpoint’s enforced aspect ratio.

New in version 2.0.

Raises

ValueError – An invalid size or format was passed.

Returns

The newly updated asset.

Return type

Asset

with_size(size, /)¶

Returns a new asset with the specified size. Also sets passthrough to False if the asset is marked as passed through.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters: size (int) – The new size of the asset.
Raises: ValueError – The asset had an invalid size.
Returns: The new updated asset.
Return type: Asset

with_format(format, /)¶

Returns a new asset with the specified format. Also sets passthrough to False if the asset is marked as passed through.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters: format (str) – The new format of the asset.
Raises: ValueError – The asset had an invalid format.
Returns: The new updated asset.
Return type: Asset

with_static_format(format, /)¶

Returns a new asset with the specified static format. Also sets passthrough to False if the asset is marked as passed through.

This only changes the format if the underlying asset is not animated. Otherwise, the asset is not changed.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters: format (str) – The new static format of the asset.
Raises: ValueError – The asset had an invalid format.
Returns: The new updated asset.
Return type: Asset

await read()¶

This function is a coroutine.

Retrieves the content of this asset as a bytes object.

Raises

DiscordException – There was no internal connection state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The content of the asset.

Return type

await save(fp, *, seek_begin=True)¶

This function is a coroutine.

Saves this asset into a file-like object.

Parameters

fp (Union[io.BufferedIOBase, os.PathLike]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.
seek_begin (bool) – Whether to seek to the beginning of the file after saving is successfully done.

Raises

DiscordException – There was no internal connection state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The number of bytes written.

Return type

await to_file(*, filename=..., description=None, spoiler=False)¶

This function is a coroutine.

Converts the asset into a File suitable for sending via abc.Messageable.send().

New in version 2.0.

Parameters

filename (Optional[str]) – The filename of the file. If not provided, then the filename from the asset’s URL is used.
description (Optional[str]) – The description for the file.
spoiler (bool) – Whether the file is a spoiler.

Raises

DiscordException – The asset does not have an associated state.
ValueError – The asset is a unicode emoji.
TypeError – The asset is a sticker with lottie type.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The asset as a file suitable for sending.

Return type

Guild¶

Attributes

acked_scheduled_event
afk_channel
afk_timeout
application_command_count
application_command_counts
application_id
approximate_member_count
approximate_presence_count
banner
bitrate_limit
categories
channels
chunked
created_at
default_notifications
default_role
description
directories
directory_channels
discovery_splash
emoji_limit
emojis
explicit_content_filter
features
filesize_limit
forums
hub_type
icon
id
joined_at
large
max_members
max_presences
max_video_channel_users
me
member_count
members
mfa_level
name
notification_settings
nsfw_level
online_count
owner
owner_id
preferred_locale
premium_progress_bar_enabled
premium_subscriber_role
premium_subscribers
premium_subscription_count
premium_tier
public_updates_channel
roles
rules_channel
scheduled_events
scheduled_events_read_state
splash
stage_channels
stage_instances
sticker_limit
stickers
system_channel
system_channel_flags
text_channels
threads
unavailable
vanity_url
vanity_url_code
verification_level
voice_channels
voice_client
widget_channel
widget_enabled

Methods

asyncack
asyncadmin_community_eligibility
asyncapplication_commands
asyncapplications
asyncapply_premium_subscription_slots
async foraudit_logs
asyncautomod_rules
asyncban
async forbans
defby_category
asyncchange_voice_state
asyncchunk
asynccreate_automod_rule
asynccreate_category
asynccreate_category_channel
asynccreate_custom_emoji
asynccreate_directory
asynccreate_directory_channel
asynccreate_forum
asynccreate_forum_channel
asynccreate_integration
asynccreate_role
asynccreate_scheduled_event
asynccreate_stage_channel
asynccreate_sticker
asynccreate_template
asynccreate_text_channel
asynccreate_voice_channel
asyncdelete
asyncdelete_emoji
asyncdelete_sticker
asyncdirectory_broadcast_eligibility
asyncedit
asyncedit_role_positions
asyncedit_welcome_screen
asyncedit_widget
asyncentitlements
asyncestimate_pruned_members
asyncfetch_automod_rule
asyncfetch_ban
asyncfetch_channel
asyncfetch_channels
asyncfetch_emoji
asyncfetch_emojis
asyncfetch_member
asyncfetch_member_profile
asyncfetch_members
asyncfetch_price_tier
asyncfetch_roles
asyncfetch_scheduled_event
asyncfetch_scheduled_events
asyncfetch_sticker
asyncfetch_stickers
defget_channel
defget_channel_or_thread
defget_emoji
defget_member
defget_member_named
defget_role
defget_scheduled_event
defget_stage_instance
defget_thread
asyncintegrations
asyncinvites
defis_hub
defis_joined
asyncjoin_admin_community
asynckick
asyncleave
asyncmigrate_command_scope
asyncpremium_subscriptions
asyncprice_tiers
asyncprune_members
asyncquery_members
asyncquery_recent_members
asyncrole_member_counts
defsearch
asyncsubscribe
asyncsubscribe_to
asyncsubscribed_scheduled_events
asynctemplates
asynctop_channels
asynctop_emojis
asyncunban
asyncunsubscribe_from
asyncvanity_invite
asyncwebhook_channels
asyncwebhooks
asyncwelcome_screen
asyncwidget

class discord.Guild¶

Represents a Discord guild.

This is referred to as a “server” in the official Discord UI.

x == y: Checks if two guilds are equal.

x != y: Checks if two guilds are not equal.

hash(x): Returns the guild’s hash.

str(x): Returns the guild’s name.

name¶

The guild name.

Type: str

emojis¶

All emojis that the guild owns.

Type: Tuple[Emoji, …]

stickers¶

All stickers that the guild owns.

New in version 2.0.

Type: Tuple[GuildSticker, …]

afk_timeout¶

The timeout to get sent to the AFK channel.

Type: int

id¶

The guild’s ID.

Type: int

owner_id¶

The guild owner’s ID.

Type: int

application_id¶

The application ID of the guild owner (if applicable).

New in version 2.0.

Changed in version 2.1: Renamed from owner_application_id to application_id.

Type: Optional[int]

unavailable¶

Indicates if the guild is unavailable. If this is True then the reliability of other attributes outside of Guild.id is slim and they might all be None. It is best to not do anything with the guild if it is unavailable.

Check the on_guild_unavailable() and on_guild_available() events.

Type: bool

max_presences¶

The maximum amount of presences for the guild.

Type: Optional[int]

max_members¶

The maximum amount of members for the guild.

Type: Optional[int]

max_video_channel_users¶

The maximum amount of users in a video channel.

New in version 1.4.

Type: Optional[int]

description¶

The guild’s description.

Type: Optional[str]

verification_level¶

The guild’s verification level.

Type: VerificationLevel

vanity_url_code¶

The guild’s vanity url code, if any

New in version 2.0.

Type: Optional[str]

explicit_content_filter¶

The guild’s explicit content filter.

Type: ContentFilter

default_notifications¶

The guild’s notification settings.

Type: NotificationLevel

features¶

A list of features that the guild has. The features that a guild can have are subject to arbitrary change by Discord.

Type: List[str]

premium_subscription_count¶

The number of “boosts” this guild currently has.

Type: int

preferred_locale¶

The preferred locale for the guild. Used when filtering Server Discovery results to a specific language.

Changed in version 2.0: This field is now an enum instead of a str.

Type: Locale

nsfw_level¶

The guild’s NSFW level.

New in version 2.0.

Type: NSFWLevel

mfa_level¶

The guild’s Multi-Factor Authentication requirement level.

Changed in version 2.0: This field is now an enum instead of an int.

Type: MFALevel

application_command_counts¶

A namedtuple representing the number of application commands in the guild, separated by type.

New in version 2.0.

Type: Optional[ApplicationCommandCounts]

approximate_member_count¶

The approximate number of members in the guild. This is None unless the guild is obtained using Client.fetch_guild() with with_counts=True.

New in version 2.0.

Type: Optional[int]

approximate_presence_count¶

The approximate number of members currently active in the guild. Offline members are excluded. This is None unless the guild is obtained using Client.fetch_guild() with with_counts=True.

New in version 2.0.

Type: Optional[int]

premium_progress_bar_enabled¶

Indicates if the guild has the premium (server boost) progress bar enabled.

New in version 2.0.

Type: bool

widget_enabled¶

Indicates if the guild has widget enabled.

New in version 2.0.

Type: bool

hub_type¶

The type of Student Hub the guild is, if applicable.

New in version 2.1.

Type: Optional[HubType]

property channels¶

A list of channels that belongs to this guild.

Type: Sequence[abc.GuildChannel]

property threads¶

A list of active threads that you have permission to view.

New in version 2.0.

Type: Sequence[Thread]

property large¶

Indicates if the guild is a ‘large’ guild.

A large guild is defined as having more than large_threshold count members, which for this library is set to the maximum of 250.

Type: bool

is_hub()¶: bool: Whether the guild is a Student Hub.

New in version 2.1.

property voice_channels¶

A list of voice channels that belongs to this guild.

This is sorted by the position and are in UI order from top to bottom.

Type: List[VoiceChannel]

property stage_channels¶

A list of stage channels that belongs to this guild.

New in version 1.7.

This is sorted by the position and are in UI order from top to bottom.

Type: List[StageChannel]

property me¶

Similar to Client.user except an instance of Member. This is essentially used to get the member version of yourself.

Changed in version 2.0: The type has been updated to be optional, which properly reflects cases where the current user is not a member of the guild, or the current user’s member object is not cached.

Type: Optional[Member]

is_joined()¶

Returns whether you are a full member of this guild.

May not be accurate for Guild s fetched over HTTP.

New in version 2.0.

Returns: Whether you are a member of this guild.
Return type: bool

property joined_at¶

Returns when you joined the guild.

New in version 2.0.

Type: datetime.datetime

property voice_client¶

Returns the VoiceProtocol associated with this guild, if any.

Type: Optional[VoiceProtocol]

property notification_settings¶

Returns the notification settings for the guild.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: GuildSettings

property text_channels¶

A list of text channels that belongs to this guild.

This is sorted by the position and are in UI order from top to bottom.

Type: List[TextChannel]

property categories¶

A list of categories that belongs to this guild.

This is sorted by the position and are in UI order from top to bottom.

Type: List[CategoryChannel]

property forums¶

A list of forum channels that belongs to this guild.

This is sorted by the position and are in UI order from top to bottom.

New in version 2.0.

Type: List[ForumChannel]

property directory_channels¶

A list of directory channels that belongs to this guild.

This is sorted by the position and are in UI order from top to bottom.

New in version 2.1.

Type: List[DirectoryChannel]

property directories¶

A list of directory channels that belongs to this guild.

An alias for Guild.directory_channels.

New in version 2.1.

Type: List[DirectoryChannel]

by_category()¶

Returns every CategoryChannel and their associated channels.

These channels and categories are sorted in the official Discord UI order.

If the channels do not have a category, then the first element of the tuple is None.

Returns: The categories and their associated channels.
Return type: List[Tuple[Optional[CategoryChannel], List[abc.GuildChannel]]]

get_channel_or_thread(channel_id, /)¶

Returns a channel or thread with the given ID.

New in version 2.0.

Parameters: channel_id (int) – The ID to search for.
Returns: The returned channel, thread, or None if not found.
Return type: Optional[Union[Thread, abc.GuildChannel]]

get_channel(channel_id, /)¶

Returns a channel with the given ID.

Note

This does not search for threads.

Changed in version 2.0: channel_id parameter is now positional-only.

Parameters: channel_id (int) – The ID to search for.
Returns: The returned channel or None if not found.
Return type: Optional[abc.GuildChannel]

get_thread(thread_id, /)¶

Returns a thread with the given ID.

Note

This does not always retrieve archived threads, as they are not retained in the internal cache. Use fetch_channel() instead.

New in version 2.0.

Parameters: thread_id (int) – The ID to search for.
Returns: The returned thread or None if not found.
Return type: Optional[Thread]

get_emoji(emoji_id, /)¶

Returns an emoji with the given ID.

New in version 2.0.

Parameters: emoji_id (int) – The ID to search for.
Returns: The returned Emoji or None if not found.
Return type: Optional[Emoji]

property system_channel¶

Returns the guild’s channel used for system messages.

If no channel is set, then this returns None.

Type: Optional[TextChannel]

property system_channel_flags¶

Returns the guild’s system channel settings.

Type: SystemChannelFlags

property rules_channel¶

Return’s the guild’s channel used for the rules. The guild must be a Community guild.

If no channel is set, then this returns None.

New in version 1.3.

Type: Optional[TextChannel]

property public_updates_channel¶

Return’s the guild’s channel where admins and moderators of the guilds receive notices from Discord. The guild must be a Community guild.

If no channel is set, then this returns None.

New in version 1.4.

Type: Optional[TextChannel]

property afk_channel¶

Returns the guild channel AFK users are moved to.

If no channel is set, then this returns None.

Type: Optional[VoiceChannel]

property widget_channel¶

Returns the widget channel of the guild.

If no channel is set, then this returns None.

New in version 2.0.

Type: Optional[Union[TextChannel, ForumChannel, VoiceChannel, StageChannel]]

property emoji_limit¶

The maximum number of emoji slots this guild has.

Type: int

property sticker_limit¶

The maximum number of sticker slots this guild has.

New in version 2.0.

Type: int

property bitrate_limit¶

The maximum bitrate for voice channels this guild can have.

Type: float

property filesize_limit¶

The maximum number of bytes files can have when uploaded to this guild.

Type: int

property members¶

A list of members that belong to this guild.

Type: Sequence[Member]

get_member(user_id, /)¶

Returns a member with the given ID.

Changed in version 2.0: user_id parameter is now positional-only.

Parameters: user_id (int) – The ID to search for.
Returns: The member or None if not found.
Return type: Optional[Member]

property premium_tier¶

The premium tier for this guild. Corresponds to “Server Boost Level” in the official UI. The number goes from 0 to 3 inclusive.

Type: int

property premium_subscribers¶

A list of members who have subscribed to (boosted) this guild.

Type: List[Member]

property roles¶

Returns a sequence of the guild’s roles in hierarchy order.

The first element of this sequence will be the lowest role in the hierarchy.

Type: Sequence[Role]

get_role(role_id, /)¶

Returns a role with the given ID.

Changed in version 2.0: role_id parameter is now positional-only.

Parameters: role_id (int) – The ID to search for.
Returns: The role or None if not found.
Return type: Optional[Role]

property default_role¶

Gets the @everyone role that all members have by default.

Type: Role

property premium_subscriber_role¶

Gets the premium subscriber role, AKA “boost” role, in this guild.

New in version 1.6.

Type: Optional[Role]

property stage_instances¶

Returns a sequence of the guild’s stage instances that are currently running.

New in version 2.0.

Type: Sequence[StageInstance]

get_stage_instance(stage_instance_id, /)¶

Returns a stage instance with the given ID.

New in version 2.0.

Parameters: stage_instance_id (int) – The ID to search for.
Returns: The stage instance or None if not found.
Return type: Optional[StageInstance]

property scheduled_events¶

Returns a sequence of the guild’s scheduled events.

New in version 2.0.

Type: Sequence[ScheduledEvent]

property scheduled_events_read_state¶

Returns the read state representing the guild’s scheduled events.

New in version 2.1.

Type: ReadState

property acked_scheduled_event¶

Returns the last scheduled event that the user has acknowledged.

New in version 2.1.

Type: Optional[ScheduledEvent]

get_scheduled_event(scheduled_event_id, /)¶

Returns a scheduled event with the given ID.

New in version 2.0.

Parameters: scheduled_event_id (int) – The ID to search for.
Returns: The scheduled event or None if not found.
Return type: Optional[ScheduledEvent]

property owner¶

The member that owns the guild.

Type: Optional[Member]

property icon¶

Returns the guild’s icon asset, if available.

Type: Optional[Asset]

property banner¶

Returns the guild’s banner asset, if available.

Type: Optional[Asset]

property splash¶

Returns the guild’s invite splash asset, if available.

Type: Optional[Asset]

property discovery_splash¶

Returns the guild’s discovery splash asset, if available.

Type: Optional[Asset]

property member_count¶

Returns the member count if available.

Warning

Due to a Discord limitation, this may not always be up-to-date and accurate.

Type: Optional[int]

property online_count¶

Returns the online member count.

New in version 1.9.

Warning

Due to a Discord limitation, this may not always be up-to-date and accurate.

Type: Optional[int]

property application_command_count¶

Returns the application command count, if available.

New in version 2.0.

Type: Optional[int]

property chunked¶

Returns a boolean indicating if the guild is “chunked”.

A chunked guild means that the guild member count is equal to the number of members stored in the internal members cache.

If this value returns False, then you should request for offline members.

Type: bool

property created_at¶

Returns the guild’s creation time in UTC.

Type: datetime.datetime

get_member_named(name, /)¶

Returns the first member found that matches the name provided.

The name is looked up in the following order:

Username#Discriminator (deprecated)
Username#0 (deprecated, only gets users that migrated from their discriminator)
Nickname
Global name
Username

If no member is found, None is returned.

Changed in version 2.0: name parameter is now positional-only.

Deprecated since version 2.1: Looking up users via discriminator due to Discord API change.

Parameters: name (str) – The name of the member to lookup.
Returns: The member in this guild with the associated name. If not found then None is returned.
Return type: Optional[Member]

await create_text_channel(name, *, reason=None, category=None, news=False, position=..., topic=..., slowmode_delay=..., nsfw=..., overwrites=..., default_auto_archive_duration=..., default_thread_slowmode_delay=...)¶

This function is a coroutine.

Creates a TextChannel for the guild.

Note that you must have manage_channels to create the channel.

The overwrites parameter can be used to create a ‘secret’ channel upon creation. This parameter expects a dict of overwrites with the target (either a Member or a Role) as the key and a PermissionOverwrite as the value.

Note

Creating a channel of a specified position will not update the position of other channels to follow suit. A follow-up call to edit() will be required to update the position of the channel in the channel list.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Examples

Creating a basic channel:

channel = await guild.create_text_channel('cool-channel')

Creating a “secret” channel:

overwrites = {
    guild.default_role: discord.PermissionOverwrite(read_messages=False),
    guild.me: discord.PermissionOverwrite(read_messages=True)
}

channel = await guild.create_text_channel('secret', overwrites=overwrites)

Parameters

name (str) – The channel’s name.
overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite to apply upon creation of a channel. Useful for creating secret channels.
category (Optional[CategoryChannel]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.
position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.
topic (str) – The new channel’s topic.
slowmode_delay (int) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is 21600.
nsfw (bool) – To mark the channel as NSFW or not.
news (bool) –
Whether to create the text channel as a news channel.

New in version 2.0.
default_auto_archive_duration (int) –
The default auto archive duration for threads created in the text channel (in minutes). Must be one of 60, 1440, 4320, or 10080.

New in version 2.0.
default_thread_slowmode_delay (int) –
The default slowmode delay in seconds for threads created in the text channel.

New in version 2.0.
reason (Optional[str]) – The reason for creating this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

TextChannel

await create_voice_channel(name, *, reason=None, category=None, position=..., bitrate=..., user_limit=..., rtc_region=..., video_quality_mode=..., overwrites=...)¶

This function is a coroutine.

This is similar to create_text_channel() except makes a VoiceChannel instead.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

name (str) – The channel’s name.
overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite to apply upon creation of a channel. Useful for creating secret channels.
category (Optional[CategoryChannel]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.
position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.
bitrate (int) – The channel’s preferred audio bitrate in bits per second.
user_limit (int) – The channel’s limit for number of members that can be in a voice channel.
rtc_region (Optional[str]) –
The region for the voice channel’s voice communication. A value of None indicates automatic voice region detection.

New in version 1.7.
video_quality_mode (VideoQualityMode) –
The camera video quality for the voice channel’s participants.

New in version 2.0.
reason (Optional[str]) – The reason for creating this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

VoiceChannel

await create_stage_channel(name, *, reason=None, category=None, position=..., bitrate=..., user_limit=..., rtc_region=..., video_quality_mode=..., overwrites=...)¶

This function is a coroutine.

This is similar to create_text_channel() except makes a StageChannel instead.

New in version 1.7.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

name (str) – The channel’s name.
overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite to apply upon creation of a channel. Useful for creating secret channels.
category (Optional[CategoryChannel]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.
position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.
bitrate (int) –
The channel’s preferred audio bitrate in bits per second.

New in version 2.0.
user_limit (int) –
The channel’s limit for number of members that can be in a voice channel.

New in version 2.0.
rtc_region (Optional[str]) –
The region for the voice channel’s voice communication. A value of None indicates automatic voice region detection.

New in version 2.0.
video_quality_mode (VideoQualityMode) –
The camera video quality for the voice channel’s participants.

New in version 2.0.
reason (Optional[str]) – The reason for creating this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

StageChannel

await create_category(name, *, overwrites=..., reason=None, position=...)¶

This function is a coroutine.

Same as create_text_channel() except makes a CategoryChannel instead.

Note

The category parameter is not supported in this function since categories cannot have categories.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

CategoryChannel

await create_category_channel(name, *, overwrites=..., reason=None, position=...)¶

This function is a coroutine.

Same as create_text_channel() except makes a CategoryChannel instead.

Note

The category parameter is not supported in this function since categories cannot have categories.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

CategoryChannel

await create_directory(name, *, reason=None, category=None, position=..., topic=..., overwrites=...)¶

This function is a coroutine.

This is similar to create_text_channel() except makes a DirectoryChannel instead.

New in version 2.1.

Parameters

name (str) – The channel’s name.
overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite to apply upon creation of a channel. Useful for creating secret channels.
category (Optional[CategoryChannel]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.
position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.
topic (str) – The new channel’s topic.
reason (Optional[str]) – The reason for creating this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

TextChannel

await create_directory_channel(name, *, reason=None, category=None, position=..., topic=..., overwrites=...)¶

This function is a coroutine.

This is similar to create_text_channel() except makes a DirectoryChannel instead.

New in version 2.1.

Parameters

name (str) – The channel’s name.
overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite to apply upon creation of a channel. Useful for creating secret channels.
category (Optional[CategoryChannel]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.
position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.
topic (str) – The new channel’s topic.
reason (Optional[str]) – The reason for creating this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

TextChannel

await create_forum(name, *, topic=..., position=..., category=None, slowmode_delay=..., nsfw=..., overwrites=..., reason=None, default_auto_archive_duration=..., default_thread_slowmode_delay=..., default_sort_order=..., default_reaction_emoji=..., default_layout=..., available_tags=...)¶

This function is a coroutine.

Similar to create_text_channel() except makes a ForumChannel instead.

New in version 2.0.

Parameters

name (str) – The channel’s name.
overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite to apply upon creation of a channel. Useful for creating secret channels.
topic (str) – The channel’s topic.
category (Optional[CategoryChannel]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.
position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.
nsfw (bool) – To mark the channel as NSFW or not.
slowmode_delay (int) – Specifies the slowmode rate limit for users in this channel, in seconds. The maximum possible value is 21600.
reason (Optional[str]) – The reason for creating this channel. Shows up in the audit log.
default_auto_archive_duration (int) – The default auto archive duration for threads created in the forum channel (in minutes). Must be one of 60, 1440, 4320, or 10080.
default_thread_slowmode_delay (int) – The default slowmode delay in seconds for threads created in this forum.
default_sort_order (ForumOrderType) – The default sort order for posts in this forum channel.
default_reaction_emoji (Union[Emoji, PartialEmoji, str]) – The default reaction emoji for threads created in this forum to show in the add reaction button.
default_layout (ForumLayoutType) – The default layout for posts in this forum.
available_tags (Sequence[ForumTag]) – The available tags for this forum channel.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

ForumChannel

await create_forum_channel(name, *, topic=..., position=..., category=None, slowmode_delay=..., nsfw=..., overwrites=..., reason=None, default_auto_archive_duration=..., default_thread_slowmode_delay=..., default_sort_order=..., default_reaction_emoji=..., default_layout=..., available_tags=...)¶

This function is a coroutine.

Similar to create_text_channel() except makes a ForumChannel instead.

New in version 2.0.

Parameters

name (str) – The channel’s name.
overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite to apply upon creation of a channel. Useful for creating secret channels.
topic (str) – The channel’s topic.
category (Optional[CategoryChannel]) – The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided.
position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.
nsfw (bool) – To mark the channel as NSFW or not.
slowmode_delay (int) – Specifies the slowmode rate limit for users in this channel, in seconds. The maximum possible value is 21600.
reason (Optional[str]) – The reason for creating this channel. Shows up in the audit log.
default_auto_archive_duration (int) – The default auto archive duration for threads created in the forum channel (in minutes). Must be one of 60, 1440, 4320, or 10080.
default_thread_slowmode_delay (int) – The default slowmode delay in seconds for threads created in this forum.
default_sort_order (ForumOrderType) – The default sort order for posts in this forum channel.
default_reaction_emoji (Union[Emoji, PartialEmoji, str]) – The default reaction emoji for threads created in this forum to show in the add reaction button.
default_layout (ForumLayoutType) – The default layout for posts in this forum.
available_tags (Sequence[ForumTag]) – The available tags for this forum channel.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.
TypeError – The permission overwrite information is not in proper form.

Returns

The channel that was just created.

Return type

ForumChannel

await leave()¶

This function is a coroutine.

Leaves the guild.

Note

You cannot leave a guild that you own, you must delete it instead via delete().

Raises: HTTPException – Leaving the guild failed.

await delete()¶

This function is a coroutine.

Deletes the guild. You must be the guild owner to delete the guild.

Raises

HTTPException – Deleting the guild failed.
Forbidden – You do not have permissions to delete the guild.

await edit(*, reason=..., name=..., description=..., icon=..., banner=..., splash=..., discovery_splash=..., community=..., afk_channel=..., owner=..., afk_timeout=..., default_notifications=..., verification_level=..., explicit_content_filter=..., vanity_code=..., system_channel=..., system_channel_flags=..., preferred_locale=..., rules_channel=..., public_updates_channel=..., premium_progress_bar_enabled=..., discoverable=..., invites_disabled=..., widget_enabled=..., widget_channel=..., mfa_level=...)¶

This function is a coroutine.

Edits the guild.

You must have manage_guild to edit the guild.

Changed in version 2.0: The newly updated guild is returned.

Changed in version 2.0: The region keyword parameter has been removed.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

name (str) – The new name of the guild.
description (Optional[str]) – The new description of the guild. Could be None for no description.
icon (bytes) – A bytes-like object representing the icon. Only PNG/JPEG is supported. GIF is only available to guilds that contain ANIMATED_ICON in Guild.features. Could be None to denote removal of the icon.
banner (bytes) – A bytes-like object representing the banner. Only PNG/JPEG is supported. GIF is only available to guilds that contain ANIMATED_BANNER in Guild.features. Could be None to denote removal of the banner. This is only available to guilds that contain BANNER in Guild.features.
splash (bytes) – A bytes-like object representing the invite splash. Only PNG/JPEG supported. Could be None to denote removing the splash. This is only available to guilds that contain INVITE_SPLASH in Guild.features.
discovery_splash (bytes) –
A bytes-like object representing the discovery splash. Only PNG/JPEG supported. Could be None to denote removing the splash. This is only available to guilds that contain DISCOVERABLE in Guild.features.

New in version 2.0.
community (bool) –
Whether the guild should be a Community guild. If set to True, both rules_channel and public_updates_channel parameters are required.

New in version 2.0.
afk_channel (Optional[VoiceChannel]) – The new channel that is the AFK channel. Could be None for no AFK channel.
afk_timeout (int) – The number of seconds until someone is moved to the AFK channel.
owner (Member) – The new owner of the guild to transfer ownership to. Note that you must be owner of the guild to do this.
verification_level (VerificationLevel) – The new verification level for the guild.
default_notifications (NotificationLevel) – The new default notification level for the guild.
explicit_content_filter (ContentFilter) – The new explicit content filter for the guild.
vanity_code (str) – The new vanity code for the guild.
system_channel (Optional[TextChannel]) – The new channel that is used for the system channel. Could be None for no system channel.
system_channel_flags (SystemChannelFlags) – The new system channel settings to use with the new system channel.
preferred_locale (Locale) –
The new preferred locale for the guild. Used as the primary language in the guild.

Changed in version 2.0: Now accepts an enum instead of str.
rules_channel (Optional[TextChannel]) –
The new channel that is used for rules. This is only available to guilds that contain COMMUNITY in Guild.features. Could be None for no rules channel.

New in version 1.4.
public_updates_channel (Optional[TextChannel]) –
The new channel that is used for public updates from Discord. This is only available to guilds that contain COMMUNITY in Guild.features. Could be None for no public updates channel.

New in version 1.4.
premium_progress_bar_enabled (bool) –
Whether the premium AKA server boost level progress bar should be enabled for the guild.

New in version 2.0.
discoverable (bool) –
Whether server discovery is enabled for this guild.

New in version 2.0.
invites_disabled (bool) –
Whether joining via invites should be disabled for the guild.

New in version 2.0.
widget_enabled (bool) –
Whether to enable the widget for the guild.

New in version 2.0.
widget_channel (Optional[abc.Snowflake]) –
The new widget channel. None removes the widget channel.

New in version 2.0.
mfa_level (MFALevel) –
The guild’s new Multi-Factor Authentication requirement level. Note that you must be owner of the guild to do this.

New in version 2.0.
reason (Optional[str]) – The reason for editing this guild. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit the guild.
HTTPException – Editing the guild failed.
ValueError – The image format passed in to icon is invalid. It must be PNG or JPG. This is also raised if you are not the owner of the guild and request an ownership transfer.
TypeError – The type passed to the default_notifications, verification_level, explicit_content_filter, system_channel_flags, or mfa_level parameter was of the incorrect type.

Returns

The newly updated guild. Note that this has the same limitations as mentioned in Client.fetch_guild() and may not have full data.

Return type

await top_channels()¶

This function is a coroutine.

Retrieves the top 10 most read channels in the guild. Channels are returned in order of descending usage.

Note

For guilds without many members, this may return an empty list.

New in version 2.1.

Raises: HTTPException – Retrieving the top channels failed.
Returns: The top 10 most read channels. Falls back to PartialMessageable if the channel is not found in cache.
Return type: List[Union[TextChannel, VoiceChannel, StageChannel, PartialMessageable]]

await webhook_channels()¶

This function is a coroutine.

Retrieves the channels that the current user can create webhooks in for the guild.

New in version 2.1.

Raises: HTTPException – Retrieving the webhook channels failed.
Returns: The channels that the current user can create webhooks in. Falls back to PartialMessageable if the channel is not found in cache. Any PartialMessageable will have its PartialMessageable.name filled in.
Return type: List[Union[TextChannel, VoiceChannel, StageChannel, PartialMessageable]]

await fetch_channels()¶

This function is a coroutine.

Retrieves all abc.GuildChannel that the guild has.

Note

This method is an API call. For general usage, consider channels instead.

New in version 1.2.

Raises

InvalidData – An unknown channel type was received from Discord.
HTTPException – Retrieving the channels failed.

Returns

All channels in the guild.

Return type

Sequence[abc.GuildChannel]

await fetch_member(member_id, /)¶

This function is a coroutine.

Retrieves a Member from a guild ID, and a member ID.

Note

This method is an API call. If you have member cache, consider get_member() instead.

Changed in version 2.0: member_id parameter is now positional-only.

Parameters

member_id (int) – The member’s ID to fetch from.

Raises

Forbidden – You do not have access to the guild.
HTTPException – Fetching the member failed.
NotFound – The member could not be found.

Returns

The member from the member ID.

Return type

Member

await fetch_member_profile(member_id, /, *, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

Retrieves a MemberProfile from a guild ID, and a member ID.

New in version 2.0.

Parameters

member_id (int) – The ID of the member to fetch their profile for.
with_mutual_guilds (bool) – Whether to fetch mutual guilds. This fills in MemberProfile.mutual_guilds.
with_mutual_friends_count (bool) – Whether to fetch the number of mutual friends. This fills in MemberProfile.mutual_friends_count.
with_mutual_friends (bool) – Whether to fetch mutual friends. This fills in MemberProfile.mutual_friends and MemberProfile.mutual_friends_count, but requires an extra API call.

Raises

NotFound – A user with this ID does not exist.
Forbidden – You do not have a mutual with this user, and and the user is not a bot.
HTTPException – Fetching the profile failed.
InvalidData – The member is not in this guild or has blocked you.

Returns

The profile of the member.

Return type

MemberProfile

await fetch_ban(user)¶

This function is a coroutine.

Retrieves the BanEntry for a user.

You must have ban_members to get this information.

Parameters

user (abc.Snowflake) – The user to get ban information from.

Raises

Forbidden – You do not have proper permissions to get the information.
NotFound – This user is not banned.
HTTPException – An error occurred while fetching the information.

Returns

The BanEntry object for the specified user.

Return type

BanEntry

await fetch_channel(channel_id, /)¶

This function is a coroutine.

Retrieves a abc.GuildChannel or Thread with the specified ID.

Note

This method is an API call. For general usage, consider get_channel_or_thread() instead.

New in version 2.0.

Raises

InvalidData – An unknown channel type was received from Discord or the guild the channel belongs to is not the same as the one in this object points to.
HTTPException – Retrieving the channel failed.
NotFound – Invalid Channel ID.
Forbidden – You do not have permission to fetch this channel.

Returns

The channel from the ID.

Return type

Union[abc.GuildChannel, Thread]

async for ... in bans(*, limit=1000, before=..., after=..., paginate=True)¶

Retrieves an asynchronous iterator of the users that are banned from the guild as a BanEntry.

You must have ban_members to get this information.

Changed in version 2.0: Due to a breaking change in Discord’s API, this now returns a paginated iterator instead of a list.

Examples

Usage

async for entry in guild.bans(limit=150):
    print(entry.user, entry.reason)

Flattening into a list

bans = [entry async for entry in guild.bans(limit=2000)]
# bans is now a list of BanEntry...

All parameters are optional.

Parameters

limit (Optional[int]) – The number of bans to retrieve. If None, it retrieves every ban in the guild. Note, however, that this would make it a slow operation. Defaults to 1000.
before (abc.Snowflake) – Retrieves bans before this user.
after (abc.Snowflake) – Retrieve bans after this user.
paginate (bool) –
Whether to paginate the results. If False, all bans are fetched with a single request and yielded, limit is ignored, and before and after must not be provided.

New in version 2.0.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.
TypeError – Both after and before were provided, as Discord does not support this type of pagination.

Yields

BanEntry – The ban entry of the banned user.

search(content=..., *, limit=25, offset=0, before=..., after=..., include_nsfw=..., channels=..., authors=..., author_types=..., mentions=..., mention_everyone=..., pinned=..., has=..., embed_types=..., embed_providers=..., link_hostnames=..., attachment_filenames=..., attachment_extensions=..., application_commands=..., oldest_first=False, most_relevant=False)¶

Returns an asynchronous iterator that enables searching the guild’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

counter = 0
async for message in guild.search('hi', limit=200):
    if message.author == client.user:
        counter += 1

Flattening into a list:

messages = [message async for message in guild.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (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 (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.
nsfw_allowed (bool) – Whether to include messages from NSFW channels. Defaults to nsfw_allowed.
channels (List[Union[abc.GuildChannel, abc.PrivateChannel, Thread]]) – The channels to filter by.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[abc.ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.

Yields

Message – The message with the message data parsed.

await prune_members(*, days, compute_prune_count=True, roles=..., reason=None)¶

This function is a coroutine.

Prunes the guild from its inactive members.

The inactive members are denoted if they have not logged on in days number of days and they have no roles.

You must have kick_members to do this.

To check how many members you would prune without actually pruning, see the estimate_pruned_members() function.

To prune members that have specific roles see the roles parameter.

Changed in version 1.4: The roles keyword-only parameter was added.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

days (int) – The number of days before counting as inactive.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.
compute_prune_count (bool) – Whether to compute the prune count. This defaults to True which makes it prone to timeouts in very large guilds. In order to prevent timeouts, you must set this to False. If this is set to False, then this function will always return None.
roles (List[abc.Snowflake]) – A list of abc.Snowflake that represent roles to include in the pruning process. If a member has a role that is not specified, they’ll be excluded.

Raises

Forbidden – You do not have permissions to prune members.
HTTPException – An error occurred while pruning members.
TypeError – An integer was not passed for days.

Returns

The number of members pruned. If compute_prune_count is False then this returns None.

Return type

Optional[int]

await templates()¶

This function is a coroutine.

Gets the list of templates from this guild.

You must have manage_guild to do this.

New in version 1.7.

Raises: Forbidden – You don’t have permissions to get the templates.
Returns: The templates for this guild.
Return type: List[Template]

await webhooks()¶

This function is a coroutine.

Gets the list of webhooks from this guild.

You must have manage_webhooks to do this.

Raises: Forbidden – You don’t have permissions to get the webhooks.
Returns: The webhooks for this guild.
Return type: List[Webhook]

await estimate_pruned_members(*, days, roles=...)¶

This function is a coroutine.

Similar to prune_members() except instead of actually pruning members, it returns how many members it would prune from the guild had it been called.

Changed in version 2.0: The returned value can be None.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

days (int) – The number of days before counting as inactive.
roles (List[abc.Snowflake]) –
A list of abc.Snowflake that represent roles to include in the estimate. If a member has a role that is not specified, they’ll be excluded.

New in version 1.7.

Raises

Forbidden – You do not have permissions to prune members.
HTTPException – An error occurred while fetching the prune members estimate.
TypeError – An integer was not passed for days.

Returns

The number of members estimated to be pruned.

Return type

Optional[int]

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from the guild.

You must have manage_guild to get this information.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

await create_template(*, name, description=...)¶

This function is a coroutine.

Creates a template for the guild.

You must have manage_guild to do this.

New in version 1.7.

Parameters

name (str) – The name of the template.
description (str) – The description of the template.

await create_integration(*, type, id, reason=None)¶

This function is a coroutine.

Attaches an integration to the guild. This “enables” an existing integration.

You must have manage_guild to do this.

New in version 1.4.

Parameters

type (str) – The integration type (e.g. Twitch).
id (int) – The integration ID.
reason (Optional[str]) –
The reason for creating this integration. Shows up on the audit log.

New in version 2.0.

Raises

Forbidden – You do not have permission to create the integration.
HTTPException – The account could not be found.

await integrations(*, has_commands=False)¶

This function is a coroutine.

Returns a list of all integrations attached to the guild.

You must have manage_guild to do this.

New in version 1.4.

Parameters

has_commands (bool) –

Whether to only return integrations that have commands registered.

New in version 2.1.

Raises

Forbidden – You do not have permission to create the integration.
HTTPException – Fetching the integrations failed.

Returns

The list of integrations that are attached to the guild.

Return type

List[Integration]

await application_commands()¶

This function is a coroutine.

Returns a list of all application commands available in the guild.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises: HTTPException – Fetching the commands failed.
Returns: The list of application commands that are available in the guild.
Return type: List[Union[SlashCommand, UserCommand, MessageCommand]]

await fetch_stickers()¶

This function is a coroutine.

Retrieves a list of all Stickers for the guild.

New in version 2.0.

Note

This method is an API call. For general usage, consider stickers instead.

Raises: HTTPException – An error occurred fetching the stickers.
Returns: The retrieved stickers.
Return type: List[GuildSticker]

await fetch_sticker(sticker_id, /)¶

This function is a coroutine.

Retrieves a custom Sticker from the guild.

New in version 2.0.

Note

This method is an API call. For general usage, consider iterating over stickers instead.

Parameters

sticker_id (int) – The sticker’s ID.

Raises

NotFound – The sticker requested could not be found.
HTTPException – An error occurred fetching the sticker.

Returns

The retrieved sticker.

Return type

GuildSticker

await create_sticker(*, name, description, emoji, file, reason=None)¶

This function is a coroutine.

Creates a Sticker for the guild.

You must have manage_emojis_and_stickers to do this.

New in version 2.0.

Parameters

name (str) – The sticker name. Must be at least 2 characters.
description (str) – The sticker’s description.
emoji (str) – The name of a unicode emoji that represents the sticker’s expression.
file (File) – The file of the sticker to upload.
reason (str) – The reason for creating this sticker. Shows up on the audit log.

Raises

Forbidden – You are not allowed to create stickers.
HTTPException – An error occurred creating a sticker.

Returns

The created sticker.

Return type

GuildSticker

await delete_sticker(sticker, /, *, reason=None)¶

This function is a coroutine.

Deletes the custom Sticker from the guild.

You must have manage_emojis_and_stickers to do this.

New in version 2.0.

Parameters

sticker (abc.Snowflake) – The sticker you are deleting.
reason (Optional[str]) – The reason for deleting this sticker. Shows up on the audit log.

Raises

Forbidden – You are not allowed to delete stickers.
HTTPException – An error occurred deleting the sticker.

await subscribed_scheduled_events()¶

This function is a coroutine.

Retrieves a list of all scheduled events that the current user is subscribed to.

New in version 2.1.

Raises: HTTPException – Retrieving the subscribed scheduled events failed.
Returns: The subscribed scheduled events. Falls back to an object if the event is not found in cache.
Return type: List[Union[ScheduledEvent, Object]]

await fetch_scheduled_events(*, with_counts=True)¶

This function is a coroutine.

Retrieves a list of all scheduled events for the guild.

New in version 2.0.

Parameters: with_counts (bool) – Whether to include the number of users that are subscribed to the event. Defaults to True.
Raises: HTTPException – Retrieving the scheduled events failed.
Returns: The scheduled events.
Return type: List[ScheduledEvent]

await fetch_scheduled_event(scheduled_event_id, /, *, with_counts=True)¶

This function is a coroutine.

Retrieves a scheduled event from the guild.

New in version 2.0.

Parameters

scheduled_event_id (int) – The scheduled event ID.
with_counts (bool) – Whether to include the number of users that are subscribed to the event. Defaults to True.

Raises

NotFound – The scheduled event was not found.
HTTPException – Retrieving the scheduled event failed.

Returns

The scheduled event.

Return type

await create_scheduled_event(*, name, start_time, entity_type=..., privacy_level=<PrivacyLevel.closed: 2>, channel=..., location=..., end_time=..., description=..., image=..., directory_broadcast=False, reason=None)¶

This function is a coroutine.

Creates a scheduled event for the guild.

You must have manage_events to do this.

New in version 2.0.

Parameters

name (str) – The name of the scheduled event.
description (str) – The description of the scheduled event.
channel (Optional[abc.Snowflake]) –
The channel to send the scheduled event to. If the channel is a StageInstance or VoiceChannel then it automatically sets the entity type.

Required if entity_type is either EntityType.voice or EntityType.stage_instance.
start_time (datetime.datetime) – The scheduled start time of the scheduled event. This must be a timezone-aware datetime object. Consider using utils.utcnow().
end_time (datetime.datetime) –
The scheduled end time of the scheduled event. This must be a timezone-aware datetime object. Consider using utils.utcnow().

Required if the entity type is EntityType.external.
privacy_level (PrivacyLevel) – The privacy level of the scheduled event.
entity_type (EntityType) – The entity type of the scheduled event. If the channel is a StageInstance or VoiceChannel then this is automatically set to the appropriate entity type. If no channel is passed then the entity type is assumed to be EntityType.external
image (bytes) – The image of the scheduled event.
location (str) –
The location of the scheduled event.

Required if the entity_type is EntityType.external.
directory_broadcast (bool) –
Whether to broadcast the scheduled event to the directories the guild is in. You should first check eligibility with directory_broadcast_eligibility().

New in version 2.1.
reason (Optional[str]) – The reason for creating this scheduled event. Shows up on the audit log.

Raises

TypeError – image was not a bytes-like object, or privacy_level was not a PrivacyLevel, or entity_type was not an EntityType, status was not an EventStatus, or an argument was provided that was incompatible with the provided entity_type.
ValueError – start_time or end_time was not a timezone-aware datetime object.
Forbidden – You are not allowed to create scheduled events.
HTTPException – Creating the scheduled event failed.

Returns

The created scheduled event.

Return type

await top_emojis()¶

This function is a coroutine.

Retrieves the most used custom emojis in the guild. Emojis are returned in order of descending usage.

New in version 2.0.

Raises: HTTPException – Retrieving the top emojis failed.
Returns: The most used emojis. Falls back to a bare PartialEmoji if the emoji is not found in cache.
Return type: List[Union[Emoji, PartialEmoji]]

await fetch_emojis()¶

This function is a coroutine.

Retrieves all custom Emojis from the guild.

Note

This method is an API call. For general usage, consider emojis instead.

Raises: HTTPException – An error occurred fetching the emojis.
Returns: The retrieved emojis.
Return type: List[Emoji]

await fetch_emoji(emoji_id, /)¶

This function is a coroutine.

Retrieves a custom Emoji from the guild.

Note

This method is an API call. For general usage, consider iterating over emojis instead.

Changed in version 2.0: emoji_id parameter is now positional-only.

Parameters

emoji_id (int) – The emoji’s ID.

Raises

NotFound – The emoji requested could not be found.
HTTPException – An error occurred fetching the emoji.

Returns

The retrieved emoji.

Return type

Emoji

await create_custom_emoji(*, name, image, roles=..., reason=None)¶

This function is a coroutine.

Creates a custom Emoji for the guild.

There is currently a limit of 50 static and animated emojis respectively per guild, unless the guild has the MORE_EMOJI feature which extends the limit to 200.

You must have manage_emojis to do this.

Parameters

name (str) – The emoji name. Must be at least 2 characters.
image (bytes) – The bytes-like object representing the image data to use. Only JPG, PNG and GIF images are supported.
roles (List[Role]) – A list of Roles that can use this emoji. Leave empty to make it available to everyone.
reason (Optional[str]) – The reason for creating this emoji. Shows up on the audit log.

Raises

Forbidden – You are not allowed to create emojis.
HTTPException – An error occurred creating an emoji.

Returns

The created emoji.

Return type

Emoji

await delete_emoji(emoji, /, *, reason=None)¶

This function is a coroutine.

Deletes the custom Emoji from the guild.

You must have manage_emojis to do this.

Changed in version 2.0: emoji parameter is now positional-only.

Parameters

emoji (abc.Snowflake) – The emoji you are deleting.
reason (Optional[str]) – The reason for deleting this emoji. Shows up on the audit log.

Raises

Forbidden – You are not allowed to delete emojis.
HTTPException – An error occurred deleting the emoji.

await fetch_roles()¶

This function is a coroutine.

Retrieves all Role that the guild has.

Note

This method is an API call. For general usage, consider roles instead.

New in version 1.3.

Raises: HTTPException – Retrieving the roles failed.
Returns: All roles in the guild.
Return type: List[Role]

await create_role(*, name=..., permissions=..., color=..., colour=..., hoist=..., display_icon=..., mentionable=..., icon=..., emoji=..., reason=None)¶

This function is a coroutine.

Creates a Role for the guild.

All fields are optional.

You must have manage_roles to do this.

Changed in version 1.6: Can now pass int to colour keyword-only parameter.

New in version 2.0: The display_icon keyword-only parameter was added.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

name (str) – The role name. Defaults to ‘new role’.
permissions (Permissions) – The permissions to have. Defaults to no permissions.
colour (Union[Colour, int]) – The colour for the role. Defaults to Colour.default(). This is aliased to color as well.
hoist (bool) – Indicates if the role should be shown separately in the member list. Defaults to False.
display_icon (Union[bytes, str]) – A bytes-like object representing the icon or str representing unicode emoji that should be used as a role icon. Only PNG/JPEG is supported. This is only available to guilds that contain ROLE_ICONS in features.
mentionable (bool) – Indicates if the role should be mentionable by others. Defaults to False.
icon (Optional[bytes]) – A bytes-like object representing the icon. Only PNG/JPEG is supported. Could be None to denote removal of the icon.
emoji (Optional[PartialEmoji]) – An emoji to show next to the role. Only unicode emojis are supported.
reason (Optional[str]) – The reason for creating this role. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to create the role.
HTTPException – Creating the role failed.
TypeError – An invalid keyword argument was given.
ValueError – unicode_emoji was the wrong type.

Returns

The newly created role.

Return type

Role

await edit_role_positions(positions, *, reason=None)¶

This function is a coroutine.

Bulk edits a list of Role in the guild.

You must have manage_roles to do this.

New in version 1.4.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Example

positions = {
    bots_role: 1, # penultimate role
    tester_role: 2,
    admin_role: 6
}

await guild.edit_role_positions(positions=positions)

Parameters

positions – A dict of Role to int to change the positions of each given role.
reason (Optional[str]) – The reason for editing the role positions. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to move the roles.
HTTPException – Moving the roles failed.
TypeError – An invalid keyword argument was given.

Returns

A list of all the roles in the guild.

Return type

List[Role]

await role_member_counts()¶

This function is a coroutine.

Retrieves the number of members in each role the guild has.

New in version 2.1.

Raises

Forbidden – You do not have permissions to get the member counts.
HTTPException – Getting the member counts failed.

Returns

A mapping of the role to the number of members in that role.

Return type

Dict[Role, int]

await kick(user, *, reason=None)¶

This function is a coroutine.

Kicks a user from the guild.

The user must meet the abc.Snowflake abc.

You must have kick_members to do this.

Parameters

user (abc.Snowflake) – The user to kick from their guild.
reason (Optional[str]) – The reason the user got kicked.

Raises

Forbidden – You do not have the proper permissions to kick.
HTTPException – Kicking failed.

await ban(user, *, reason=None, delete_message_days=..., delete_message_seconds=...)¶

This function is a coroutine.

Bans a user from the guild.

The user must meet the abc.Snowflake abc.

You must have ban_members to do this.

Parameters

user (abc.Snowflake) – The user to ban from their guild.
delete_message_days (int) –
The number of days worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 7. Defaults to 1 day if neither delete_message_days nor delete_message_seconds are passed.

Deprecated since version 2.0.
delete_message_seconds (int) –
The number of seconds worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 604800 (7 days). Defaults to 1 day if neither delete_message_days nor delete_message_seconds are passed.

New in version 2.0.
reason (Optional[str]) – The reason the user got banned.

Raises

NotFound – The requested user was not found.
Forbidden – You do not have the proper permissions to ban.
HTTPException – Banning failed.
TypeError – You specified both delete_message_days and delete_message_seconds.

await unban(user, *, reason=None)¶

This function is a coroutine.

Unbans a user from the guild.

The user must meet the abc.Snowflake abc.

You must have ban_members to do this.

Parameters

user (abc.Snowflake) – The user to unban.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

NotFound – The requested unban was not found.
Forbidden – You do not have the proper permissions to unban.
HTTPException – Unbanning failed.

property vanity_url¶

The Discord vanity invite URL for this guild, if available.

New in version 2.0.

Type: Optional[str]

await vanity_invite()¶

This function is a coroutine.

Returns the guild’s special vanity invite.

The guild must have VANITY_URL in features.

You must have manage_guild to do this.as well.

Raises

Forbidden – You do not have the proper permissions to get this.
HTTPException – Retrieving the vanity invite failed.

Returns

The special vanity invite. If None then the guild does not have a vanity invite set.

Return type

Optional[Invite]

async for ... in audit_logs(*, limit=100, before=..., after=..., oldest_first=..., user=..., action=...)¶

Returns an asynchronous iterator that enables receiving the guild’s audit logs.

You must have view_audit_log to do this.

Examples

Getting the first 100 entries:

async for entry in guild.audit_logs(limit=100):
    print(f'{entry.user} did {entry.action} to {entry.target}')

Getting entries for a specific action:

async for entry in guild.audit_logs(action=discord.AuditLogAction.ban):
    print(f'{entry.user} banned {entry.target}')

Getting entries made by a specific user:

entries = [entry async for entry in guild.audit_logs(limit=None, user=guild.me)]
await channel.send(f'I made {len(entries)} moderation actions.')

Parameters

limit (Optional[int]) – The number of entries to retrieve. If None retrieve all entries.
before (Union[abc.Snowflake, datetime.datetime]) – Retrieve entries before this date or entry. 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 (Union[abc.Snowflake, datetime.datetime]) – Retrieve entries after this date or entry. 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.
oldest_first (bool) – If set to True, return entries in oldest->newest order. Defaults to True if after is specified, otherwise False.
user (abc.Snowflake) – The moderator to filter entries from.
action (AuditLogAction) – The action to filter with.

Raises

Forbidden – You are not allowed to fetch audit logs
HTTPException – An error occurred while fetching the audit logs.

Yields

AuditLogEntry – The audit log entry.

await ack()¶

This function is a coroutine.

Marks every message in this guild as read.

Raises: HTTPException – Acking failed.

await widget()¶

This function is a coroutine.

Returns the widget of the guild.

Note

The guild must have the widget enabled to get this information.

Raises

Forbidden – The widget for this guild is disabled.
HTTPException – Retrieving the widget failed.

Returns

The guild’s widget.

Return type

Widget

await edit_widget(*, enabled=..., channel=..., reason=None)¶

This function is a coroutine.

Edits the widget of the guild. This can also be done with edit.

You must have manage_guild to do this.

New in version 2.0.

Parameters

enabled (bool) – Whether to enable the widget for the guild.
channel (Optional[Snowflake]) – The new widget channel. None removes the widget channel.
reason (Optional[str]) – The reason for editing this widget. Shows up on the audit log.

Raises

Forbidden – You do not have permission to edit the widget.
HTTPException – Editing the widget failed.

await welcome_screen()¶

This function is a coroutine.

Returns the guild’s welcome screen.

You must have manage_guild permission to use this.

Note

The guild must have the welcome screen enabled to get this information.

New in version 2.0.

Raises

NotFound – The guild does not have a welcome screen.
Forbidden – You do not have manage_guild.
HTTPException – Retrieving the welcome screen failed.

Returns

The welcome screen.

Return type

WelcomeScreen

await edit_welcome_screen(*, description=..., welcome_channels=..., enabled=..., reason=None)¶

This function is a coroutine.

Edit the welcome screen.

Welcome channels can only accept custom emojis if Guild.premium_tier is level 2 or above.

You must have manage_guild in the guild to do this.

All parameters are optional.

New in version 2.0.

Usage:

rules_channel = guild.get_channel(12345678)
announcements_channel = guild.get_channel(87654321)

custom_emoji = utils.get(guild.emojis, name='loudspeaker')

await welcome_screen.edit(
    description='This is a very cool community server!',
    welcome_channels=[
        WelcomeChannel(channel=rules_channel, description='Read the rules!', emoji='👨‍🏫'),
        WelcomeChannel(channel=announcements_channel, description='Watch out for announcements!', emoji=custom_emoji),
    ]
)

Parameters

enabled (bool) – Whether the welcome screen will be shown.
description (str) – The welcome screen’s description.
welcome_channels (Optional[List[WelcomeChannel]]) – The welcome channels (in order).
reason (Optional[str]) – The reason for editing the welcome screen. Shows up on the audit log.

Raises

NotFound – The guild does not have a welcome screen.
HTTPException – Editing the welcome screen failed failed.
Forbidden – You don’t have permissions to edit the welcome screen.

await applications(*, with_team=False, type=None, channel=None)¶

This function is a coroutine.

Returns the list of applications that are attached to this guild.

New in version 2.0.

Parameters

with_team (bool) – Whether to include the team of the application.
type (ApplicationType) – The type of application to restrict the returned applications to.

Raises

HTTPException – Fetching the applications failed.

Returns

The applications that belong to this guild.

Return type

List[PartialApplication]

await premium_subscriptions()¶

This function is a coroutine.

Returns the list of premium subscriptions (boosts) for this guild.

New in version 2.0.

Raises

Forbidden – You do not have permission to get the premium guild subscriptions.
HTTPException – Fetching the premium guild subscriptions failed.

Returns

The premium guild subscriptions.

Return type

List[PremiumGuildSubscription]

await apply_premium_subscription_slots(*subscription_slots)¶

This function is a coroutine.

Applies premium subscription slots to the guild (boosts the guild).

New in version 2.0.

Parameters: *subscription_slots (PremiumGuildSubscriptionSlot) – The subscription slots to apply.
Raises: HTTPException – Applying the premium subscription slots failed.

await entitlements(*, with_sku=True, with_application=True, exclude_deleted=False)¶

This function is a coroutine.

Returns the list of entitlements for this guild.

New in version 2.0.

Parameters

with_sku (bool) – Whether to include the SKU information in the returned entitlements.
with_application (bool) – Whether to include the application in the returned entitlements’ SKUs.
exclude_deleted (bool) – Whether to exclude deleted entitlements.

Raises

HTTPException – Retrieving the entitlements failed.

Returns

The guild’s entitlements.

Return type

List[Entitlement]

await price_tiers()¶

This function is a coroutine.

Returns the list of price tiers available for use in this guild.

New in version 2.0.

Raises: HTTPException – Fetching the price tiers failed.
Returns: The available price tiers.
Return type: List[int]

await fetch_price_tier(price_tier, /)¶

This function is a coroutine.

Returns a mapping of currency to price for the given price tier.

New in version 2.0.

Parameters

price_tier (int) – The price tier to retrieve.

Raises

NotFound – The price tier does not exist.
HTTPException – Fetching the price tier failed.

Returns

The price tier mapping.

Return type

Dict[str, int]

await chunk(*, cache=True)¶

This function is a coroutine.

Requests all members that belong to this guild.

This is a websocket operation and can be slow.

New in version 2.0.

Note

For guilds with more than 1,000 members, this requires the manage_roles, kick_members, or ban_members permissions. For guilds with less than 1,000 members, this requires at least one channel that is viewable by every member.

Parameters

cache (bool) – Whether to cache the members as well.

Raises

ClientException – This guild is not subscribed to. This guild cannot be chunked or chunking failed.
InvalidData – Did not receive a response from the Gateway.

Returns

The members that belong to this guild.

Return type

List[Member]

await fetch_members(channels=..., *, cache=False, force_scraping=False, delay=0)¶

This function is a coroutine.

Retrieves all members that belong to this guild. This is a websocket operation and can be slow.

This does not enable you to receive events for the guild, and can be called multiple times.

New in version 2.0.

Note

If you have any of kick_members, ban_members, or manage_roles, members will be requested normally (including offline members). Else, this will scrape the member sidebar, which is slower and may not include offline members.

Parameters

channels (List[Snowflake]) – A list of up to 5 channels to request members from. More channels make it faster. This only applies when scraping from the member sidebar.
cache (bool) – Whether to cache the members as well. The cache will not be kept updated.
force_scraping (bool) – Whether to scrape the member sidebar regardless of permissions.
delay (float) – The time in seconds to wait between requests. This only applies when scraping from the member sidebar.

Raises

ClientException – Fetching members failed.
InvalidData – Did not receive a response from the gateway.

Returns

The members that belong to this guild (offline members may not be included).

Return type

List[Member]

await query_members(query=None, *, limit=5, user_ids=None, presences=True, cache=True, subscribe=False)¶

This function is a coroutine.

Request members of this guild whose username or nickname starts with the given query. This is a websocket operation.

Note

This is preferrable to using fetch_member() as the client uses it quite often, and you can also request presence.

New in version 1.3.

Changed in version 2.0: The function now raises a TypeError instead of ValueError.

Parameters

query (Optional[str]) – The string that the username or nickname should start with.
limit (int) – The maximum number of members to send back. This must be a number between 5 and 100.
presences (bool) –
Whether to request for presences to be provided. This defaults to True.

New in version 1.6.
cache (bool) – Whether to cache the members internally. This makes operations such as get_member() work for those that matched. The cache will not be kept updated unless subscribe is set to True.
user_ids (Optional[List[int]]) –
List of user IDs to search for. If the user ID is not in the guild then it won’t be returned.

New in version 1.4.
subscribe (bool) –
Whether to subscribe to the resulting members. This will keep their member info and presence updated. This requires another request, and defaults to False.

See also subscribe_to().

New in version 2.0.

Raises

asyncio.TimeoutError – The query timed out waiting for the members.
TypeError – Invalid parameters were passed to the function.

Returns

The list of members that have matched the query.

Return type

List[Member]

await query_recent_members(query=None, *, limit=1000, cache=True)¶

This function is a coroutine.

Request the most recent 10,000 joined members of this guild. This is a websocket operation.

Note

This operation does not return presences.

New in version 2.1.

Parameters

query (Optional[str]) – The string that the username or nickname should start with, if any.
limit (int) – The maximum number of members to send back. This must be a number between 1 and 10,000.
cache (bool) – Whether to cache the members internally. This makes operations such as get_member() work for those that matched. The cache will not be kept updated.

Raises

asyncio.TimeoutError – The query timed out waiting for the members.
TypeError – Invalid parameters were passed to the function.

Returns

The list of members that have matched the query.

Return type

List[Member]

await change_voice_state(*, channel, self_mute=False, self_deaf=False, self_video=False, preferred_region=...)¶

This function is a coroutine.

Changes client’s voice state in the guild.

New in version 1.4.

Parameters

channel (Optional[abc.Snowflake]) – Channel the client wants to join. Use None to disconnect.
self_mute (bool) – Indicates if the client should be self-muted.
self_deaf (bool) – Indicates if the client should be self-deafened.
self_video (bool) – Indicates if the client is using video. Untested & unconfirmed (do not use).
preferred_region (Optional[str]) –
The preferred region to connect to.

Changed in version 2.0: The type of this parameter has changed to str.

await subscribe(*, typing=..., activities=..., threads=..., member_updates=...)¶

This function is a coroutine.

Subscribes to a guild.

This is required to receive most events and have a populated thread cache for large guilds.

Note

This is done automatically by default, so you do not need to perform this operation unless you passed guild_subscriptions=False to your Client. This is not recommended for most use cases.

New in version 2.1.

Parameters

typing (bool) –
Whether to receive typing events (i.e. discord.on_typing()).

Note

This is required to subscribe to large guilds (over 75,000 members).
activities (bool) – Currently unknown.
threads (bool) – Whether to populate the thread cache and receive thread events.
member_updates (bool) – Whether to receive member update events (i.e. discord.on_member_join(), discord.on_member_update(), and discord.on_member_remove()).

Raises

TypeError – Attempted to subscribe to a guild without subscribing to typing events.

await subscribe_to(*, members=..., threads=...)¶

This function is a coroutine.

Subscribes to specific members and thread member lists in the guild.

Subscribing to members ensures their member and presence information is kept up to date, ensuring on_member_update(), on_user_update(), and on_presence_update() events are dispatched.

New in version 2.1.

Parameters

members (List[Snowflake]) – A collection of members to subscribe to.
threads (List[Snowflake]) – A collection of threads to subscribe to. If these threads are cached, they will have their members cache populated.

Raises

ValueError – The guild is not subscribed to. The subscription payload is too large.

await unsubscribe_from(*, members=..., threads=...)¶

This function is a coroutine.

Unsubscribes from specific members and thread member lists in the guild. Any unknown members or threads are ignored.

New in version 2.1.

Parameters

members (List[Snowflake]) – A collection of members to unsubscribe from.
threads (List[Snowflake]) – A collection of threads to unsubscribe from.

Raises

ValueError – The guild is not subscribed to.

await automod_rules()¶

This function is a coroutine.

Fetches all automod rules from the guild.

You must have Permissions.manage_guild to do this.

New in version 2.0.

Raises

Forbidden – You do not have permission to view the automod rule.
NotFound – There are no automod rules within this guild.

Returns

The automod rules that were fetched.

Return type

List[AutoModRule]

await fetch_automod_rule(automod_rule_id, /)¶

This function is a coroutine.

Fetches an active automod rule from the guild.

You must have Permissions.manage_guild to do this.

New in version 2.0.

Parameters: automod_rule_id (int) – The ID of the automod rule to fetch.
Raises: Forbidden – You do not have permission to view the automod rule.
Returns: The automod rule that was fetched.
Return type: AutoModRule

await create_automod_rule(*, name, event_type, trigger, actions, enabled=False, exempt_roles=..., exempt_channels=..., reason=...)¶

This function is a coroutine.

Create an automod rule.

You must have Permissions.manage_guild to do this.

New in version 2.0.

Parameters

name (str) – The name of the automod rule.
event_type (AutoModRuleEventType) – The type of event that the automod rule will trigger on.
trigger (AutoModTrigger) – The trigger that will trigger the automod rule.
actions (List[AutoModRuleAction]) – The actions that will be taken when the automod rule is triggered.
enabled (bool) – Whether the automod rule is enabled. Defaults to False.
exempt_roles (Sequence[abc.Snowflake]) – A list of roles that will be exempt from the automod rule.
exempt_channels (Sequence[abc.Snowflake]) – A list of channels that will be exempt from the automod rule.
reason (str) – The reason for creating this automod rule. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to create an automod rule.
HTTPException – Creating the automod rule failed.

Returns

The automod rule that was created.

Return type

AutoModRule

await admin_community_eligibility()¶

This function is a coroutine.

Checks if the user is eligible to join the Discord Admin Community through the guild.

New in version 2.1.

Raises

Forbidden – You do not have permissions to join through the guild.
HTTPException – Checking eligibility failed.

Returns

Whether the user is eligible to join the Discord Admin Community through the guild.

Return type

bool

await join_admin_community()¶

This function is a coroutine.

Joins the Discord Admin Community through the guild. You should check your eligibility with admin_community_eligibility() before calling this.

New in version 2.1.

Raises

Forbidden – You do not have permissions to join through the guild.
HTTPException – Joining failed.

Returns

The Discord Admin Community guild.

Return type

await migrate_command_scope()¶

This function is a coroutine.

Migrates the guild’s bot integrations to the applications.commands scope.

New in version 2.1.

Raises

Forbidden – You do not have permissions to migrate the guild’s bots.
HTTPException – Migrating failed.

Returns

The integration IDs that have newly-added application commands.

Return type

List[int]

await directory_broadcast_eligibility()¶

This function is a coroutine.

Checks if scheduled events can be broadcasted to the directories the guild is in.

New in version 2.1.

Raises: HTTPException – Checking eligibility failed.
Returns: Whether the guild is eligible to broadcast scheduled events to directories.
Return type: bool

Attributes

approximate_member_count
approximate_presence_count
features
icon
id
mfa_level
name
owner
permissions

Methods

asyncdelete
defis_joined
asyncleave

class discord.UserGuild¶

Represents a partial joined guild.

x == y: Checks if two guilds are equal.

x != y: Checks if two guilds are not equal.

hash(x): Returns the guild’s hash.

str(x): Returns the guild’s name.

New in version 2.0.

id¶

The guild’s ID.

Type: int

name¶

The guild name.

Type: str

features¶

A list of features that the guild has. The features that a guild can have are subject to arbitrary change by Discord. Incomplete when retrieved from OAuth2Authorization.guilds.

Type: List[str]

owner¶

Whether the current user is the owner of the guild. Inaccurate when retrieved from OAuth2Authorization.guilds.

Type: bool

mfa_level¶

The guild’s Multi-Factor Authentication requirement level. Only available from OAuth2Authorization.guilds.

New in version 2.1.

Type: MFALevel

approximate_member_count¶

The approximate number of members in the guild. Only available using using Client.fetch_guilds() with with_counts=True.

Type: Optional[int]

approximate_presence_count¶

The approximate number of members currently active in the guild. Offline members are excluded. Only available using Client.fetch_guilds() with with_counts=True.

Type: Optional[int]

property icon¶

Returns the guild’s icon asset, if available.

Type: Optional[Asset]

property permissions¶

Returns the calculated permissions the current user has in the guild.

Type: Permissions

is_joined()¶

Returns whether you are a member of this guild.

Always returns True.

Returns: Whether you are a member of this guild.
Return type: bool

await leave()¶

This function is a coroutine.

Leaves the guild.

Note

You cannot leave a guild that you own, you must delete it instead via delete().

New in version 2.1.

Raises: HTTPException – Leaving the guild failed.

await delete()¶

This function is a coroutine.

Deletes the guild. You must be the guild owner to delete the guild.

New in version 2.1.

Raises

HTTPException – Deleting the guild failed.
Forbidden – You do not have permissions to delete the guild.

Attributes

guild
id
nick

class discord.MutualGuild¶

Represents a mutual guild between a user and the client user.

x == y: Checks if two guilds are equal.

x != y: Checks if two guilds are not equal.

hash(x): Returns the guild’s hash.

New in version 2.0.

id¶

The guild’s ID.

Type: int

nick¶

The guild specific nickname of the user.

Type: Optional[str]

property guild¶

The guild that the user is mutual with.

Type: Guild

class discord.BanEntry¶

A namedtuple which represents a ban returned from bans().

reason¶

The reason this user was banned.

Type: Optional[str]

user¶

The User that was banned.

Type: User

class discord.ApplicationCommandCounts¶

A namedtuple which represents the application command counts for a guild.

chat_input¶

The number of chat input (slash) commands.

Type: int

user¶

The number of user commands.

Type: int

message¶

The number of message commands.

Type: int

Role¶

Attributes

color
colour
created_at
display_icon
guild
hoist
icon
id
managed
members
mention
mentionable
name
permissions
position
tags
unicode_emoji

Methods

asyncadd_members
asyncdelete
asyncedit
asyncfetch_members
defis_assignable
defis_bot_managed
defis_default
defis_integration
defis_premium_subscriber
asyncmember_count
asyncremove_members

class discord.Role¶

Represents a Discord role in a Guild.

x == y: Checks if two roles are equal.

x != y: Checks if two roles are not equal.

x > y: Checks if a role is higher than another in the hierarchy.

x < y: Checks if a role is lower than another in the hierarchy.

x >= y: Checks if a role is higher or equal to another in the hierarchy.

x <= y: Checks if a role is lower or equal to another in the hierarchy.

hash(x): Return the role’s hash.

str(x): Returns the role’s name.

id¶

The ID for the role.

Type: int

name¶

The name of the role.

Type: str

guild¶

The guild the role belongs to.

Type: Guild

hoist¶

Indicates if the role will be displayed separately from other members.

Type: bool

position¶

The position of the role. This number is usually positive. The bottom role has a position of 0.

Warning

Multiple roles can have the same position number. As a consequence of this, comparing via role position is prone to subtle bugs if checking for role hierarchy. The recommended and correct way to compare for roles in the hierarchy is using the comparison operators on the role objects themselves.

Type: int

unicode_emoji¶

The role’s unicode emoji, if available.

Note

If icon is not None, it is displayed as role icon instead of the unicode emoji under this attribute.

If you want the icon that a role has displayed, consider using display_icon.

New in version 2.0.

Type: Optional[str]

managed¶

Indicates if the role is managed by the guild through some form of integrations such as Twitch.

Type: bool

mentionable¶

Indicates if the role can be mentioned by users.

Type: bool

tags¶

The role tags associated with this role.

Type: Optional[RoleTags]

is_default()¶: bool: Checks if the role is the default role.

is_bot_managed()¶: bool: Whether the role is associated with a bot.

New in version 1.6.

is_premium_subscriber()¶: bool: Whether the role is the premium subscriber, AKA “boost”, role for the guild.

New in version 1.6.

is_integration()¶: bool: Whether the role is managed by an integration.

New in version 1.6.

is_assignable()¶: bool: Whether the role is able to be assigned or removed by the bot.

New in version 2.0.

property permissions¶

Returns the role’s permissions.

Type: Permissions

property colour¶

Returns the role colour. An alias exists under color.

Type: Colour

property color¶

Returns the role color. An alias exists under colour.

Type: Colour

property icon¶

Returns the role’s icon asset, if available.

Note

If this is None, the role might instead have unicode emoji as its icon if unicode_emoji is not None.

If you want the icon that a role has displayed, consider using display_icon.

New in version 2.0.

Type: Optional[Asset]

property display_icon¶

Returns the role’s display icon, if available.

New in version 2.0.

Type: Optional[Union[Asset, str]]

property created_at¶

Returns the role’s creation time in UTC.

Type: datetime.datetime

property mention¶

Returns a string that allows you to mention a role.

Type: str

property members¶

Returns all the members with this role.

Type: List[Member]

await fetch_members(*, subscribe=False)¶

This function is a coroutine.

Retrieves all members with this role. This is a partial websocket operation.

New in version 2.0.

Note

This can only return up to 100 of the first members, and cannot be used on the default role.

Parameters

subscribe (bool) – Whether to subscribe to the resulting members. This will keep their info and presence updated. This requires another request, and defaults to False.

Raises

HTTPException – Fetching the members failed.
TypeError – This role is the default role.
asyncio.TimeoutError – The operation timed out.

Returns

The members with this role.

Return type

List[Member]

await add_members(*members, reason=None)¶

This function is a coroutine.

Adds a number of Members to this role.

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

Parameters

*members (abc.Snowflake) – An argument list of abc.Snowflake representing a Member to add to the role.
reason (Optional[str]) – The reason for adding these members. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to add these members.
HTTPException – Adding members failed.
TypeError – The role is the default role.

Returns

The list of members that were added to the role.

Return type

List[Member]

await remove_members(*members, reason=None)¶

This function is a coroutine.

Removes Members from this role.

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

Parameters

*members (abc.Snowflake) – An argument list of abc.Snowflake representing a Member to remove from the role.
reason (Optional[str]) – The reason for adding these members. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to remove these members.
HTTPException – Removing the members failed.
TypeError – The role is the default role.

await edit(*, name=..., permissions=..., colour=..., color=..., hoist=..., display_icon=..., icon=..., unicode_emoji=..., mentionable=..., position=..., reason=...)¶

This function is a coroutine.

Edits the role.

You must have manage_roles to do this.

All fields are optional.

Changed in version 1.4: Can now pass int to colour keyword-only parameter.

Changed in version 2.0: Edits are no longer in-place, the newly edited role is returned instead.

New in version 2.0: The display_icon, icon, and unicode_emoji keyword-only parameters were added.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

name (str) – The new role name to change to.
permissions (Permissions) – The new permissions to change to.
colour (Union[Colour, int]) – The new colour to change to. (aliased to color as well)
hoist (bool) – Indicates if the role should be shown separately in the member list.
display_icon (Optional[Union[bytes, str]]) – A bytes-like object representing the icon or str representing unicode emoji that should be used as a role icon. Could be None to denote removal of the icon. Only PNG/JPEG is supported. This is only available to guilds that contain ROLE_ICONS in Guild.features.
icon (Optional[bytes]) – A bytes-like object representing the icon that should be used as a role icon. Could be None to denote removal of the icon. Only PNG/JPEG is supported. This is only available to guilds that contain ROLE_ICONS in Guild.features.
unicode_emoji (Optional[str]) – A unicode emoji that should be used as a role icon. icon takes precedence over this, but both can be set. This is only available to guilds that contain ROLE_ICONS in Guild.features.
mentionable (bool) – Indicates if the role should be mentionable by others.
position (int) – The new role’s position. This must be below your top role’s position or it will fail.
reason (Optional[str]) – The reason for editing this role. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to change the role.
HTTPException – Editing the role failed.
ValueError – An invalid position was given, the default role was asked to be moved, or both display_icon and icon/unicode_emoji were set.

Returns

The newly edited role.

Return type

Role

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the role.

You must have manage_roles to do this.

Parameters

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

Raises

Forbidden – You do not have permissions to delete the role.
HTTPException – Deleting the role failed.

await member_count()¶

This function is a coroutine.

Retrieves the number of members that have this role.

New in version 2.1.

Raises

Forbidden – You do not have permissions to get the member count.
HTTPException – Retrieving the member count failed.

Returns

The number of members with this role.

Return type

Attributes

bot_id
integration_id
subscription_listing_id

Methods

defis_available_for_purchase
defis_bot_managed
defis_guild_connection
defis_integration
defis_premium_subscriber

class discord.RoleTags¶

Represents tags on a role.

A role tag is a piece of extra information attached to a managed role that gives it context for the reason the role is managed.

While this can be accessed, a useful interface is also provided in the Role and Guild classes as well.

New in version 1.6.

bot_id¶

The bot’s user ID that manages this role.

Type: Optional[int]

integration_id¶

The integration ID that manages the role.

Type: Optional[int]

subscription_listing_id¶

The ID of this role’s subscription SKU and listing.

New in version 2.0.

Type: Optional[int]

is_bot_managed()¶: bool: Whether the role is associated with a bot.

is_premium_subscriber()¶: bool: Whether the role is the premium subscriber, AKA “boost”, role for the guild.

is_integration()¶: bool: Whether the role is managed by an integration.

is_available_for_purchase()¶: bool: Whether the role is available for purchase.

New in version 2.0.

is_guild_connection()¶: bool: Whether the role is a guild’s linked role.

New in version 2.0.

ScheduledEvent¶

Attributes

channel
cover_image
creator
creator_id
description
end_time
entity_id
entity_type
guild
id
location
name
privacy_level
sku_ids
start_time
status
url
user_count

Methods

asyncack
asynccancel
asyncdelete
asyncedit
asyncend
defis_acked
asyncrsvp
asyncstart
asyncunrsvp
asyncusers

class discord.ScheduledEvent¶

Represents a scheduled event in a guild.

x == y: Checks if two scheduled events are equal.

x != y: Checks if two scheduled events are not equal.

hash(x): Returns the scheduled event’s hash.

New in version 2.0.

id¶

The scheduled event’s ID.

Type: int

name¶

The name of the scheduled event.

Type: str

description¶

The description of the scheduled event.

Type: Optional[str]

entity_type¶

The type of entity this event is for.

Type: EntityType

entity_id¶

The ID of the entity this event is for if available.

Type: Optional[int]

start_time¶

The time that the scheduled event will start in UTC.

Type: datetime.datetime

end_time¶

The time that the scheduled event will end in UTC.

Type: Optional[datetime.datetime]

privacy_level¶

The privacy level of the scheduled event.

Type: PrivacyLevel

status¶

The status of the scheduled event.

Type: EventStatus

user_count¶

The number of users subscribed to the scheduled event.

Type: int

creator¶

The user that created the scheduled event.

Type: Optional[User]

creator_id¶

The ID of the user that created the scheduled event.

Type: Optional[int]

location¶

The location of the scheduled event.

Type: Optional[str]

sku_ids¶

The IDs of the SKUs associated with the ticketed scheduled event.

New in version 2.1.

Type: List[int]

property cover_image¶

The scheduled event’s cover image.

Type: Optional[Asset]

property guild¶

The guild this scheduled event is in.

Type: Optional[Guild]

property channel¶

The channel this scheduled event is in.

Type: Optional[Union[VoiceChannel, StageChannel]]

property url¶

The url for the scheduled event.

Type: str

is_acked()¶: bool: Whether the scheduled event has been marked as read.

New in version 2.1.

await start(*, reason=None)¶

This function is a coroutine.

Starts the scheduled event.

Shorthand for:

await event.edit(status=EventStatus.active)

Parameters

reason (Optional[str]) – The reason for starting the scheduled event.

Raises

ValueError – The scheduled event has already started or has ended.
Forbidden – You do not have the proper permissions to start the scheduled event.
HTTPException – The scheduled event could not be started.

Returns

The scheduled event that was started.

Return type

await end(*, reason=None)¶

This function is a coroutine.

Ends the scheduled event.

Shorthand for:

await event.edit(status=EventStatus.completed)

Parameters

reason (Optional[str]) – The reason for ending the scheduled event.

Raises

ValueError – The scheduled event is not active or has already ended.
Forbidden – You do not have the proper permissions to end the scheduled event.
HTTPException – The scheduled event could not be ended.

Returns

The scheduled event that was ended.

Return type

await cancel(*, reason=None)¶

This function is a coroutine.

Cancels the scheduled event.

Shorthand for:

await event.edit(status=EventStatus.cancelled)

Parameters

reason (Optional[str]) – The reason for cancelling the scheduled event.

Raises

ValueError – The scheduled event is already running.
Forbidden – You do not have the proper permissions to cancel the scheduled event.
HTTPException – The scheduled event could not be cancelled.

Returns

The scheduled event that was cancelled.

Return type

await edit(*, name=..., description=..., channel=..., start_time=..., end_time=..., privacy_level=..., entity_type=..., status=..., image=..., location=..., directory_broadcast=..., reason=None)¶

This function is a coroutine.

Edits the scheduled event.

You must have manage_events to do this.

Parameters

name (str) – The name of the scheduled event.
description (str) – The description of the scheduled event.
channel (Optional[Snowflake]) –
The channel to put the scheduled event in. If the channel is a StageInstance or VoiceChannel then it automatically sets the entity type.

Required if the entity type is either EntityType.voice or EntityType.stage_instance.
start_time (datetime.datetime) – The time that the scheduled event will start. This must be a timezone-aware datetime object. Consider using utils.utcnow().
end_time (Optional[datetime.datetime]) –
The time that the scheduled event will end. This must be a timezone-aware datetime object. Consider using utils.utcnow().

If the entity type is either EntityType.voice or EntityType.stage_instance, the end_time can be cleared by passing None.

Required if the entity type is EntityType.external.
privacy_level (PrivacyLevel) – The privacy level of the scheduled event.
entity_type (EntityType) – The new entity type. If the channel is a StageInstance or VoiceChannel then this is automatically set to the appropriate entity type.
status (EventStatus) – The new status of the scheduled event.
image (Optional[bytes]) – The new image of the scheduled event or None to remove the image.
location (str) –
The new location of the scheduled event.

Required if the entity type is EntityType.external.
directory_broadcast (bool) –
Whether to broadcast the scheduled event to the directories the guild is in. You should first check eligibility with Guild.directory_broadcast_eligibility().

New in version 2.1.
reason (Optional[str]) – The reason for editing the scheduled event. Shows up on the audit log.

Raises

TypeError – image was not a bytes-like object, or privacy_level was not a PrivacyLevel, or entity_type was not an EntityType, status was not an EventStatus, or an argument was provided that was incompatible with the scheduled event’s entity type.
ValueError – start_time or end_time was not a timezone-aware datetime object.
Forbidden – You do not have permissions to edit the scheduled event.
HTTPException – Editing the scheduled event failed.

Returns

The edited scheduled event.

Return type

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the scheduled event.

You must have manage_events to do this.

Parameters

reason (Optional[str]) – The reason for deleting the scheduled event. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to delete the scheduled event.
HTTPException – Deleting the scheduled event failed.

async for ... in users(*, limit=None, before=None, after=None, oldest_first=...)¶

This function is a coroutine.

Retrieves all User that are subscribed to this event.

Raises: HTTPException – Retrieving the members failed.
Returns: All subscribed users of this event.
Return type: List[User]

await rsvp()¶

This function is a coroutine.

Marks the current user as interested in this event.

New in version 2.1.

Raises: HTTPException – RSVPing failed.

await unrsvp()¶

This function is a coroutine.

Unmarks the current user as interested in this event.

New in version 2.1.

Raises: HTTPException – Un-RSVPing failed.

await ack()¶

This function is a coroutine.

Marks this scheduled event as read.

Note

This sets the last acknowledged scheduled event to this event, which will mark acknowledged events created after this one as unread.

New in version 2.1.

Raises: HTTPException – Acking failed.

Integration¶

Attributes

account
enabled
guild
id
name
type
user

Methods

asyncdelete

class discord.Integration¶

Represents a guild integration.

New in version 1.4.

id¶

The integration ID.

Type: int

name¶

The integration name.

Type: str

guild¶

The guild of the integration.

Type: Guild

type¶

The integration type.

Type: str

enabled¶

Whether the integration is currently enabled.

Type: bool

account¶

The account linked to this integration.

Type: IntegrationAccount

user¶

The user that added this integration, if available.

Type: Optional[User]

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the integration.

You must have manage_guild to do this.

Parameters

reason (str) –

The reason the integration was deleted. Shows up on the audit log.

New in version 2.0.

Raises

Forbidden – You do not have permission to delete the integration.
HTTPException – Deleting the integration failed.

Attributes

id
name

class discord.IntegrationAccount¶

Represents an integration account.

New in version 1.4.

id¶

The account ID.

Type: str

name¶

The account name.

Type: str

Attributes

account
application
application_id
enabled
guild
id
name
scopes
type
user

class discord.BotIntegration¶

Represents a bot integration on discord.

New in version 2.0.

id¶

The integration ID.

Type: int

name¶

The integration name.

Type: str

guild¶

The guild of the integration.

Type: Guild

type¶

The integration type (i.e. Discord).

Type: str

enabled¶

Whether the integration is currently enabled.

Type: bool

user¶

The user that added this integration, if available.

Type: Optional[User]

account¶

The integration account information.

Type: IntegrationAccount

application_id¶

The application ID of the integration.

Type: int

application¶

The application tied to this integration. Not available in some contexts.

Type: Optional[IntegrationApplication]

scopes¶

The scopes the integration is authorized for.

Type: List[str]

Attributes

account
enable_emoticons
enabled
expire_behavior
expire_behaviour
expire_grace_period
guild
id
name
role
synced_at
syncing
type
user

Methods

asyncdisable
asyncedit
asyncenable
asyncsync

class discord.StreamIntegration¶

Represents a stream integration for Twitch or YouTube.

New in version 2.0.

id¶

The integration ID.

Type: int

name¶

The integration name.

Type: str

guild¶

The guild of the integration.

Type: Guild

type¶

The integration type (i.e. Twitch).

Type: str

enabled¶

Whether the integration is currently enabled.

Type: bool

syncing¶

Where the integration is currently syncing.

Type: bool

enable_emoticons¶

Whether emoticons should be synced for this integration (currently twitch only).

Type: bool

expire_behaviour¶

The behaviour of expiring subscribers. Aliased to expire_behavior as well.

Type: ExpireBehaviour

expire_grace_period¶

The grace period (in days) for expiring subscribers.

Type: int

user¶

The user for the integration, if available.

Type: Optional[User]

account¶

The integration account information.

Type: IntegrationAccount

synced_at¶

An aware UTC datetime representing when the integration was last synced.

Type: datetime.datetime

property expire_behavior¶

An alias for expire_behaviour.

Type: ExpireBehaviour

property role¶: Optional[Role] The role which the integration uses for subscribers.

await edit(*, expire_behaviour=..., expire_grace_period=..., enable_emoticons=...)¶

This function is a coroutine.

Edits the integration.

You must have manage_guild to do this.

Parameters

expire_behaviour (ExpireBehaviour) – The behaviour when an integration subscription lapses. Aliased to expire_behavior as well.
expire_grace_period (int) – The period (in days) where the integration will ignore lapsed subscriptions.
enable_emoticons (bool) – Where emoticons should be synced for this integration (currently twitch only).

Raises

Forbidden – You do not have permission to edit the integration.
HTTPException – Editing the guild failed.

await sync()¶

This function is a coroutine.

Syncs the integration.

You must have manage_guild to do this.

Raises

Forbidden – You do not have permission to sync the integration.
HTTPException – Syncing the integration failed.

await disable(*, reason=None)¶

This function is a coroutine.

Disables the integration.

This is an alias of Integration.delete().

You must have manage_guild to do this.

Parameters

reason (str) – The reason the integration was disabled. Shows up on the audit log.

Raises

Forbidden – You do not have permission to disable the integration.
HTTPException – Disabling the integration failed.

await enable(*, reason=None)¶

This function is a coroutine.

Enables the integration.

You must have manage_guild to do this.

Parameters

reason (str) – The reason the integration was enabled. Shows up on the audit log.

Raises

Forbidden – You do not have permission to enable the integration.
HTTPException – Enabling the integration failed.

Attributes

bot
cover_image
created_at
deeplink_uri
description
icon
id
name
primary_sku_id
primary_sku_url
role_connections_verification_url
splash
third_party_skus
type

Methods

asyncactivity_statistics
asyncassets
asyncentitlement_ticket
asyncentitlements
asyncprimary_store_listing
asyncpublished_store_listings
asyncticket

class discord.IntegrationApplication¶

Represents a very partial application received in integration/interaction contexts.

x == y: Checks if two applications are equal.

x != y: Checks if two applications are not equal.

hash(x): Return the application’s hash.

str(x): Returns the application’s name.

New in version 2.0.

id¶

The application ID.

Type: int

name¶

The application name.

Type: str

bot¶

The bot attached to the application, if any.

Type: Optional[User]

description¶

The application description.

Type: str

deeplink_uri¶

The application’s deeplink URI, if set.

New in version 2.1.

Type: Optional[str]

type¶

The type of application.

Type: Optional[ApplicationType]

primary_sku_id¶

The application’s primary SKU ID, if any. This can be an application’s game SKU, subscription SKU, etc.

Type: Optional[int]

role_connections_verification_url¶

The application’s connection verification URL which will render the application as a verification method in the guild’s role verification configuration.

Type: Optional[str]

third_party_skus¶

A list of third party platforms the SKU is available at.

New in version 2.1.

Type: List[ThirdPartySKU]

property created_at¶

Returns the application’s creation time in UTC.

New in version 2.1.

Type: datetime.datetime

property icon¶

Retrieves the application’s icon asset, if any.

Type: Optional[Asset]

property cover_image¶

Retrieves the application’s cover image, if any.

Type: Optional[Asset]

property splash¶

Retrieves the application’s splash, if any.

New in version 2.1.

Type: Optional[Asset]

property primary_sku_url¶

The URL to the primary SKU of the application, if any.

Type: str

await assets()¶

This function is a coroutine.

Retrieves the assets of this application.

Raises: HTTPException – Retrieving the assets failed.
Returns: The application’s assets.
Return type: List[ApplicationAsset]

await published_store_listings(*, localize=True)¶

This function is a coroutine.

Retrieves all published store listings for this application.

Parameters: localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.
Raises: HTTPException – Retrieving the listings failed.
Returns: The store listings.
Return type: List[StoreListing]

await primary_store_listing(*, localize=True)¶

This function is a coroutine.

Retrieves the primary store listing of this application.

This is the public store listing of the primary SKU.

Parameters

localize (bool) – Whether to localize the store listings to the current user’s locale. If False then all localizations are returned.

Raises

NotFound – The application does not have a primary SKU.
HTTPException – Retrieving the store listing failed.

Returns

The application’s primary store listing, if any.

Return type

await entitlements(*, exclude_consumed=True)¶

This function is a coroutine.

Retrieves the entitlements this account has granted for this application.

Parameters

exclude_consumed (bool) – Whether to exclude consumed entitlements.

Raises

Forbidden – You do not have permissions to fetch entitlements.
HTTPException – Fetching the entitlements failed.

Returns

The entitlements retrieved.

Return type

List[Entitlement]

await ticket()¶

This function is a coroutine.

Retrieves the license ticket for this application.

Raises: HTTPException – Retrieving the ticket failed.
Returns: The ticket retrieved.
Return type: str

await entitlement_ticket()¶

This function is a coroutine.

Retrieves the entitlement ticket for this application.

Raises: HTTPException – Retrieving the ticket failed.
Returns: The ticket retrieved.
Return type: str

await activity_statistics()¶

This function is a coroutine.

Retrieves the activity usage statistics for this application.

Raises: HTTPException – Retrieving the statistics failed.
Returns: The statistics retrieved.
Return type: List[ApplicationActivityStatistics]

AutoMod¶

Attributes

actions
creator
creator_id
enabled
exempt_channel_ids
exempt_channels
exempt_role_ids
exempt_roles
guild
id
name
trigger

Methods

asyncdelete
asyncedit
defis_exempt

class discord.AutoModRule¶

Represents an auto moderation rule.

New in version 2.0.

id¶

The ID of the rule.

Type: int

guild¶

The guild the rule is for.

Type: Guild

name¶

The name of the rule.

Type: str

creator_id¶

The ID of the user that created the rule.

Type: int

trigger¶

The rule’s trigger.

Type: AutoModTrigger

enabled¶

Whether the rule is enabled.

Type: bool

exempt_role_ids¶

The IDs of the roles that are exempt from the rule.

Type: Set[int]

exempt_channel_ids¶

The IDs of the channels that are exempt from the rule.

Type: Set[int]

property creator¶

The member that created this rule.

Type: Optional[Member]

exempt_roles¶

The roles that are exempt from this rule.

Type: List[Role]

exempt_channels¶

The channels that are exempt from this rule.

Type: List[Union[abc.GuildChannel, Thread]]

actions¶

The actions that are taken when this rule is triggered.

Type: List[AutoModRuleAction]

is_exempt(obj, /)¶

Check if an object is exempt from the automod rule.

Parameters: obj (abc.Snowflake) – The role, channel, or thread to check.
Returns: Whether the object is exempt from the automod rule.
Return type: bool

await edit(*, name=..., event_type=..., actions=..., trigger=..., enabled=..., exempt_roles=..., exempt_channels=..., reason=...)¶

This function is a coroutine.

Edits this auto moderation rule.

You must have Permissions.manage_guild to edit rules.

Parameters

name (str) – The new name to change to.
event_type (AutoModRuleEventType) – The new event type to change to.
actions (List[AutoModRuleAction]) – The new rule actions to update.
trigger (AutoModTrigger) – The new trigger to update. You can only change the trigger metadata, not the type.
enabled (bool) – Whether the rule should be enabled or not.
exempt_roles (Sequence[abc.Snowflake]) – The new roles to exempt from the rule.
exempt_channels (Sequence[abc.Snowflake]) – The new channels to exempt from the rule.
reason (str) – The reason for updating this rule. Shows up on the audit log.

Raises

Forbidden – You do not have permission to edit this rule.
HTTPException – Editing the rule failed.

Returns

The updated auto moderation rule.

Return type

AutoModRule

await delete(*, reason=...)¶

This function is a coroutine.

Deletes the auto moderation rule.

You must have Permissions.manage_guild to delete rules.

Parameters

reason (str) – The reason for deleting this rule. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to delete the rule.
HTTPException – Deleting the rule failed.

Attributes

action
alert_system_message_id
channel
channel_id
content
guild
guild_id
matched_content
matched_keyword
member
message_id
rule_id
rule_trigger_type
user_id

Methods

asyncfetch_rule

class discord.AutoModAction¶

Represents an action that was taken as the result of a moderation rule.

New in version 2.0.

action¶

The action that was taken.

Type: AutoModRuleAction

message_id¶

The message ID that triggered the action. This is only available if the action is done on an edited message.

Type: Optional[int]

rule_id¶

The ID of the rule that was triggered.

Type: int

rule_trigger_type¶

The trigger type of the rule that was triggered.

Type: AutoModRuleTriggerType

guild_id¶

The ID of the guild where the rule was triggered.

Type: int

user_id¶

The ID of the user that triggered the rule.

Type: int

channel_id¶

The ID of the channel where the rule was triggered.

Type: int

alert_system_message_id¶

The ID of the system message that was sent to the predefined alert channel.

Type: Optional[int]

content¶

The content of the message that triggered the rule.

Type: str

matched_keyword¶

The matched keyword from the triggering message.

Type: Optional[str]

matched_content¶

The matched content from the triggering message.

Type: Optional[str]

property guild¶

The guild this action was taken in.

Type: Guild

property channel¶

The channel this action was taken in.

Type: Optional[Union[abc.GuildChannel, Thread]]

property member¶

The member this action was taken against /who triggered this rule.

Type: Optional[Member]

await fetch_rule()¶

This function is a coroutine.

Fetch the rule whose action was taken.

You must have Permissions.manage_guild to do this.

Raises

Forbidden – You do not have permissions to view the rule.
HTTPException – Fetching the rule failed.

Returns

The rule that was executed.

Return type

AutoModRule

Attributes

profanity
sexual_content
slurs
value

Methods

clsAutoModPresets.all
clsAutoModPresets.none

class discord.AutoModPresets¶

Wraps up the Discord AutoModRule presets.

x == y: Checks if two AutoModPresets flags are equal.

x != y: Checks if two AutoModPresets flags are not equal.

x | y, x |= y: Returns an AutoModPresets instance with all enabled flags from both x and y.

x & y, x &= y: Returns an AutoModPresets instance with only flags enabled on both x and y.

x ^ y, x ^= y: Returns an AutoModPresets instance with only flags enabled on only one of x or y, not on both.

~x: Returns an AutoModPresets instance with all flags inverted from x.

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.

bool(b): Returns whether any flag is set to True.

New in version 2.0.

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 AutoModPresets with everything enabled.

classmethod none()¶: A factory method that creates a AutoModPresets with everything disabled.

profanity¶

Whether to use the preset profanity filter.

Type: bool

sexual_content¶

Whether to use the preset sexual content filter.

Type: bool

slurs¶

Whether to use the preset slurs filter.

Type: bool

Attributes

channel_id
custom_message
duration
type

class discord.AutoModRuleAction¶

Represents an auto moderation’s rule action.

Note

Only one of channel_id, duration, or custom_message can be used.

New in version 2.0.

type¶

The type of action to take. Defaults to block_message.

Type: AutoModRuleActionType

channel_id¶

The ID of the channel or thread to send the alert message to, if any. Passing this sets type to send_alert_message.

Type: Optional[int]

duration¶

The duration of the timeout to apply, if any. Has a maximum of 28 days. Passing this sets type to timeout.

Type: Optional[datetime.timedelta]

custom_message¶

A custom message which will be shown to a user when their message is blocked. Passing this sets type to block_message.

New in version 2.0.

Type: Optional[str]

Attributes

allow_list
keyword_filter
mention_limit
presets
regex_patterns
type

class discord.AutoModTrigger¶

Represents a trigger for an auto moderation rule.

The following table illustrates relevant attributes for each AutoModRuleTriggerType:

Type	Attributes
`AutoModRuleTriggerType.keyword`	`keyword_filter`, `regex_patterns`, `allow_list`
`AutoModRuleTriggerType.spam`
`AutoModRuleTriggerType.keyword_preset`	`presets`, `allow_list`
`AutoModRuleTriggerType.mention_spam`	`mention_limit`

New in version 2.0.

type¶

The type of trigger.

Type: AutoModRuleTriggerType

keyword_filter¶

The list of strings that will trigger the keyword filter. Maximum of 1000. Keywords can only be up to 60 characters in length.

This could be combined with regex_patterns.

Type: List[str]

regex_patterns¶

The regex pattern that will trigger the filter. The syntax is based off of Rust’s regex syntax. Maximum of 10. Regex strings can only be up to 260 characters in length.

This could be combined with keyword_filter and/or allow_list

New in version 2.0.

Type: List[str]

presets¶

The presets used with the preset keyword filter.

Type: AutoModPresets

allow_list¶

The list of words that are exempt from the commonly flagged words. Maximum of 100. Keywords can only be up to 60 characters in length.

Type: List[str]

mention_limit¶

The total number of user and role mentions a message can contain. Has a maximum of 50.

Type: int

Member¶

Methods

asyncack
asyncack_pins
asyncadd_roles
asyncapplication_commands
asyncban
asyncblock
asyncconnect
asynccreate_dm
asyncedit
asyncfetch_message
asyncfetch_mutual_friends
defget_role
asyncgreet
async forhistory
defis_blocked
defis_friend
defis_on_mobile
defis_pomelo
defis_timed_out
asynckick
defmentioned_in
asyncmove_to
asyncpins
asyncprofile
asyncremove_friend
asyncremove_roles
asyncrequest_to_speak
defsearch
asyncsend
asyncsend_friend_request
defslash_commands
asynctimeout
deftyping
asyncunack
asyncunban
asyncunblock
asyncupload_files
defuser_commands

class discord.Member¶

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 handle (e.g. name or name#discriminator).

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]

guild¶

The guild that the member belongs to.

Type: Guild

nick¶

The guild specific nickname of the user. Takes precedence over the global name.

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]

timed_out_until¶

An aware datetime object that specifies the date and time in UTC that the member’s time out will expire. This will be set to None if the user is not timed out.

New in version 2.0.

Type: Optional[datetime.datetime]

async with typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

async for ... in slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

async for ... in user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

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 avatar_decoration¶: Equivalent to User.avatar_decoration

property avatar_decoration_sku_id¶: Equivalent to User.avatar_decoration_sku_id

property note¶: Equivalent to User.note

property relationship¶: Equivalent to User.relationship

is_friend()¶: bool: Checks if the user is your friend.

is_blocked()¶: bool: Checks if the user is blocked.

property dm_channel¶: Equivalent to User.dm_channel

property call¶: Equivalent to User.call

await create_dm()¶

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

await block()¶

This function is a coroutine.

Blocks the user.

Raises

Forbidden – Not allowed to block this user.
HTTPException – Blocking the user failed.

await unblock()¶

This function is a coroutine.

Unblocks the user.

Raises

Forbidden – Not allowed to unblock this user.
HTTPException – Unblocking the user failed.

await remove_friend()¶

This function is a coroutine.

Removes the user as a friend.

Raises

Forbidden – Not allowed to remove this user as a friend.
HTTPException – Removing the user as a friend failed.

await fetch_mutual_friends()¶

This function is a coroutine.

Fetches mutual friends with the user.

New in version 2.1.

Raises: HTTPException – Fetching the mutual friends failed.
Returns: The mutual friends with the user.
Return type: List[User]

property public_flags¶: Equivalent to User.public_flags

property premium_type¶: Equivalent to User.premium_type

property banner¶: Equivalent to User.banner

property accent_color¶: Equivalent to User.accent_color

property accent_colour¶: Equivalent to User.accent_colour

property status¶

The member’s overall status.

Type: Status

property raw_status¶

The member’s overall status as a string value.

New in version 1.5.

Type: str

property mobile_status¶

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

Type: Status

property desktop_status¶

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

Type: Status

property web_status¶

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

Type: Status

is_on_mobile()¶: bool: A helper function that determines if a member is active on a mobile device.

property colour¶

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¶

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¶

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

A property that returns the role icon that is rendered for this member. If no icon is shown then None is returned.

New in version 2.0.

Type: Optional[Union[str, Asset]]

property mention¶

Returns a string that allows you to mention the member.

Type: str

property display_name¶

Returns the user’s display name.

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

Type: str

property display_avatar¶

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¶

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

New in version 2.0.

Type: Optional[Asset]

property activities¶

Returns 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 GH-1738 for more information.

Type: Tuple[Union[BaseActivity, Spotify]]

property activity¶

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 GH-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)¶

Checks if the member is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the member is mentioned in the message.
Return type: bool

property top_role¶

Returns the member’s highest role.

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

Type: Role

property guild_permissions¶

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, the administrator implication, and whether the member is timed out.

Changed in version 2.0: Member timeouts are taken into consideration.

Type: Permissions

property voice¶

Returns the member’s current voice state.

Type: Optional[VoiceState]

property flags¶

Returns the member’s flags.

New in version 2.0.

Type: MemberFlags

await ban(*, delete_message_days=..., delete_message_seconds=..., reason=None)¶

This function is a coroutine.

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

await unban(*, reason=None)¶

This function is a coroutine.

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

await kick(*, reason=None)¶

This function is a coroutine.

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

await edit(*, nick=..., mute=..., deafen=..., suppress=..., roles=..., voice_channel=..., timed_out_until=..., avatar=..., banner=..., bio=..., bypass_verification=..., reason=None)¶

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`
timed_out_until	`Permissions.moderate_members`
bypass_verification	`Permissions.moderate_members`

All parameters are optional.

Note

To upload an avatar or banner, a bytes-like object must be passed in that represents the image being uploaded. If this is done through a file then the file must be opened via open('some_filename', 'rb') and the bytes-like object is given through the use of fp.read().

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 updated member is now optionally returned, if applicable.

Parameters

nick (Optional[str]) – The member’s new nickname. Use None to remove the nickname.
mute (bool) – Indicates if the member should be guild muted or un-muted.
deafen (bool) – Indicates if the member should be guild deafened or un-deafened.
suppress (bool) –
Indicates if the member should be suppressed in stage channels.

New in version 1.7.
roles (List[Role]) – The member’s new list of roles. This replaces the roles.
voice_channel (Optional[Union[VoiceChannel, StageChannel]]) – The voice channel to move the member to. Pass None to kick them from voice.
timed_out_until (Optional[datetime.datetime]) –
The date the member’s timeout should expire, or None to remove the timeout. This must be a timezone-aware datetime object. Consider using utils.utcnow().

New in version 2.0.
avatar (Optional[bytes]) –
The member’s new guild avatar. Pass None to remove the avatar. You can only change your own guild avatar.

New in version 2.0.
banner (Optional[bytes]) –
The member’s new guild banner. Pass None to remove the banner. You can only change your own guild banner.

New in version 2.0.
bio (Optional[str]) –
The member’s new guild “about me”. Pass None to remove the bio. You can only change your own guild bio.

New in version 2.0.
bypass_verification (bool) –
Indicates if the member should be allowed to bypass the guild verification requirements.

New in version 2.0.
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.
TypeError – The datetime object passed to timed_out_until was not timezone-aware.

Returns

The newly updated member, if applicable. This is not returned if certain fields are passed, such as suppress.

Return type

Optional[Member]

await request_to_speak()¶

This function is a coroutine.

Request 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

ClientException – You are not connected to a voice channel.
Forbidden – You do not have the proper permissions to the action requested.
HTTPException – The operation failed.

await move_to(channel, *, reason=None)¶

This function is a coroutine.

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

You must have move_members to do 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[Union[VoiceChannel, StageChannel]]) – 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 timeout(until, /, *, reason=None)¶

This function is a coroutine.

Applies a time out to a member until the specified date time or for the given datetime.timedelta.

You must have moderate_members to do this.

This raises the same exceptions as edit().

Parameters

until (Optional[Union[datetime.timedelta, datetime.datetime]]) – If this is a datetime.timedelta then it represents the amount of time the member should be timed out for. If this is a datetime.datetime then it’s when the member’s timeout should expire. If None is passed then the timeout is removed. Note that the API only allows for timeouts up to 28 days.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

TypeError – The until parameter was the wrong type or the datetime was not timezone-aware.

await add_roles(*roles, reason=None, atomic=True)¶

This function is a coroutine.

Gives the member a number of Roles.

You must have manage_roles 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

Forbidden – You do not have permissions to add these roles.
HTTPException – Adding roles failed.

await remove_roles(*roles, reason=None, atomic=True)¶

This function is a coroutine.

Removes Roles from this member.

You must have manage_roles 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, /)¶

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

New in version 2.0.

Parameters: role_id (int) – The ID to search for.
Returns: The role or None if not found in the member’s roles.
Return type: Optional[Role]

is_timed_out()¶

Returns whether this member is timed out.

New in version 2.0.

Returns: True if the member is timed out. False otherwise.
Return type: bool

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

property display_banner¶: Equivalent to User.display_banner

await fetch_message(id, /)¶

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

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

is_pomelo()¶: bool: Checks if the user has migrated to Discord’s new unique username system

New in version 2.1.

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

property premium¶: Equivalent to User.premium

await profile(*, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

A shorthand method to retrieve a MemberProfile for the member.

Parameters

with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in MemberProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in MemberProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in MemberProfile.mutual_friends and MemberProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

Forbidden – Not allowed to fetch this profile.
HTTPException – Fetching the profile failed.
InvalidData – The member is not in this guild or has blocked you.

Returns

The profile of the member.

Return type

MemberProfile

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await send_friend_request()¶

This function is a coroutine.

Sends the user a friend request.

Raises

Forbidden – Not allowed to send a friend request to the user.
HTTPException – Sending the friend request failed.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

Methods

asyncack
asyncack_pins
asyncadd_roles
asyncapplication_commands
asyncban
asyncblock
asyncconnect
asynccreate_dm
asyncedit
asyncfetch_message
asyncfetch_mutual_friends
defget_role
asyncgreet
async forhistory
defis_blocked
defis_friend
defis_on_mobile
defis_pomelo
defis_timed_out
asynckick
defmentioned_in
asyncmove_to
asyncpins
asyncprofile
asyncremove_friend
asyncremove_roles
asyncrequest_to_speak
defsearch
asyncsend
asyncsend_friend_request
defslash_commands
asynctimeout
deftyping
asyncunack
asyncunban
asyncunblock
asyncupload_files
defuser_commands

class discord.MemberProfile¶

Represents a Discord member’s profile.

This is a Member with extended attributes.

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

Note

Information may be missing or inaccurate if the user has blocked the client user.

New in version 2.0.

application¶

The application profile of the user, if it is a bot.

Type: Optional[ApplicationProfile]

metadata¶

The global profile metadata of the user.

New in version 2.1.

Type: ProfileMetadata

legacy_username¶

The user’s legacy username (Username#Discriminator), if public.

New in version 2.1.

Type: Optional[str]

bio¶

The user’s “about me” field. Could be None.

Type: Optional[str]

guild_bio¶

The user’s “about me” field for the guild. Could be None.

Type: Optional[str]

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

Note

This is renamed from Member.premium_since because of name collisions.

Type: Optional[datetime.datetime]

premium_type¶

Specifies the type of premium a user has (i.e. Nitro, Nitro Classic, or Nitro Basic).

Changed in version 2.1: This is now PremiumType.none instead of None if the user is not premium.

Type: Optional[PremiumType]

premium_since¶

An aware datetime object that specifies how long a user has been premium (had Nitro). None if the user is not a premium user.

Note

This is not the same as Member.premium_since. That is renamed to guild_premium_since.

Type: Optional[datetime.datetime]

premium_guild_since¶

An aware datetime object that specifies when a user first Nitro boosted a guild.

Type: Optional[datetime.datetime]

connections¶

The connected accounts that show up on the profile.

Type: Optional[List[PartialConnection]]

badges¶

A list of badge icons that the user has.

New in version 2.1.

Type: List[ProfileBadge]

mutual_guilds¶

A list of guilds that you share with the user. None if you didn’t fetch mutuals.

Type: Optional[List[MutualGuild]]

mutual_friends¶

A list of friends that you share with the user. None if you didn’t fetch mutuals.

Type: Optional[List[User]]

property display_banner¶

Returns the member’s display banner.

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

Type: Optional[Asset]

property guild_banner¶

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

Type: Optional[Asset]

property display_bio¶

Returns the member’s display bio.

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

Type: Optional[str]

property accent_color¶: Equivalent to User.accent_color

property accent_colour¶: Equivalent to User.accent_colour

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

property activities¶

Returns 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 GH-1738 for more information.

Type: Tuple[Union[BaseActivity, Spotify]]

property activity¶

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 GH-1738 for more information.

Note

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

Type: Optional[Union[BaseActivity, Spotify]]

await add_roles(*roles, reason=None, atomic=True)¶

This function is a coroutine.

Gives the member a number of Roles.

You must have manage_roles 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

Forbidden – You do not have permissions to add these roles.
HTTPException – Adding roles failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

property avatar¶: Equivalent to User.avatar

property avatar_decoration¶: Equivalent to User.avatar_decoration

property avatar_decoration_sku_id¶: Equivalent to User.avatar_decoration_sku_id

await ban(*, delete_message_days=..., delete_message_seconds=..., reason=None)¶

This function is a coroutine.

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

property banner¶: Equivalent to User.banner

await block()¶

This function is a coroutine.

Blocks the user.

Raises

Forbidden – Not allowed to block this user.
HTTPException – Blocking the user failed.

property bot¶: Equivalent to User.bot

property call¶: Equivalent to User.call

property color¶

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

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

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await create_dm()¶

This function is a coroutine.

Creates a DMChannel with this user.

This should be rarely called, as this is done transparently for most people.

Returns: The channel that was created.
Return type: DMChannel

property created_at¶: Equivalent to User.created_at

property default_avatar¶: Equivalent to User.default_avatar

property desktop_status¶

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

Type: Status

property discriminator¶: Equivalent to User.discriminator

property display_avatar¶

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

A property that returns the role icon that is rendered for this member. If no icon is shown then None is returned.

New in version 2.0.

Type: Optional[Union[str, Asset]]

property display_name¶

Returns the user’s display name.

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

Type: str

property dm_channel¶: Equivalent to User.dm_channel

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`
timed_out_until	`Permissions.moderate_members`
bypass_verification	`Permissions.moderate_members`

All parameters are optional.

Note

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 updated member is now optionally returned, if applicable.

Parameters

nick (Optional[str]) – The member’s new nickname. Use None to remove the nickname.
mute (bool) – Indicates if the member should be guild muted or un-muted.
deafen (bool) – Indicates if the member should be guild deafened or un-deafened.
suppress (bool) –
Indicates if the member should be suppressed in stage channels.

New in version 1.7.
roles (List[Role]) – The member’s new list of roles. This replaces the roles.
voice_channel (Optional[Union[VoiceChannel, StageChannel]]) – The voice channel to move the member to. Pass None to kick them from voice.
timed_out_until (Optional[datetime.datetime]) –
The date the member’s timeout should expire, or None to remove the timeout. This must be a timezone-aware datetime object. Consider using utils.utcnow().

New in version 2.0.
avatar (Optional[bytes]) –
The member’s new guild avatar. Pass None to remove the avatar. You can only change your own guild avatar.

New in version 2.0.
banner (Optional[bytes]) –
The member’s new guild banner. Pass None to remove the banner. You can only change your own guild banner.

New in version 2.0.
bio (Optional[str]) –
The member’s new guild “about me”. Pass None to remove the bio. You can only change your own guild bio.

New in version 2.0.
bypass_verification (bool) –
Indicates if the member should be allowed to bypass the guild verification requirements.

New in version 2.0.
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.
TypeError – The datetime object passed to timed_out_until was not timezone-aware.

Returns

The newly updated member, if applicable. This is not returned if certain fields are passed, such as suppress.

Return type

Optional[Member]

await fetch_message(id, /)¶

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

await fetch_mutual_friends()¶

This function is a coroutine.

Fetches mutual friends with the user.

New in version 2.1.

Raises: HTTPException – Fetching the mutual friends failed.
Returns: The mutual friends with the user.
Return type: List[User]

property flags¶

Returns the member’s flags.

New in version 2.0.

Type: MemberFlags

get_role(role_id, /)¶

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

New in version 2.0.

Parameters: role_id (int) – The ID to search for.
Returns: The role or None if not found in the member’s roles.
Return type: Optional[Role]

property global_name¶: Equivalent to User.global_name

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

property guild_avatar¶

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

Returns the member’s guild permissions.

This does take into consideration guild ownership, the administrator implication, and whether the member is timed out.

Changed in version 2.0: Member timeouts are taken into consideration.

Type: Permissions

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

property id¶: Equivalent to User.id

is_blocked()¶: bool: Checks if the user is blocked.

is_friend()¶: bool: Checks if the user is your friend.

is_on_mobile()¶: bool: A helper function that determines if a member is active on a mobile device.

is_pomelo()¶: bool: Checks if the user has migrated to Discord’s new unique username system

New in version 2.1.

is_timed_out()¶

Returns whether this member is timed out.

New in version 2.0.

Returns: True if the member is timed out. False otherwise.
Return type: bool

await kick(*, reason=None)¶

This function is a coroutine.

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

property mention¶

Returns a string that allows you to mention the member.

Type: str

mentioned_in(message)¶

Checks if the member is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the member is mentioned in the message.
Return type: bool

property mobile_status¶

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

Type: Status

await move_to(channel, *, reason=None)¶

This function is a coroutine.

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

You must have move_members to do 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[Union[VoiceChannel, StageChannel]]) – 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.

property mutual_friends_count¶

The number of mutual friends the user has with the client user.

Type: Optional[int]

property name¶: Equivalent to User.name

property note¶: Equivalent to User.note

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

property premium¶

Indicates if the user is a premium user.

Type: bool

await profile(*, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

A shorthand method to retrieve a MemberProfile for the member.

Parameters

with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in MemberProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in MemberProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in MemberProfile.mutual_friends and MemberProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

Forbidden – Not allowed to fetch this profile.
HTTPException – Fetching the profile failed.
InvalidData – The member is not in this guild or has blocked you.

Returns

The profile of the member.

Return type

MemberProfile

property public_flags¶: Equivalent to User.public_flags

property raw_status¶

The member’s overall status as a string value.

New in version 1.5.

Type: str

property relationship¶: Equivalent to User.relationship

await remove_friend()¶

This function is a coroutine.

Removes the user as a friend.

Raises

Forbidden – Not allowed to remove this user as a friend.
HTTPException – Removing the user as a friend failed.

await remove_roles(*roles, reason=None, atomic=True)¶

This function is a coroutine.

Removes Roles from this member.

You must have manage_roles 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.

await request_to_speak()¶

This function is a coroutine.

Request 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

ClientException – You are not connected to a voice channel.
Forbidden – You do not have the proper permissions to the action requested.
HTTPException – The operation failed.

property roles¶

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]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await send_friend_request()¶

This function is a coroutine.

Sends the user a friend request.

Raises

Forbidden – Not allowed to send a friend request to the user.
HTTPException – Sending the friend request failed.

slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

property status¶

The member’s overall status.

Type: Status

property system¶: Equivalent to User.system

await timeout(until, /, *, reason=None)¶

This function is a coroutine.

Applies a time out to a member until the specified date time or for the given datetime.timedelta.

You must have moderate_members to do this.

This raises the same exceptions as edit().

Parameters

until (Optional[Union[datetime.timedelta, datetime.datetime]]) – If this is a datetime.timedelta then it represents the amount of time the member should be timed out for. If this is a datetime.datetime then it’s when the member’s timeout should expire. If None is passed then the timeout is removed. Note that the API only allows for timeouts up to 28 days.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

TypeError – The until parameter was the wrong type or the datetime was not timezone-aware.

property top_role¶

Returns the member’s highest role.

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

Type: Role

typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await unban(*, reason=None)¶

This function is a coroutine.

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

await unblock()¶

This function is a coroutine.

Unblocks the user.

Raises

Forbidden – Not allowed to unblock this user.
HTTPException – Unblocking the user failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property voice¶

Returns the member’s current voice state.

Type: Optional[VoiceState]

property web_status¶

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

Type: Status

VoiceState¶

Attributes

afk
channel
deaf
mute
requested_to_speak_at
self_deaf
self_mute
self_stream
self_video
suppress

class discord.VoiceState¶

Represents a Discord user’s voice state.

deaf¶

Indicates if the user is currently deafened by the guild.

Doesn’t apply to private channels.

Type: bool

mute¶

Indicates if the user is currently muted by the guild.

Doesn’t apply to private channels.

Type: bool

self_mute¶

Indicates if the user is currently muted by their own accord.

Type: bool

self_deaf¶

Indicates if the user is currently deafened by their own accord.

Type: bool

self_stream¶

Indicates if the user is currently streaming via ‘Go Live’ feature.

New in version 1.3.

Type: bool

self_video¶

Indicates if the user is currently broadcasting video.

Type: bool

suppress¶

Indicates if the user is suppressed from speaking.

Only applicable to stage channels.

New in version 1.7.

Type: bool

requested_to_speak_at¶

An aware datetime object that specifies the date and time in UTC that the member requested to speak. It will be None if they are not requesting to speak anymore or have been accepted to speak.

Only applicable to stage channels.

New in version 1.7.

Type: Optional[datetime.datetime]

afk¶

Indicates if the user is currently in the AFK channel in the guild.

Type: bool

channel¶

The voice channel that the user is currently connected to. None if the user is not currently in a voice channel.

Type: Optional[Union[VoiceChannel, StageChannel, DMChannel, GroupChannel]]

Emoji¶

Attributes

animated
available
created_at
guild
guild_id
id
managed
name
require_colons
roles
url
user

Methods

asyncdelete
asyncedit
asyncfetch_guild
defis_usable
asyncread
asyncsave
asyncto_file

class discord.Emoji¶

Represents a custom emoji.

Depending on the way this object was created, some of the attributes can have a value of None.

x == y: Checks if two emoji are the same.

x != y: Checks if two emoji are not the same.

hash(x): Return the emoji’s hash.

iter(x): Returns an iterator of (field, value) pairs. This allows this class to be used as an iterable in list/dict/etc constructions.

str(x): Returns the emoji rendered for discord.

name¶

The name of the emoji.

Type: str

id¶

The emoji’s ID.

Type: int

require_colons¶

If colons are required to use this emoji in the client (:PJSalt: vs PJSalt).

Type: bool

animated¶

Whether an emoji is animated or not.

Type: bool

managed¶

If this emoji is managed by a Twitch integration.

Type: bool

guild_id¶

The guild ID the emoji belongs to.

Type: int

available¶

Whether the emoji is available for use.

Type: bool

user¶

The user that created the emoji. This can only be retrieved using Guild.fetch_emoji() and having manage_emojis.

Type: Optional[User]

property created_at¶

Returns the emoji’s creation time in UTC.

Type: datetime.datetime

property url¶

Returns the URL of the emoji.

Type: str

property roles¶

A list of roles that is allowed to use this emoji.

If roles is empty, the emoji is unrestricted.

Type: List[Role]

property guild¶

The guild this emoji belongs to.

Type: Guild

is_usable()¶: bool: Whether the bot can use this emoji.

New in version 1.3.

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the custom emoji.

You must have manage_emojis to do this.

Parameters

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

Raises

Forbidden – You are not allowed to delete emojis.
HTTPException – An error occurred deleting the emoji.

await edit(*, name=..., roles=..., reason=None)¶

This function is a coroutine.

Edits the custom emoji.

You must have manage_emojis to do this.

Changed in version 2.0: The newly updated emoji is returned.

Parameters

name (str) – The new emoji name.
roles (List[Snowflake]) – A list of roles that can use this emoji. An empty list can be passed to make it available to everyone.
reason (Optional[str]) – The reason for editing this emoji. Shows up on the audit log.

Raises

Forbidden – You are not allowed to edit emojis.
HTTPException – An error occurred editing the emoji.

Returns

The newly updated emoji.

Return type

Emoji

await fetch_guild()¶

This function is a coroutine.

Retrieves the guild this emoji belongs to.

New in version 1.9.

Raises

NotFound – The guild this emoji belongs to is not public.
HTTPException – An error occurred while fetching the guild.

Returns

The guild this emoji belongs to.

Return type

await read()¶

This function is a coroutine.

Retrieves the content of this asset as a bytes object.

Raises

DiscordException – There was no internal connection state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The content of the asset.

Return type

await save(fp, *, seek_begin=True)¶

This function is a coroutine.

Saves this asset into a file-like object.

Parameters

fp (Union[io.BufferedIOBase, os.PathLike]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.
seek_begin (bool) – Whether to seek to the beginning of the file after saving is successfully done.

Raises

DiscordException – There was no internal connection state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The number of bytes written.

Return type

await to_file(*, filename=..., description=None, spoiler=False)¶

This function is a coroutine.

Converts the asset into a File suitable for sending via abc.Messageable.send().

New in version 2.0.

Parameters

filename (Optional[str]) – The filename of the file. If not provided, then the filename from the asset’s URL is used.
description (Optional[str]) – The description for the file.
spoiler (bool) – Whether the file is a spoiler.

Raises

DiscordException – The asset does not have an associated state.
ValueError – The asset is a unicode emoji.
TypeError – The asset is a sticker with lottie type.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The asset as a file suitable for sending.

Return type

Attributes

animated
created_at
id
name
url

Methods

clsPartialEmoji.from_str
asyncfetch_guild
defis_custom_emoji
defis_unicode_emoji
asyncread
asyncsave
asyncto_file

class discord.PartialEmoji¶

Represents a “partial” emoji.

This model will be given in two scenarios:

“Raw” data events such as on_raw_reaction_add()
Custom emoji that the bot cannot see from e.g. Message.reactions

x == y: Checks if two emoji are the same.

x != y: Checks if two emoji are not the same.

hash(x): Return the emoji’s hash.

str(x): Returns the emoji rendered for discord.

name¶

The custom emoji name, if applicable, or the unicode codepoint of the non-custom emoji. This can be None if the emoji got deleted (e.g. removing a reaction with a deleted emoji).

Type: Optional[str]

animated¶

Whether the emoji is animated or not.

Type: bool

id¶

The ID of the custom emoji, if applicable.

Type: Optional[int]

classmethod from_str(value)¶

Converts a Discord string representation of an emoji to a PartialEmoji.

The formats accepted are:

a:name:id
<a:name:id>
name:id
<:name:id>

If the format does not match then it is assumed to be a unicode emoji.

New in version 2.0.

Parameters: value (str) – The string representation of an emoji.
Returns: The partial emoji from this string.
Return type: PartialEmoji

is_custom_emoji()¶: bool: Checks if this is a custom non-Unicode emoji.

is_unicode_emoji()¶: bool: Checks if this is a Unicode emoji.

property created_at¶

Returns the emoji’s creation time in UTC, or None if Unicode emoji.

New in version 1.6.

Type: Optional[datetime.datetime]

property url¶

Returns the URL of the emoji, if it is custom.

If this isn’t a custom emoji then an empty string is returned

Type: str

await read()¶

This function is a coroutine.

Retrieves the content of this asset as a bytes object.

Raises

DiscordException – There was no internal connection state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.
ValueError – The PartialEmoji is not a custom emoji.

Returns

The content of the asset.

Return type

await fetch_guild()¶

This function is a coroutine.

Retrieves the guild this emoji belongs to.

New in version 1.9.

Raises

NotFound – The guild this emoji belongs to is not public.
HTTPException – An error occurred while fetching the guild.
ValueError – The emoji is not custom.
TypeError – The emoji does not have state available.

Returns

The guild this emoji belongs to.

Return type

await save(fp, *, seek_begin=True)¶

This function is a coroutine.

Saves this asset into a file-like object.

Parameters

fp (Union[io.BufferedIOBase, os.PathLike]) – The file-like object to save this asset to or the filename to use. If a filename is passed then a file is created with that filename and used instead.
seek_begin (bool) – Whether to seek to the beginning of the file after saving is successfully done.

Raises

DiscordException – There was no internal connection state.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The number of bytes written.

Return type

await to_file(*, filename=..., description=None, spoiler=False)¶

This function is a coroutine.

Converts the asset into a File suitable for sending via abc.Messageable.send().

New in version 2.0.

Parameters

filename (Optional[str]) – The filename of the file. If not provided, then the filename from the asset’s URL is used.
description (Optional[str]) – The description for the file.
spoiler (bool) – Whether the file is a spoiler.

Raises

DiscordException – The asset does not have an associated state.
ValueError – The asset is a unicode emoji.
TypeError – The asset is a sticker with lottie type.
HTTPException – Downloading the asset failed.
NotFound – The asset was deleted.

Returns

The asset as a file suitable for sending.

Return type

Sticker¶

Attributes

created_at
description
format
id
name
pack_id
url

class discord.Sticker¶

Represents a sticker.

New in version 1.6.

str(x): Returns the name of the sticker.

x == y: Checks if the sticker is equal to another sticker.

x != y: Checks if the sticker is not equal to another sticker.

name¶

The sticker’s name.

Type: str

id¶

The id of the sticker.

Type: int

description¶

The description of the sticker.

Type: str

pack_id¶

The id of the sticker’s pack.

Type: int

format¶

The format for the sticker’s image.

Type: StickerFormatType

url¶

The URL for the sticker’s image.

Type: str

property created_at¶

Returns the sticker’s creation time in UTC.

Type: datetime.datetime

Attributes

format
id
name
url

Methods

asyncfetch
asyncfetch_guild

class discord.StickerItem¶

Represents a sticker item.

New in version 2.0.

str(x): Returns the name of the sticker item.

x == y: Checks if the sticker item is equal to another sticker item.

x != y: Checks if the sticker item is not equal to another sticker item.

name¶

The sticker’s name.

Type: str

id¶

The id of the sticker.

Type: int

format¶

The format for the sticker’s image.

Type: StickerFormatType

url¶

The URL for the sticker’s image.

Type: str

await fetch()¶

This function is a coroutine.

Attempts to retrieve the full sticker data of the sticker item.

Raises: HTTPException – Retrieving the sticker failed.
Returns: The retrieved sticker.
Return type: Union[StandardSticker, GuildSticker]

await fetch_guild()¶

This function is a coroutine.

Retrieves the guild this sticker belongs to.

New in version 1.9.

Raises

NotFound – The guild this sticker belongs to is not public.
HTTPException – An error occurred while fetching the guild.

Returns

The guild this emoji belongs to.

Return type

Attributes

banner
cover_sticker
cover_sticker_id
description
id
name
sku_id
stickers

class discord.StickerPack¶

Represents a sticker pack.

New in version 2.0.

str(x): Returns the name of the sticker pack.

x == y: Checks if the sticker pack is equal to another sticker pack.

x != y: Checks if the sticker pack is not equal to another sticker pack.

name¶

The name of the sticker pack.

Type: str

description¶

The description of the sticker pack.

Type: str

id¶

The id of the sticker pack.

Type: int

stickers¶

The stickers of this sticker pack.

Type: List[StandardSticker]

sku_id¶

The SKU ID of the sticker pack.

Type: int

cover_sticker_id¶

The ID of the sticker used for the cover of the sticker pack.

Type: Optional[int]

cover_sticker¶

The sticker used for the cover of the sticker pack.

Type: Optional[StandardSticker]

property banner¶

The banner asset of the sticker pack.

Type: Asset

Attributes

description
format
id
name
pack_id
sort_value
tags

Methods

asyncpack

class discord.StandardSticker¶

Represents a sticker that is found in a standard sticker pack.

New in version 2.0.

str(x): Returns the name of the sticker.

x == y: Checks if the sticker is equal to another sticker.

x != y: Checks if the sticker is not equal to another sticker.

name¶

The sticker’s name.

Type: str

id¶

The id of the sticker.

Type: int

description¶

The description of the sticker.

Type: str

pack_id¶

The id of the sticker’s pack.

Type: int

format¶

The format for the sticker’s image.

Type: StickerFormatType

tags¶

A list of tags for the sticker.

Type: List[str]

sort_value¶

The sticker’s sort order within its pack.

Type: int

await pack()¶

This function is a coroutine.

Retrieves the sticker pack that this sticker belongs to.

Raises

InvalidData – The corresponding sticker pack was not found.
HTTPException – Retrieving the sticker pack failed.

Returns

The retrieved sticker pack.

Return type

StickerPack

Attributes

available
description
emoji
format
guild
guild_id
id
name
user

Methods

asyncdelete
asyncedit
asyncfetch_guild

class discord.GuildSticker¶

Represents a sticker that belongs to a guild.

New in version 2.0.

str(x): Returns the name of the sticker.

x == y: Checks if the sticker is equal to another sticker.

x != y: Checks if the sticker is not equal to another sticker.

name¶

The sticker’s name.

Type: str

id¶

The id of the sticker.

Type: int

description¶

The description of the sticker.

Type: str

format¶

The format for the sticker’s image.

Type: StickerFormatType

available¶

Whether this sticker is available for use.

Type: bool

guild_id¶

The ID of the guild that this sticker is from.

Type: int

user¶

The user that created this sticker. This can only be retrieved using Guild.fetch_sticker() and having manage_emojis_and_stickers.

Type: Optional[User]

emoji¶

The name of a unicode emoji that represents this sticker.

Type: str

guild¶

The guild that this sticker is from. Could be None if the bot is not in the guild.

New in version 2.0.

Type: Optional[Guild]

await edit(*, name=..., description=..., emoji=..., reason=None)¶

This function is a coroutine.

Edits a GuildSticker for the guild.

Parameters

name (str) – The sticker’s new name. Must be at least 2 characters.
description (Optional[str]) – The sticker’s new description. Can be None.
emoji (str) – The name of a unicode emoji that represents the sticker’s expression.
reason (str) – The reason for editing this sticker. Shows up on the audit log.

Raises

Forbidden – You are not allowed to edit stickers.
HTTPException – An error occurred editing the sticker.

Returns

The newly modified sticker.

Return type

GuildSticker

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the custom Sticker from the guild.

You must have manage_emojis_and_stickers to do this.

Parameters

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

Raises

Forbidden – You are not allowed to delete stickers.
HTTPException – An error occurred deleting the sticker.

await fetch_guild()¶

This function is a coroutine.

Retrieves the guild this sticker belongs to.

Raises

NotFound – The guild this sticker belongs to is not public.
HTTPException – An error occurred while fetching the guild.

Returns

The guild this emoji belongs to.

Return type

GuildChannel¶

Methods

asyncclone
asynccreate_directory
asynccreate_directory_channel
asynccreate_forum
asynccreate_forum_channel
asynccreate_invite
asynccreate_stage_channel
asynccreate_text_channel
asynccreate_voice_channel
asyncdelete
asyncedit
asyncinvites
defis_nsfw
asyncmove
defoverwrites_for
defpermissions_for
asyncset_permissions

class discord.CategoryChannel¶

Represents a Discord channel category.

These are useful to group channels to logical compartments.

x == y: Checks if two channels are equal.

x != y: Checks if two channels are not equal.

hash(x): Returns the category’s hash.

str(x): Returns the category’s name.

name¶

The category name.

Type: str

guild¶

The guild the category belongs to.

Type: Guild

id¶

The category channel ID.

Type: int

position¶

The position in the category list. This is a number that starts at 0. e.g. the top category is position 0.

Type: int

nsfw¶

If the channel is marked as “not safe for work”.

Note

To check if the channel or the guild of that channel are marked as NSFW, consider is_nsfw() instead.

Type: bool

property type¶

The channel’s Discord type.

Type: ChannelType

is_nsfw()¶: bool: Checks if the category is NSFW.

await clone(*, name=None, reason=None)¶

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have manage_channels to do this.

New in version 1.1.

Parameters

name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.
reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.

Returns

The channel that was created.

Return type

await edit(*, reason=None, **options)¶

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

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

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

name (str) – The new category’s name.
position (int) – The new category’s position.
nsfw (bool) – To mark the category as NSFW or not.
reason (Optional[str]) – The reason for editing this category. Shows up on the audit log.
overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.

Raises

ValueError – If position is less than 0 or greater than the number of categories.
TypeError – The overwrite information is not in proper form.
Forbidden – You do not have permissions to edit the category.
HTTPException – Editing the category failed.

Returns

The newly edited category channel. If the edit was only positional then None is returned instead.

Return type

Optional[CategoryChannel]

await move(**kwargs)¶

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have manage_channels to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.
end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.
before (Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.
offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.
category (Optional[Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.
sync_permissions (bool) – Whether to sync the permissions with the category (if given).
reason (str) – The reason for the move.

Raises

ValueError – An invalid position was given.
TypeError – A bad mix of arguments were passed.
Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.

property channels¶

Returns the channels that are under this category.

These are sorted by the official Discord UI, which places voice channels below the text channels.

Type: List[abc.GuildChannel]

property text_channels¶

Returns the text channels that are under this category.

Type: List[TextChannel]

property voice_channels¶

Returns the voice channels that are under this category.

Type: List[VoiceChannel]

property stage_channels¶

Returns the stage channels that are under this category.

New in version 1.7.

Type: List[StageChannel]

property forums¶

Returns the forum channels that are under this category.

New in version 2.1.

Type: List[ForumChannel]

property directory_channels¶

Returns the directory channels that are under this category.

New in version 2.1.

Type: List[DirectoryChannel]

property directories¶

Returns the directory channels that are under this category.

An alias for directory_channels.

New in version 2.1.

Type: List[DirectoryChannel]

await create_text_channel(name, **options)¶

This function is a coroutine.

A shortcut method to Guild.create_text_channel() to create a TextChannel in the category.

Returns: The channel that was just created.
Return type: TextChannel

await create_voice_channel(name, **options)¶

This function is a coroutine.

A shortcut method to Guild.create_voice_channel() to create a VoiceChannel in the category.

Returns: The channel that was just created.
Return type: VoiceChannel

await create_stage_channel(name, **options)¶

This function is a coroutine.

A shortcut method to Guild.create_stage_channel() to create a StageChannel in the category.

New in version 1.7.

Returns: The channel that was just created.
Return type: StageChannel

await create_directory(name, **options)¶

This function is a coroutine.

A shortcut method to Guild.create_directory() to create a DirectoryChannel in the category.

New in version 2.1.

Returns: The channel that was just created.
Return type: DirectoryChannel

await create_directory_channel(name, **options)¶

This function is a coroutine.

A shortcut method to Guild.create_directory() to create a DirectoryChannel in the category.

New in version 2.1.

Returns: The channel that was just created.
Return type: DirectoryChannel

await create_forum(name, **options)¶

This function is a coroutine.

A shortcut method to Guild.create_forum() to create a ForumChannel in the category.

New in version 2.0.

Returns: The channel that was just created.
Return type: ForumChannel

await create_forum_channel(name, **options)¶

This function is a coroutine.

A shortcut method to Guild.create_forum() to create a ForumChannel in the category.

New in version 2.0.

Returns: The channel that was just created.
Return type: ForumChannel

property category¶

The category this channel belongs to.

If there is no category then this is None.

Type: Optional[CategoryChannel]

property changed_roles¶

Returns a list of roles that have been overridden from their default values in the roles attribute.

Type: List[Role]

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, guest=False, target_type=None, target_user=None, target_application=None)¶

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have create_instant_invite to do this.

Changed in version 2.1: The validate parameter has been removed.

Parameters

max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.
max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.
temporary (bool) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
guest (bool) –
Denotes that the invite is a guest invite. Guest invites grant temporary membership for the purposes of joining a voice channel. Defaults to False.

New in version 2.1.
unique (bool) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.
target_type (Optional[InviteTarget]) –
The type of target for the voice channel invite, if any.

New in version 2.0.
target_user (Optional[User]) –
The user whose stream to display for this invite, required if target_type is InviteTarget.stream. The user must be streaming in the channel.

New in version 2.0.
target_application: –
Optional[Application]: The embedded application for the invite, required if target_type is InviteTarget.embedded_application.

New in version 2.0.
reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises

HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.
ValueError – target_type is not a creatable invite target type.

Returns

The invite that was created.

Return type

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the channel.

You must have manage_channels to do this.

Parameters

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

Raises

Forbidden – You do not have proper permissions to delete the channel.
NotFound – The channel was not found or was already deleted.
HTTPException – Deleting the channel failed.

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have manage_channels to get this information.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

property mention¶

The string that allows you to mention the channel.

Type: str

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property overwrites¶

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Changed in version 2.0: Overwrites can now be type-aware Object in case of cache lookup failure

Returns: The channel’s permission overwrites.
Return type: Dict[Union[Role, Member, Object], PermissionOverwrite]

overwrites_for(obj)¶

Returns the channel-specific overwrites for a member or a role.

Parameters: obj (Union[Role, User, Object]) – The role or user denoting whose overwrite to get.
Returns: The permission overwrites for this object.
Return type: PermissionOverwrite

permissions_for(obj, /)¶

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

Guild owner
Guild roles
Channel overrides
Member overrides
Implicit permissions
Member timeout

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

The default role permissions
The permissions of the role used as a parameter
The default role permission overwrites
The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Changed in version 2.0: obj parameter is now positional-only.

Parameters: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Returns: The resolved permissions for the member or role.
Return type: Permissions

property permissions_synced¶

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type: bool

await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)¶

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have manage_roles to do this.

Note

This method replaces the old overwrites with the ones given.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, read_messages=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False
overwrite.read_messages = True
await channel.set_permissions(member, overwrite=overwrite)

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

target (Union[Member, Role]) – The member or role to overwrite permissions for.
overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.
**permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit channel specific permissions.
HTTPException – Editing channel specific permissions failed.
NotFound – The role or member being edited is not part of the guild.
TypeError – The overwrite parameter was invalid or the target type was not Role or Member.
ValueError – The overwrite parameter and positions parameters were both unset.

Methods

asyncack
asyncack_pins
asyncapplication_commands
async forarchived_threads
asyncclone
asynccreate_invite
asynccreate_thread
asynccreate_webhook
asyncdelete
asyncdelete_messages
asyncedit
asyncfetch_message
asyncfollow
defget_partial_message
defget_thread
asyncgreet
async forhistory
asyncinvites
defis_news
defis_nsfw
asyncmove
defoverwrites_for
defpermissions_for
asyncpins
asyncpurge
defsearch
asyncsend
asyncset_permissions
defslash_commands
deftyping
asyncunack
asyncupload_files
defuser_commands
asyncwebhooks

class discord.TextChannel¶

Represents a Discord guild text channel.

x == y: Checks if two channels are equal.

x != y: Checks if two channels are not equal.

hash(x): Returns the channel’s hash.

str(x): Returns the channel’s name.

name¶

The channel name.

Type: str

guild¶

The guild the channel belongs to.

Type: Guild

id¶

The channel ID.

Type: int

category_id¶

The category channel ID this channel belongs to, if applicable.

Type: Optional[int]

topic¶

The channel’s topic. None if it doesn’t exist.

Type: Optional[str]

position¶

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type: int

last_message_id¶

The last message ID of the message sent to this channel. It may not point to an existing or valid message.

Type: Optional[int]

last_pin_timestamp¶

When the last pinned message was pinned. None if there are no pinned messages.

New in version 2.0.

Type: Optional[datetime.datetime]

slowmode_delay¶

The number of seconds a member must wait between sending messages in this channel. A value of 0 denotes that it is disabled. Bots and users with manage_channels or manage_messages bypass slowmode.

Type: int

nsfw¶

If the channel is marked as “not safe for work” or “age restricted”.

Type: bool

default_auto_archive_duration¶

The default auto archive duration in minutes for threads created in this channel.

New in version 2.0.

Type: int

default_thread_slowmode_delay¶

The default slowmode delay in seconds for threads created in this channel.

New in version 2.0.

Type: int

async with typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

async for ... in slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

async for ... in user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property type¶

The channel’s Discord type.

Type: ChannelType

permissions_for(obj, /)¶

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

Guild owner
Guild roles
Channel overrides
Member overrides
Implicit permissions
Member timeout

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

The default role permissions
The permissions of the role used as a parameter
The default role permission overwrites
The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Changed in version 2.0: obj parameter is now positional-only.

Parameters: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Returns: The resolved permissions for the member or role.
Return type: Permissions

property members¶

Returns all members that can see this channel.

Type: List[Member]

property threads¶

Returns all the threads that you can see.

New in version 2.0.

Type: List[Thread]

is_nsfw()¶: bool: Checks if the channel is NSFW.

is_news()¶: bool: Checks if the channel is a news channel.

property read_state¶

Returns the read state for this channel.

New in version 2.1.

Type: ReadState

property last_message¶

Retrieves the last message from this channel in cache.

The message might not be valid or point to an existing message.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

Returns: The last message in this channel or None if not found.
Return type: Optional[Message]

property acked_message_id¶

The last message ID that the user has acknowledged. It may not point to an existing or valid message.

New in version 2.1.

Type: int

property acked_message¶

Retrieves the last message that the user has acknowledged in cache.

The message might not be valid or point to an existing message.

New in version 2.1.

Reliable Fetching

For a slightly more reliable method of fetching the last acknowledged message, consider using either history() or fetch_message() with the acked_message_id attribute.

Returns: The last acknowledged message in this channel or None if not found.
Return type: Optional[Message]

property acked_pin_timestamp¶

When the channel’s pins were last acknowledged.

New in version 2.1.

Type: Optional[datetime.datetime]

property mention_count¶

Returns how many unread mentions the user has in this channel.

New in version 2.1.

Type: int

property last_viewed_timestamp¶

When the channel was last viewed.

New in version 2.1.

Type: datetime.date

await edit(*, reason=None, **options)¶

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

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

Changed in version 1.4: The type keyword-only parameter was added.

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

name (str) – The new channel name.
topic (str) – The new channel’s topic.
position (int) – The new channel’s position.
nsfw (bool) – To mark the channel as NSFW or not.
sync_permissions (bool) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to False.
category (Optional[CategoryChannel]) – The new category for this channel. Can be None to remove the category.
slowmode_delay (int) – Specifies the slowmode rate limit for user in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600.
type (ChannelType) – Change the type of this text channel. Currently, only conversion between ChannelType.text and ChannelType.news is supported. This is only available to guilds that contain NEWS in Guild.features.
reason (Optional[str]) – The reason for editing this channel. Shows up on the audit log.
overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.
default_auto_archive_duration (int) –
The new default auto archive duration in minutes for threads created in this channel. Must be one of 60, 1440, 4320, or 10080.

New in version 2.0.
default_thread_slowmode_delay (int) –
The new default slowmode delay in seconds for threads created in this channel.

New in version 2.0.

Raises

ValueError – The new position is less than 0 or greater than the number of channels.
TypeError – The permission overwrite information is not in proper form.
Forbidden – You do not have permissions to edit the channel.
HTTPException – Editing the channel failed.

Returns

The newly edited text channel. If the edit was only positional then None is returned instead.

Return type

Optional[TextChannel]

await clone(*, name=None, reason=None)¶

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have manage_channels to do this.

New in version 1.1.

Parameters

name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.
reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.

Returns

The channel that was created.

Return type

await delete_messages(messages, /, *, reason=None)¶

This function is a coroutine.

Deletes a list of messages. This is similar to Message.delete() except it bulk deletes multiple messages.

You must have manage_messages to use this (unless they’re your own).

Note

Users do not have access to the message bulk-delete endpoint. Since messages are just iterated over and deleted one-by-one, it’s easy to get ratelimited using this method.

Changed in version 2.0: messages parameter is now positional-only.

The reason keyword-only parameter was added.

Parameters

messages (Iterable[abc.Snowflake]) – An iterable of messages denoting which ones to bulk delete.
reason (Optional[str]) – The reason for deleting the messages. Shows up on the audit log.

Raises

Forbidden – You do not have proper permissions to delete the messages.
HTTPException – Deleting the messages failed.

await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=None, reason=None)¶

This function is a coroutine.

Purges a list of messages that meet the criteria given by the predicate check. If a check is not provided then all messages are deleted without discrimination.

Having read_message_history is needed to retrieve message history.

Changed in version 2.0: The reason keyword-only parameter was added.

Examples

Deleting bot’s messages

def is_me(m):
    return m.author == client.user

deleted = await channel.purge(limit=100, check=is_me)
await channel.send(f'Deleted {len(deleted)} message(s)')

Parameters

limit (Optional[int]) – The number of messages to search through. This is not the number of messages that will be deleted, though it can be.
check (Callable[[Message], bool]) – The function used to check if a message should be deleted. It must take a Message as its sole parameter.
before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as before in history().
after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as after in history().
around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as around in history().
oldest_first (Optional[bool]) – Same as oldest_first in history().
reason (Optional[str]) – The reason for purging the messages. Shows up on the audit log.

Raises

Forbidden – You do not have proper permissions to do the actions required.
HTTPException – Purging the messages failed.

Returns

The list of messages that were deleted.

Return type

List[Message]

await webhooks()¶

This function is a coroutine.

Gets the list of webhooks from this channel.

You must have manage_webhooks to do this.

Raises: Forbidden – You don’t have permissions to get the webhooks.
Returns: The webhooks for this channel.
Return type: List[Webhook]

await create_webhook(*, name, avatar=None, reason=None)¶

This function is a coroutine.

Creates a webhook for this channel.

You must have manage_webhooks to do this.

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

Parameters

name (str) – The webhook’s name.
avatar (Optional[bytes]) – A bytes-like object representing the webhook’s default avatar. This operates similarly to edit().
reason (Optional[str]) – The reason for creating this webhook. Shows up in the audit logs.

Raises

HTTPException – Creating the webhook failed.
Forbidden – You do not have permissions to create a webhook.

Returns

The created webhook.

Return type

await follow(*, destination, reason=None)¶

This function is a coroutine.

Follows a channel using a webhook.

Only news channels can be followed.

Note

The webhook returned will not provide a token to do webhook actions, as Discord does not provide it.

New in version 1.3.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

destination (TextChannel) – The channel you would like to follow from.
reason (Optional[str]) –
The reason for following the channel. Shows up on the destination guild’s audit log.

New in version 1.4.

Raises

HTTPException – Following the channel failed.
Forbidden – You do not have the permissions to create a webhook.
ClientException – The channel is not a news channel.
TypeError – The destination channel is not a text channel.

Returns

The created webhook.

Return type

get_partial_message(message_id, /)¶

Creates a PartialMessage from the message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

New in version 1.6.

Changed in version 2.0: message_id parameter is now positional-only.

Parameters: message_id (int) – The message ID to create a partial message for.
Returns: The partial message.
Return type: PartialMessage

get_thread(thread_id, /)¶

Returns a thread with the given ID.

Note

This does not always retrieve archived threads, as they are not retained in the internal cache. Use Guild.fetch_channel() instead.

New in version 2.0.

Parameters: thread_id (int) – The ID to search for.
Returns: The returned thread or None if not found.
Return type: Optional[Thread]

await create_thread(*, name, message=None, auto_archive_duration=..., type=None, reason=None, invitable=True, slowmode_delay=None)¶

This function is a coroutine.

Creates a thread in this text channel.

To create a public thread, you must have create_public_threads. For a private thread, create_private_threads is needed instead.

New in version 2.0.

Parameters

name (str) – The name of the thread.
message (Optional[abc.Snowflake]) – A snowflake representing the message to create the thread with. If None is passed then a private thread is created. Defaults to None.
auto_archive_duration (int) –
The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

Must be one of 60, 1440, 4320, or 10080, if provided.
type (Optional[ChannelType]) – The type of thread to create. If a message is passed then this parameter is ignored, as a thread created with a message is always a public thread. By default this creates a private thread if this is None.
reason (Optional[str]) – The reason for creating a new thread. Shows up on the audit log.
invitable (bool) – Whether non-moderators can add users to the thread. Only applicable to private threads. Defaults to True.
slowmode_delay (Optional[int]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is 21600. By default no slowmode rate limit if this is None.

Raises

Forbidden – You do not have permissions to create a thread.
HTTPException – Starting the thread failed.

Returns

The created thread

Return type

async for ... in archived_threads(*, private=False, joined=False, limit=100, before=None)¶

Returns an asynchronous iterator that iterates over all archived threads in this text channel, in order of decreasing ID for joined threads, and decreasing Thread.archive_timestamp otherwise.

You must have read_message_history to do this. If iterating over private threads then manage_threads is also required.

New in version 2.0.

Parameters

limit (Optional[bool]) – The number of threads to retrieve. If None, retrieves every archived thread in the channel. Note, however, that this would make it a slow operation.
before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve archived channels before the given date or ID.
private (bool) – Whether to retrieve private archived threads.
joined (bool) – Whether to retrieve private archived threads that you’ve joined. You cannot set joined to True and private to False.

Raises

Forbidden – You do not have permissions to get archived threads.
HTTPException – The request to get the archived threads failed.
ValueError – joined was set to True and private was set to False. You cannot retrieve public archived threads that you have joined.

Yields

Thread – The archived threads.

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

property category¶

The category this channel belongs to.

If there is no category then this is None.

Type: Optional[CategoryChannel]

property changed_roles¶

Returns a list of roles that have been overridden from their default values in the roles attribute.

Type: List[Role]

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, guest=False, target_type=None, target_user=None, target_application=None)¶

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have create_instant_invite to do this.

Changed in version 2.1: The validate parameter has been removed.

Parameters

max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.
max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.
temporary (bool) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
guest (bool) –
Denotes that the invite is a guest invite. Guest invites grant temporary membership for the purposes of joining a voice channel. Defaults to False.

New in version 2.1.
unique (bool) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.
target_type (Optional[InviteTarget]) –
The type of target for the voice channel invite, if any.

New in version 2.0.
target_user (Optional[User]) –
The user whose stream to display for this invite, required if target_type is InviteTarget.stream. The user must be streaming in the channel.

New in version 2.0.
target_application: –
Optional[Application]: The embedded application for the invite, required if target_type is InviteTarget.embedded_application.

New in version 2.0.
reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises

HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.
ValueError – target_type is not a creatable invite target type.

Returns

The invite that was created.

Return type

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the channel.

You must have manage_channels to do this.

Parameters

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

Raises

Forbidden – You do not have proper permissions to delete the channel.
NotFound – The channel was not found or was already deleted.
HTTPException – Deleting the channel failed.

await fetch_message(id, /)¶

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

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have manage_channels to get this information.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

property mention¶

The string that allows you to mention the channel.

Type: str

await move(**kwargs)¶

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have manage_channels to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.
end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.
before (Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.
offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.
category (Optional[Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.
sync_permissions (bool) – Whether to sync the permissions with the category (if given).
reason (str) – The reason for the move.

Raises

ValueError – An invalid position was given.
TypeError – A bad mix of arguments were passed.
Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property overwrites¶

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Changed in version 2.0: Overwrites can now be type-aware Object in case of cache lookup failure

Returns: The channel’s permission overwrites.
Return type: Dict[Union[Role, Member, Object], PermissionOverwrite]

overwrites_for(obj)¶

Returns the channel-specific overwrites for a member or a role.

Parameters: obj (Union[Role, User, Object]) – The role or user denoting whose overwrite to get.
Returns: The permission overwrites for this object.
Return type: PermissionOverwrite

property permissions_synced¶

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type: bool

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)¶

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have manage_roles to do this.

Note

This method replaces the old overwrites with the ones given.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, read_messages=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False
overwrite.read_messages = True
await channel.set_permissions(member, overwrite=overwrite)

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

target (Union[Member, Role]) – The member or role to overwrite permissions for.
overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.
**permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit channel specific permissions.
HTTPException – Editing channel specific permissions failed.
NotFound – The role or member being edited is not part of the guild.
TypeError – The overwrite parameter was invalid or the target type was not Role or Member.
ValueError – The overwrite parameter and positions parameters were both unset.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

Methods

asyncack
asyncack_pins
asyncapplication_commands
asyncclone
asyncconnect
asynccreate_invite
asynccreate_webhook
asyncdelete
asyncdelete_messages
asyncedit
asyncfetch_message
defget_partial_message
asyncgreet
async forhistory
asyncinvites
defis_nsfw
asyncmove
defoverwrites_for
defpermissions_for
asyncpins
asyncpurge
defsearch
asyncsend
asyncset_permissions
defslash_commands
deftyping
asyncunack
asyncupload_files
defuser_commands
asyncwebhooks

class discord.VoiceChannel¶

Represents a Discord guild voice channel.

x == y: Checks if two channels are equal.

x != y: Checks if two channels are not equal.

hash(x): Returns the channel’s hash.

str(x): Returns the channel’s name.

name¶

The channel name.

Type: str

guild¶

The guild the channel belongs to.

Type: Guild

id¶

The channel ID.

Type: int

nsfw¶

If the channel is marked as “not safe for work” or “age restricted”.

New in version 2.0.

Type: bool

category_id¶

The category channel ID this channel belongs to, if applicable.

Type: Optional[int]

position¶

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type: int

bitrate¶

The channel’s preferred audio bitrate in bits per second.

Type: int

user_limit¶

The channel’s limit for number of members that can be in a voice channel.

Type: int

rtc_region¶

The region for the voice channel’s voice communication. A value of None indicates automatic voice region detection.

New in version 1.7.

Changed in version 2.0: The type of this attribute has changed to str.

Type: Optional[str]

video_quality_mode¶

The camera video quality for the voice channel’s participants.

New in version 2.0.

Type: VideoQualityMode

last_message_id¶

The last message ID of the message sent to this channel. It may not point to an existing or valid message.

New in version 2.0.

Type: Optional[int]

last_pin_timestamp¶

When the last pinned message was pinned. None if there are no pinned messages.

New in version 2.0.

Type: Optional[datetime.datetime]

slowmode_delay¶

New in version 2.0.

Type: int

async with typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

async for ... in slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

async for ... in user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property type¶

The channel’s Discord type.

Type: ChannelType

await clone(*, name=None, reason=None)¶

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have manage_channels to do this.

New in version 1.1.

Parameters

name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.
reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.

Returns

The channel that was created.

Return type

await edit(*, reason=None, **options)¶

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

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

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

Changed in version 2.0: The region parameter now accepts str instead of an enum.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

name (str) – The new channel’s name.
bitrate (int) – The new channel’s bitrate.
nsfw (bool) – To mark the channel as NSFW or not.
user_limit (int) – The new channel’s user limit.
position (int) – The new channel’s position.
sync_permissions (bool) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to False.
category (Optional[CategoryChannel]) – The new category for this channel. Can be None to remove the category.
slowmode_delay (int) – Specifies the slowmode rate limit for user in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600.
reason (Optional[str]) – The reason for editing this channel. Shows up on the audit log.
overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.
rtc_region (Optional[str]) –
The new region for the voice channel’s voice communication. A value of None indicates automatic voice region detection.

New in version 1.7.
video_quality_mode (VideoQualityMode) –
The camera video quality for the voice channel’s participants.

New in version 2.0.

Raises

TypeError – If the permission overwrite information is not in proper form.
Forbidden – You do not have permissions to edit the channel.
HTTPException – Editing the channel failed.

Returns

The newly edited voice channel. If the edit was only positional then None is returned instead.

Return type

Optional[VoiceChannel]

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

property acked_message¶

Retrieves the last message that the user has acknowledged in cache.

The message might not be valid or point to an existing message.

New in version 2.1.

Reliable Fetching

For a slightly more reliable method of fetching the last acknowledged message, consider using either history() or fetch_message() with the acked_message_id attribute.

Returns: The last acknowledged message in this channel or None if not found.
Return type: Optional[Message]

property acked_message_id¶

The last message ID that the user has acknowledged. It may not point to an existing or valid message.

New in version 2.1.

Type: int

property acked_pin_timestamp¶

When the channel’s pins were last acknowledged.

New in version 2.1.

Type: Optional[datetime.datetime]

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

property category¶

The category this channel belongs to.

If there is no category then this is None.

Type: Optional[CategoryChannel]

property changed_roles¶

Returns a list of roles that have been overridden from their default values in the roles attribute.

Type: List[Role]

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, guest=False, target_type=None, target_user=None, target_application=None)¶

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have create_instant_invite to do this.

Changed in version 2.1: The validate parameter has been removed.

Parameters

max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.
max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.
temporary (bool) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
guest (bool) –
Denotes that the invite is a guest invite. Guest invites grant temporary membership for the purposes of joining a voice channel. Defaults to False.

New in version 2.1.
unique (bool) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.
target_type (Optional[InviteTarget]) –
The type of target for the voice channel invite, if any.

New in version 2.0.
target_user (Optional[User]) –
The user whose stream to display for this invite, required if target_type is InviteTarget.stream. The user must be streaming in the channel.

New in version 2.0.
target_application: –
Optional[Application]: The embedded application for the invite, required if target_type is InviteTarget.embedded_application.

New in version 2.0.
reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises

HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.
ValueError – target_type is not a creatable invite target type.

Returns

The invite that was created.

Return type

await create_webhook(*, name, avatar=None, reason=None)¶

This function is a coroutine.

Creates a webhook for this channel.

You must have manage_webhooks to do this.

New in version 2.0.

Parameters

name (str) – The webhook’s name.
avatar (Optional[bytes]) – A bytes-like object representing the webhook’s default avatar. This operates similarly to edit().
reason (Optional[str]) – The reason for creating this webhook. Shows up in the audit logs.

Raises

HTTPException – Creating the webhook failed.
Forbidden – You do not have permissions to create a webhook.

Returns

The created webhook.

Return type

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the channel.

You must have manage_channels to do this.

Parameters

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

Raises

Forbidden – You do not have proper permissions to delete the channel.
NotFound – The channel was not found or was already deleted.
HTTPException – Deleting the channel failed.

await delete_messages(messages, /, *, reason=None)¶

This function is a coroutine.

Deletes a list of messages. This is similar to Message.delete() except it bulk deletes multiple messages.

You must have manage_messages to use this (unless they’re your own).

Note

Users do not have access to the message bulk-delete endpoint. Since messages are just iterated over and deleted one-by-one, it’s easy to get ratelimited using this method.

New in version 2.0.

Parameters

messages (Iterable[abc.Snowflake]) – An iterable of messages denoting which ones to bulk delete.
reason (Optional[str]) – The reason for deleting the messages. Shows up on the audit log.

Raises

Forbidden – You do not have proper permissions to delete the messages.
HTTPException – Deleting the messages failed.

await fetch_message(id, /)¶

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

get_partial_message(message_id, /)¶

Creates a PartialMessage from the message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

New in version 2.0.

Parameters: message_id (int) – The message ID to create a partial message for.
Returns: The partial message.
Return type: PartialMessage

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have manage_channels to get this information.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

is_nsfw()¶: bool: Checks if the channel is NSFW.

New in version 2.0.

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

property last_message¶

Retrieves the last message from this channel in cache.

The message might not be valid or point to an existing message.

New in version 2.0.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

Returns: The last message in this channel or None if not found.
Return type: Optional[Message]

property last_viewed_timestamp¶

When the channel was last viewed.

New in version 2.1.

Type: datetime.date

property members¶

Returns all members that are currently inside this voice channel.

Type: List[Member]

property mention¶

The string that allows you to mention the channel.

Type: str

property mention_count¶

Returns how many unread mentions the user has in this channel.

New in version 2.1.

Type: int

await move(**kwargs)¶

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have manage_channels to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.
end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.
before (Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.
offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.
category (Optional[Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.
sync_permissions (bool) – Whether to sync the permissions with the category (if given).
reason (str) – The reason for the move.

Raises

ValueError – An invalid position was given.
TypeError – A bad mix of arguments were passed.
Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property overwrites¶

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Changed in version 2.0: Overwrites can now be type-aware Object in case of cache lookup failure

Returns: The channel’s permission overwrites.
Return type: Dict[Union[Role, Member, Object], PermissionOverwrite]

overwrites_for(obj)¶

Returns the channel-specific overwrites for a member or a role.

Parameters: obj (Union[Role, User, Object]) – The role or user denoting whose overwrite to get.
Returns: The permission overwrites for this object.
Return type: PermissionOverwrite

permissions_for(obj, /)¶

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

Guild owner
Guild roles
Channel overrides
Member overrides
Implicit permissions
Member timeout

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

The default role permissions
The permissions of the role used as a parameter
The default role permission overwrites
The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Changed in version 2.0: obj parameter is now positional-only.

Parameters: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Returns: The resolved permissions for the member or role.
Return type: Permissions

property permissions_synced¶

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type: bool

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=None, reason=None)¶

This function is a coroutine.

Purges a list of messages that meet the criteria given by the predicate check. If a check is not provided then all messages are deleted without discrimination.

Having read_message_history is needed to retrieve message history.

New in version 2.0.

Examples

Deleting bot’s messages

def is_me(m):
    return m.author == client.user

deleted = await channel.purge(limit=100, check=is_me)
await channel.send(f'Deleted {len(deleted)} message(s)')

Parameters

limit (Optional[int]) – The number of messages to search through. This is not the number of messages that will be deleted, though it can be.
check (Callable[[Message], bool]) – The function used to check if a message should be deleted. It must take a Message as its sole parameter.
before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as before in history().
after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as after in history().
around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as around in history().
oldest_first (Optional[bool]) – Same as oldest_first in history().
reason (Optional[str]) – The reason for purging the messages. Shows up on the audit log.

Raises

Forbidden – You do not have proper permissions to do the actions required.
HTTPException – Purging the messages failed.

Returns

The list of messages that were deleted.

Return type

List[Message]

property read_state¶

Returns the read state for this channel.

New in version 2.1.

Type: ReadState

property scheduled_events¶

Returns all scheduled events for this channel.

New in version 2.0.

Type: List[ScheduledEvent]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)¶

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have manage_roles to do this.

Note

This method replaces the old overwrites with the ones given.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, read_messages=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False
overwrite.read_messages = True
await channel.set_permissions(member, overwrite=overwrite)

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

target (Union[Member, Role]) – The member or role to overwrite permissions for.
overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.
**permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit channel specific permissions.
HTTPException – Editing channel specific permissions failed.
NotFound – The role or member being edited is not part of the guild.
TypeError – The overwrite parameter was invalid or the target type was not Role or Member.
ValueError – The overwrite parameter and positions parameters were both unset.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

property voice_states¶

Returns a mapping of member IDs who have voice states in this channel.

New in version 1.3.

Note

This function is intentionally low level to replace members when the member cache is unavailable.

Returns: The mapping of member ID to a voice state.
Return type: Mapping[int, VoiceState]

await webhooks()¶

This function is a coroutine.

Gets the list of webhooks from this channel.

You must have manage_webhooks to do this.

New in version 2.0.

Raises: Forbidden – You don’t have permissions to get the webhooks.
Returns: The webhooks for this channel.
Return type: List[Webhook]

Methods

asyncack
asyncack_pins
asyncapplication_commands
asyncclone
asyncconnect
asynccreate_instance
asynccreate_invite
asynccreate_webhook
asyncdelete
asyncdelete_messages
asyncedit
asyncfetch_instance
asyncfetch_message
defget_partial_message
asyncgreet
async forhistory
asyncinvites
defis_nsfw
asyncmove
defoverwrites_for
defpermissions_for
asyncpins
asyncpurge
defsearch
asyncsend
asyncset_permissions
defslash_commands
deftyping
asyncunack
asyncupload_files
defuser_commands
asyncwebhooks

class discord.StageChannel¶

Represents a Discord guild stage channel.

New in version 1.7.

x == y: Checks if two channels are equal.

x != y: Checks if two channels are not equal.

hash(x): Returns the channel’s hash.

str(x): Returns the channel’s name.

name¶

The channel name.

Type: str

guild¶

The guild the channel belongs to.

Type: Guild

id¶

The channel ID.

Type: int

nsfw¶

If the channel is marked as “not safe for work” or “age restricted”.

New in version 2.0.

Type: bool

topic¶

The channel’s topic. None if it isn’t set.

Type: Optional[str]

category_id¶

The category channel ID this channel belongs to, if applicable.

Type: Optional[int]

position¶

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type: int

bitrate¶

The channel’s preferred audio bitrate in bits per second.

Type: int

user_limit¶

The channel’s limit for number of members that can be in a stage channel.

Type: int

rtc_region¶

The region for the stage channel’s voice communication. A value of None indicates automatic voice region detection.

Type: Optional[str]

video_quality_mode¶

The camera video quality for the stage channel’s participants.

New in version 2.0.

Type: VideoQualityMode

last_message_id¶

The last message ID of the message sent to this channel. It may not point to an existing or valid message.

New in version 2.0.

Type: Optional[int]

last_pin_timestamp¶

When the last pinned message was pinned. None if there are no pinned messages.

New in version 2.0.

Type: Optional[datetime.datetime]

slowmode_delay¶

New in version 2.0.

Type: int

property requesting_to_speak¶

A list of members who are requesting to speak in the stage channel.

Type: List[Member]

property speakers¶

A list of members who have been permitted to speak in the stage channel.

New in version 2.0.

Type: List[Member]

property listeners¶

A list of members who are listening in the stage channel.

New in version 2.0.

Type: List[Member]

property moderators¶

A list of members who are moderating the stage channel.

New in version 2.0.

Type: List[Member]

property type¶

The channel’s Discord type.

Type: ChannelType

await clone(*, name=None, reason=None)¶

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have manage_channels to do this.

New in version 1.1.

Parameters

name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.
reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.

Returns

The channel that was created.

Return type

property instance¶

The running stage instance of the stage channel.

New in version 2.0.

Type: Optional[StageInstance]

await create_instance(*, topic, privacy_level=..., send_start_notification=False, reason=None)¶

This function is a coroutine.

Create a stage instance.

You must have manage_channels to do this.

New in version 2.0.

Parameters

topic (str) – The stage instance’s topic.
privacy_level (PrivacyLevel) – The stage instance’s privacy level. Defaults to PrivacyLevel.guild_only.
send_start_notification (bool) – Whether to send a start notification. This sends a push notification to @everyone if True. Defaults to False. You must have mention_everyone to do this.
reason (str) – The reason the stage instance was created. Shows up on the audit log.

Raises

TypeError – If the privacy_level parameter is not the proper type.
Forbidden – You do not have permissions to create a stage instance.
HTTPException – Creating a stage instance failed.

Returns

The newly created stage instance.

Return type

StageInstance

await fetch_instance()¶

This function is a coroutine.

Gets the running StageInstance.

New in version 2.0.

Raises

NotFound – The stage instance or channel could not be found.
HTTPException – Getting the stage instance failed.

Returns

The stage instance.

Return type

StageInstance

await edit(*, reason=None, **options)¶

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Changed in version 2.0: The topic parameter must now be set via create_instance.

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

Changed in version 2.0: The region parameter now accepts str instead of an enum.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

name (str) – The new channel’s name.
position (int) – The new channel’s position.
nsfw (bool) – To mark the channel as NSFW or not.
user_limit (int) – The new channel’s user limit.
sync_permissions (bool) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to False.
category (Optional[CategoryChannel]) – The new category for this channel. Can be None to remove the category.
slowmode_delay (int) – Specifies the slowmode rate limit for user in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600.
reason (Optional[str]) – The reason for editing this channel. Shows up on the audit log.
overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.
rtc_region (Optional[str]) – The new region for the stage channel’s voice communication. A value of None indicates automatic voice region detection.
video_quality_mode (VideoQualityMode) –
The camera video quality for the stage channel’s participants.

New in version 2.0.

Raises

ValueError – If the permission overwrite information is not in proper form.
Forbidden – You do not have permissions to edit the channel.
HTTPException – Editing the channel failed.

Returns

The newly edited stage channel. If the edit was only positional then None is returned instead.

Return type

Optional[StageChannel]

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

property acked_message¶

Retrieves the last message that the user has acknowledged in cache.

The message might not be valid or point to an existing message.

New in version 2.1.

Reliable Fetching

For a slightly more reliable method of fetching the last acknowledged message, consider using either history() or fetch_message() with the acked_message_id attribute.

Returns: The last acknowledged message in this channel or None if not found.
Return type: Optional[Message]

property acked_message_id¶

The last message ID that the user has acknowledged. It may not point to an existing or valid message.

New in version 2.1.

Type: int

property acked_pin_timestamp¶

When the channel’s pins were last acknowledged.

New in version 2.1.

Type: Optional[datetime.datetime]

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

property category¶

The category this channel belongs to.

If there is no category then this is None.

Type: Optional[CategoryChannel]

property changed_roles¶

Returns a list of roles that have been overridden from their default values in the roles attribute.

Type: List[Role]

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, _channel=None, self_deaf=False, self_mute=False)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
self_mute (bool) –
Indicates if the client should be self-muted.

New in version 2.0.
self_deaf (bool) –
Indicates if the client should be self-deafened.

New in version 2.0.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, guest=False, target_type=None, target_user=None, target_application=None)¶

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have create_instant_invite to do this.

Changed in version 2.1: The validate parameter has been removed.

Parameters

max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.
max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.
temporary (bool) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
guest (bool) –
Denotes that the invite is a guest invite. Guest invites grant temporary membership for the purposes of joining a voice channel. Defaults to False.

New in version 2.1.
unique (bool) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.
target_type (Optional[InviteTarget]) –
The type of target for the voice channel invite, if any.

New in version 2.0.
target_user (Optional[User]) –
The user whose stream to display for this invite, required if target_type is InviteTarget.stream. The user must be streaming in the channel.

New in version 2.0.
target_application: –
Optional[Application]: The embedded application for the invite, required if target_type is InviteTarget.embedded_application.

New in version 2.0.
reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises

HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.
ValueError – target_type is not a creatable invite target type.

Returns

The invite that was created.

Return type

await create_webhook(*, name, avatar=None, reason=None)¶

This function is a coroutine.

Creates a webhook for this channel.

You must have manage_webhooks to do this.

New in version 2.0.

Parameters

name (str) – The webhook’s name.
avatar (Optional[bytes]) – A bytes-like object representing the webhook’s default avatar. This operates similarly to edit().
reason (Optional[str]) – The reason for creating this webhook. Shows up in the audit logs.

Raises

HTTPException – Creating the webhook failed.
Forbidden – You do not have permissions to create a webhook.

Returns

The created webhook.

Return type

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the channel.

You must have manage_channels to do this.

Parameters

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

Raises

Forbidden – You do not have proper permissions to delete the channel.
NotFound – The channel was not found or was already deleted.
HTTPException – Deleting the channel failed.

await delete_messages(messages, /, *, reason=None)¶

This function is a coroutine.

Deletes a list of messages. This is similar to Message.delete() except it bulk deletes multiple messages.

You must have manage_messages to use this (unless they’re your own).

Note

Users do not have access to the message bulk-delete endpoint. Since messages are just iterated over and deleted one-by-one, it’s easy to get ratelimited using this method.

New in version 2.0.

Parameters

messages (Iterable[abc.Snowflake]) – An iterable of messages denoting which ones to bulk delete.
reason (Optional[str]) – The reason for deleting the messages. Shows up on the audit log.

Raises

Forbidden – You do not have proper permissions to delete the messages.
HTTPException – Deleting the messages failed.

await fetch_message(id, /)¶

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

get_partial_message(message_id, /)¶

Creates a PartialMessage from the message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

New in version 2.0.

Parameters: message_id (int) – The message ID to create a partial message for.
Returns: The partial message.
Return type: PartialMessage

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have manage_channels to get this information.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

is_nsfw()¶: bool: Checks if the channel is NSFW.

New in version 2.0.

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

property last_message¶

Retrieves the last message from this channel in cache.

The message might not be valid or point to an existing message.

New in version 2.0.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

Returns: The last message in this channel or None if not found.
Return type: Optional[Message]

property last_viewed_timestamp¶

When the channel was last viewed.

New in version 2.1.

Type: datetime.date

property members¶

Returns all members that are currently inside this voice channel.

Type: List[Member]

property mention¶

The string that allows you to mention the channel.

Type: str

property mention_count¶

Returns how many unread mentions the user has in this channel.

New in version 2.1.

Type: int

await move(**kwargs)¶

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have manage_channels to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.
end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.
before (Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.
offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.
category (Optional[Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.
sync_permissions (bool) – Whether to sync the permissions with the category (if given).
reason (str) – The reason for the move.

Raises

ValueError – An invalid position was given.
TypeError – A bad mix of arguments were passed.
Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property overwrites¶

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Changed in version 2.0: Overwrites can now be type-aware Object in case of cache lookup failure

Returns: The channel’s permission overwrites.
Return type: Dict[Union[Role, Member, Object], PermissionOverwrite]

overwrites_for(obj)¶

Returns the channel-specific overwrites for a member or a role.

Parameters: obj (Union[Role, User, Object]) – The role or user denoting whose overwrite to get.
Returns: The permission overwrites for this object.
Return type: PermissionOverwrite

permissions_for(obj, /)¶

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

Guild owner
Guild roles
Channel overrides
Member overrides
Implicit permissions
Member timeout

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

The default role permissions
The permissions of the role used as a parameter
The default role permission overwrites
The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Changed in version 2.0: obj parameter is now positional-only.

Parameters: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Returns: The resolved permissions for the member or role.
Return type: Permissions

property permissions_synced¶

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type: bool

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=None, reason=None)¶

This function is a coroutine.

Purges a list of messages that meet the criteria given by the predicate check. If a check is not provided then all messages are deleted without discrimination.

Having read_message_history is needed to retrieve message history.

New in version 2.0.

Examples

Deleting bot’s messages

def is_me(m):
    return m.author == client.user

deleted = await channel.purge(limit=100, check=is_me)
await channel.send(f'Deleted {len(deleted)} message(s)')

Parameters

limit (Optional[int]) – The number of messages to search through. This is not the number of messages that will be deleted, though it can be.
check (Callable[[Message], bool]) – The function used to check if a message should be deleted. It must take a Message as its sole parameter.
before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as before in history().
after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as after in history().
around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as around in history().
oldest_first (Optional[bool]) – Same as oldest_first in history().
reason (Optional[str]) – The reason for purging the messages. Shows up on the audit log.

Raises

Forbidden – You do not have proper permissions to do the actions required.
HTTPException – Purging the messages failed.

Returns

The list of messages that were deleted.

Return type

List[Message]

property read_state¶

Returns the read state for this channel.

New in version 2.1.

Type: ReadState

property scheduled_events¶

Returns all scheduled events for this channel.

New in version 2.0.

Type: List[ScheduledEvent]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)¶

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have manage_roles to do this.

Note

This method replaces the old overwrites with the ones given.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, read_messages=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False
overwrite.read_messages = True
await channel.set_permissions(member, overwrite=overwrite)

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

target (Union[Member, Role]) – The member or role to overwrite permissions for.
overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.
**permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit channel specific permissions.
HTTPException – Editing channel specific permissions failed.
NotFound – The role or member being edited is not part of the guild.
TypeError – The overwrite parameter was invalid or the target type was not Role or Member.
ValueError – The overwrite parameter and positions parameters were both unset.

slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property voice_states¶

Returns a mapping of member IDs who have voice states in this channel.

New in version 1.3.

Note

This function is intentionally low level to replace members when the member cache is unavailable.

Returns: The mapping of member ID to a voice state.
Return type: Mapping[int, VoiceState]

await webhooks()¶

This function is a coroutine.

Gets the list of webhooks from this channel.

You must have manage_webhooks to do this.

New in version 2.0.

Raises: Forbidden – You don’t have permissions to get the webhooks.
Returns: The webhooks for this channel.
Return type: List[Webhook]

Methods

asyncclone
asynccounts
asynccreate_entry
asynccreate_invite
asyncdelete
asyncedit
asyncentries
asyncfetch_entries
asyncinvites
asyncmove
defoverwrites_for
defpermissions_for
asyncsearch_entries
asyncset_permissions

class discord.DirectoryChannel¶

Represents a directory channel.

These channels hold entries for guilds attached to a directory (such as a Student Hub).

x == y: Checks if two channels are equal.

x != y: Checks if two channels are not equal.

hash(x): Returns the channel’s hash.

str(x): Returns the channel’s name.

New in version 2.1.

name¶

The channel name.

Type: str

guild¶

The guild the channel belongs to.

Type: Guild

id¶

The channel ID.

Type: int

category_id¶

The category channel ID this channel belongs to, if applicable.

Type: Optional[int]

topic¶

The channel’s topic. None if it doesn’t exist.

Type: Optional[str]

position¶

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type: int

last_message_id¶

The last directory entry ID that was created on this channel. It may not point to an existing or valid directory entry.

Type: Optional[int]

property type¶

The channel’s Discord type.

Type: ChannelType

permissions_for(obj, /)¶

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

Guild owner
Guild roles
Channel overrides
Member overrides
Implicit permissions
Member timeout

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

The default role permissions
The permissions of the role used as a parameter
The default role permission overwrites
The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Changed in version 2.0: obj parameter is now positional-only.

Parameters: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Returns: The resolved permissions for the member or role.
Return type: Permissions

property members¶

Returns all members that can see this channel.

Type: List[Member]

property read_state¶

Returns the read state for this channel.

Type: ReadState

property acked_message_id¶

The last directory entry ID that the user has acknowledged. It may not point to an existing or valid directory entry.

Type: int

property mention_count¶

Returns how many unread directory entries the user has in this channel.

Type: int

property last_viewed_timestamp¶

When the channel was last viewed.

Type: datetime.date

await edit(*, reason=None, **options)¶

This function is a coroutine.

Edits the channel.

You must have manage_channels to do this.

Parameters

name (str) – The new channel name.
topic (str) – The new channel’s topic.
position (int) – The new channel’s position.
sync_permissions (bool) – Whether to sync permissions with the channel’s new or pre-existing category. Defaults to False.
category (Optional[CategoryChannel]) – The new category for this channel. Can be None to remove the category.
reason (Optional[str]) – The reason for editing this channel. Shows up on the audit log.
overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the channel.

Raises

ValueError – The new position is less than 0 or greater than the number of channels.
TypeError – The permission overwrite information is not in proper form.
Forbidden – You do not have permissions to edit the channel.
HTTPException – Editing the channel failed.

Returns

The newly edited directory channel. If the edit was only positional then None is returned instead.

Return type

Optional[DirectoryChannel]

await clone(*, name=None, reason=None)¶

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have manage_channels to do this.

New in version 1.1.

Parameters

name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.
reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.

Returns

The channel that was created.

Return type

await counts()¶

This function is a coroutine.

Gets the number of entries in each category.

Raises

Forbidden – You don’t have permissions to get the counts.
HTTPException – Getting the counts failed.

Returns

The counts for each category.

Return type

Dict[DirectoryCategory, int]

await entries(*, type=None, category=None)¶

This function is a coroutine.

Gets the directory entries in this channel.

Raises

Forbidden – You don’t have permissions to get the entries.
HTTPException – Getting the entries failed.

Returns

The entries in this channel.

Return type

List[DirectoryEntry]

await fetch_entries(*entity_ids)¶

This function is a coroutine.

Gets a list of partial directory entries by their IDs.

Note

These DirectoryEntry objects do not have DirectoryEntry.guild.

Parameters

*entity_ids (int) – The IDs of the entries to fetch.

Raises

Forbidden – You don’t have permissions to get the entries.
HTTPException – Getting the entries failed.

Returns

The entries in this channel.

Return type

List[DirectoryEntry]

await search_entries(query, /, *, category=None)¶

This function is a coroutine.

Searches for directory entries in this channel.

Parameters

query (str) – The query to search for.

Raises

Forbidden – You don’t have permissions to search the entries.
HTTPException – Searching the entries failed.

Returns

The entries in this channel.

Return type

List[DirectoryEntry]

await create_entry(guild, *, category=<DirectoryCategory.uncategorized: 0>, description=None)¶

This function is a coroutine.

Creates a directory entry in this channel.

Parameters

guild (Guild) – The guild to create the entry for.
category (DirectoryCategory) – The category to create the entry in.
description (Optional[str]) – The description of the entry.

Raises

Forbidden – You don’t have permissions to create the entry.
HTTPException – Creating the entry failed.

Returns

The created entry.

Return type

DirectoryEntry

property category¶

The category this channel belongs to.

If there is no category then this is None.

Type: Optional[CategoryChannel]

property changed_roles¶

Returns a list of roles that have been overridden from their default values in the roles attribute.

Type: List[Role]

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, guest=False, target_type=None, target_user=None, target_application=None)¶

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have create_instant_invite to do this.

Changed in version 2.1: The validate parameter has been removed.

Parameters

max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.
max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.
temporary (bool) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
guest (bool) –
Denotes that the invite is a guest invite. Guest invites grant temporary membership for the purposes of joining a voice channel. Defaults to False.

New in version 2.1.
unique (bool) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.
target_type (Optional[InviteTarget]) –
The type of target for the voice channel invite, if any.

New in version 2.0.
target_user (Optional[User]) –
The user whose stream to display for this invite, required if target_type is InviteTarget.stream. The user must be streaming in the channel.

New in version 2.0.
target_application: –
Optional[Application]: The embedded application for the invite, required if target_type is InviteTarget.embedded_application.

New in version 2.0.
reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises

HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.
ValueError – target_type is not a creatable invite target type.

Returns

The invite that was created.

Return type

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the channel.

You must have manage_channels to do this.

Parameters

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

Raises

Forbidden – You do not have proper permissions to delete the channel.
NotFound – The channel was not found or was already deleted.
HTTPException – Deleting the channel failed.

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have manage_channels to get this information.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

property mention¶

The string that allows you to mention the channel.

Type: str

await move(**kwargs)¶

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have manage_channels to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.
end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.
before (Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.
offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.
category (Optional[Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.
sync_permissions (bool) – Whether to sync the permissions with the category (if given).
reason (str) – The reason for the move.

Raises

ValueError – An invalid position was given.
TypeError – A bad mix of arguments were passed.
Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property overwrites¶

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Changed in version 2.0: Overwrites can now be type-aware Object in case of cache lookup failure

Returns: The channel’s permission overwrites.
Return type: Dict[Union[Role, Member, Object], PermissionOverwrite]

overwrites_for(obj)¶

Returns the channel-specific overwrites for a member or a role.

Parameters: obj (Union[Role, User, Object]) – The role or user denoting whose overwrite to get.
Returns: The permission overwrites for this object.
Return type: PermissionOverwrite

property permissions_synced¶

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type: bool

await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)¶

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have manage_roles to do this.

Note

This method replaces the old overwrites with the ones given.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, read_messages=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False
overwrite.read_messages = True
await channel.set_permissions(member, overwrite=overwrite)

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

target (Union[Member, Role]) – The member or role to overwrite permissions for.
overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.
**permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit channel specific permissions.
HTTPException – Editing channel specific permissions failed.
NotFound – The role or member being edited is not part of the guild.
TypeError – The overwrite parameter was invalid or the target type was not Role or Member.
ValueError – The overwrite parameter and positions parameters were both unset.

Methods

async forarchived_threads
asyncclone
asynccreate_invite
asynccreate_tag
asynccreate_thread
asynccreate_webhook
asyncdelete
asyncedit
defget_tag
defget_thread
asyncinvites
defis_nsfw
asyncmove
defoverwrites_for
defpermissions_for
asyncset_permissions
asyncwebhooks

class discord.ForumChannel¶

Represents a Discord guild forum channel.

x == y: Checks if two forums are equal.

x != y: Checks if two forums are not equal.

hash(x): Returns the forum’s hash.

str(x): Returns the forum’s name.

New in version 2.0.

name¶

The forum name.

Type: str

guild¶

The guild the forum belongs to.

Type: Guild

id¶

The forum ID.

Type: int

category_id¶

The category channel ID this forum belongs to, if applicable.

Type: Optional[int]

topic¶

The forum’s topic. None if it doesn’t exist. Called “Guidelines” in the UI. Can be up to 4096 characters long.

Type: Optional[str]

position¶

The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

Type: int

last_message_id¶

The last thread ID that was created on this forum. This technically also coincides with the message ID that started the thread that was created. It may not point to an existing or valid thread or message.

Type: Optional[int]

slowmode_delay¶

The number of seconds a member must wait between creating threads in this forum. A value of 0 denotes that it is disabled. Bots and users with manage_channels or manage_messages bypass slowmode.

Type: int

nsfw¶

If the forum is marked as “not safe for work” or “age restricted”.

Type: bool

default_auto_archive_duration¶

The default auto archive duration in minutes for threads created in this forum.

Type: int

default_thread_slowmode_delay¶

The default slowmode delay in seconds for threads created in this forum.

Type: int

default_reaction_emoji¶

The default reaction emoji for threads created in this forum to show in the add reaction button.

Type: Optional[PartialEmoji]

default_layout¶

The default layout for posts in this forum channel. Defaults to ForumLayoutType.not_set.

Type: ForumLayoutType

default_sort_order¶

The default sort order for posts in this forum channel.

Type: Optional[ForumOrderType]

property type¶

The channel’s Discord type.

Type: ChannelType

permissions_for(obj, /)¶

Handles permission resolution for the Member or Role.

This function takes into consideration the following cases:

Guild owner
Guild roles
Channel overrides
Member overrides
Implicit permissions
Member timeout

If a Role is passed, then it checks the permissions someone with that role would have, which is essentially:

The default role permissions
The permissions of the role used as a parameter
The default role permission overwrites
The permission overwrites of the role used as a parameter

Changed in version 2.0: The object passed in can now be a role object.

Changed in version 2.0: obj parameter is now positional-only.

Parameters: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Returns: The resolved permissions for the member or role.
Return type: Permissions

get_thread(thread_id, /)¶

Returns a thread with the given ID.

Note

This does not always retrieve archived threads, as they are not retained in the internal cache. Use Guild.fetch_channel() instead.

Parameters: thread_id (int) – The ID to search for.
Returns: The returned thread or None if not found.
Return type: Optional[Thread]

property threads¶

Returns all the threads that you can see.

Type: List[Thread]

property flags¶

The flags associated with this forum.

Type: ChannelFlags

property available_tags¶

Returns all the available tags for this forum.

Type: Sequence[ForumTag]

get_tag(tag_id, /)¶

Returns the tag with the given ID.

Parameters: tag_id (int) – The ID to search for.
Returns: The tag with the given ID, or None if not found.
Return type: Optional[ForumTag]

is_nsfw()¶: bool: Checks if the forum is NSFW.

await clone(*, name=None, reason=None)¶

This function is a coroutine.

Clones this channel. This creates a channel with the same properties as this channel.

You must have manage_channels to do this.

New in version 1.1.

Parameters

name (Optional[str]) – The name of the new channel. If not provided, defaults to this channel name.
reason (Optional[str]) – The reason for cloning this channel. Shows up on the audit log.

Raises

Forbidden – You do not have the proper permissions to create this channel.
HTTPException – Creating the channel failed.

Returns

The channel that was created.

Return type

await edit(*, reason=None, **options)¶

This function is a coroutine.

Edits the forum.

You must have manage_channels to do this.

Parameters

name (str) – The new forum name.
topic (str) – The new forum’s topic.
position (int) – The new forum’s position.
nsfw (bool) – To mark the forum as NSFW or not.
sync_permissions (bool) – Whether to sync permissions with the forum’s new or pre-existing category. Defaults to False.
category (Optional[CategoryChannel]) – The new category for this forum. Can be None to remove the category.
slowmode_delay (int) – Specifies the slowmode rate limit for user in this forum, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600.
type (ChannelType) – Change the type of this text forum. Currently, only conversion between ChannelType.text and ChannelType.news is supported. This is only available to guilds that contain NEWS in Guild.features.
reason (Optional[str]) – The reason for editing this forum. Shows up on the audit log.
overwrites (Mapping) – A Mapping of target (either a role or a member) to PermissionOverwrite to apply to the forum.
default_auto_archive_duration (int) – The new default auto archive duration in minutes for threads created in this channel. Must be one of 60, 1440, 4320, or 10080.
available_tags (Sequence[ForumTag]) – The new available tags for this forum.
default_thread_slowmode_delay (int) – The new default slowmode delay for threads in this channel.
default_reaction_emoji (Optional[Union[Emoji, PartialEmoji, str]]) – The new default reaction emoji for threads in this channel.
default_layout (ForumLayoutType) – The new default layout for posts in this forum.
default_sort_order (Optional[ForumOrderType]) – The new default sort order for posts in this forum.
require_tag (bool) – Whether to require a tag for threads in this channel or not.

Raises

ValueError – The new position is less than 0 or greater than the number of channels.
TypeError – The permission overwrite information is not in proper form or a type is not the expected type.
Forbidden – You do not have permissions to edit the forum.
HTTPException – Editing the forum failed.

Returns

The newly edited forum channel. If the edit was only positional then None is returned instead.

Return type

Optional[ForumChannel]

await create_tag(*, name, emoji, moderated=False, reason=None)¶

This function is a coroutine.

Creates a new tag in this forum.

You must have manage_channels to do this.

Parameters

name (str) – The name of the tag. Can only be up to 20 characters.
emoji (Union[str, PartialEmoji]) – The emoji to use for the tag.
moderated (bool) – Whether the tag can only be applied by moderators.
reason (Optional[str]) – The reason for creating this tag. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to create a tag in this forum.
HTTPException – Creating the tag failed.

Returns

The newly created tag.

Return type

ForumTag

await create_thread(*, name, auto_archive_duration=..., slowmode_delay=None, content=None, tts=False, file=..., files=..., stickers=..., allowed_mentions=..., mention_author=..., applied_tags=..., suppress_embeds=False, reason=None)¶

This function is a coroutine.

Creates a thread in this forum.

This thread is a public thread with the initial message given. Currently in order to start a thread in this forum, the user needs send_messages.

You must send at least one of content, embed, embeds, file, files, or view to create a thread in a forum, since forum channels must have a starter message.

Parameters

name (str) – The name of the thread.
auto_archive_duration (int) –
The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

Must be one of 60, 1440, 4320, or 10080, if provided.
slowmode_delay (Optional[int]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is 21600. By default no slowmode rate limit if this is None.
content (Optional[str]) – The content of the message to send with the thread.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (File) – The file to upload.
files (List[File]) – A list of files to upload. Must be a maximum of 10.
allowed_mentions (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.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.
applied_tags (List[discord.ForumTag]) – A list of tags to apply to the thread.
stickers (Sequence[Union[GuildSticker, StickerItem]]) – A list of stickers to upload. Must be a maximum of 3.
suppress_embeds (bool) – Whether to suppress embeds for the message. This sends the message without any embeds if set to True.
reason (str) – The reason for creating a new thread. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to create a thread.
HTTPException – Starting the thread failed.
ValueError – The files or embeds list is not of the appropriate size.
TypeError – You specified both file and files, or you specified both embed and embeds.

Returns

The created thread with the created message. This is also accessible as a namedtuple with thread and message fields.

Return type

Tuple[Thread, Message]

await webhooks()¶

This function is a coroutine.

Gets the list of webhooks from this channel.

You must have manage_webhooks to do this.

Raises: Forbidden – You don’t have permissions to get the webhooks.
Returns: The webhooks for this channel.
Return type: List[Webhook]

await create_webhook(*, name, avatar=None, reason=None)¶

This function is a coroutine.

Creates a webhook for this channel.

You must have manage_webhooks to do this.

Parameters

name (str) – The webhook’s name.
avatar (Optional[bytes]) – A bytes-like object representing the webhook’s default avatar. This operates similarly to edit().
reason (Optional[str]) – The reason for creating this webhook. Shows up in the audit logs.

Raises

HTTPException – Creating the webhook failed.
Forbidden – You do not have permissions to create a webhook.

Returns

The created webhook.

Return type

async for ... in archived_threads(*, limit=100, before=None)¶

Returns an asynchronous iterator that iterates over all archived threads in this forum in order of decreasing Thread.archive_timestamp.

You must have read_message_history to do this.

Parameters

limit (Optional[bool]) – The number of threads to retrieve. If None, retrieves every archived thread in the channel. Note, however, that this would make it a slow operation.
before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve archived channels before the given date or ID.

Raises

Forbidden – You do not have permissions to get archived threads.
HTTPException – The request to get the archived threads failed.

Yields

Thread – The archived threads.

property category¶

The category this channel belongs to.

If there is no category then this is None.

Type: Optional[CategoryChannel]

property changed_roles¶

Returns a list of roles that have been overridden from their default values in the roles attribute.

Type: List[Role]

await create_invite(*, reason=None, max_age=0, max_uses=0, temporary=False, unique=True, guest=False, target_type=None, target_user=None, target_application=None)¶

This function is a coroutine.

Creates an instant invite from a text or voice channel.

You must have create_instant_invite to do this.

Changed in version 2.1: The validate parameter has been removed.

Parameters

max_age (int) – How long the invite should last in seconds. If it’s 0 then the invite doesn’t expire. Defaults to 0.
max_uses (int) – How many uses the invite could be used for. If it’s 0 then there are unlimited uses. Defaults to 0.
temporary (bool) – Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False.
guest (bool) –
Denotes that the invite is a guest invite. Guest invites grant temporary membership for the purposes of joining a voice channel. Defaults to False.

New in version 2.1.
unique (bool) – Indicates if a unique invite URL should be created. Defaults to True. If this is set to False then it will return a previously created invite.
target_type (Optional[InviteTarget]) –
The type of target for the voice channel invite, if any.

New in version 2.0.
target_user (Optional[User]) –
The user whose stream to display for this invite, required if target_type is InviteTarget.stream. The user must be streaming in the channel.

New in version 2.0.
target_application: –
Optional[Application]: The embedded application for the invite, required if target_type is InviteTarget.embedded_application.

New in version 2.0.
reason (Optional[str]) – The reason for creating this invite. Shows up on the audit log.

Raises

HTTPException – Invite creation failed.
NotFound – The channel that was passed is a category or an invalid channel.
ValueError – target_type is not a creatable invite target type.

Returns

The invite that was created.

Return type

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the channel.

You must have manage_channels to do this.

Parameters

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

Raises

Forbidden – You do not have proper permissions to delete the channel.
NotFound – The channel was not found or was already deleted.
HTTPException – Deleting the channel failed.

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

You must have manage_channels to get this information.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

property mention¶

The string that allows you to mention the channel.

Type: str

await move(**kwargs)¶

This function is a coroutine.

A rich interface to help move a channel relative to other channels.

If exact position movement is required, edit should be used instead.

You must have manage_channels to do this.

Note

Voice channels will always be sorted below text channels. This is a Discord limitation.

New in version 1.7.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

beginning (bool) – Whether to move the channel to the beginning of the channel list (or category if given). This is mutually exclusive with end, before, and after.
end (bool) – Whether to move the channel to the end of the channel list (or category if given). This is mutually exclusive with beginning, before, and after.
before (Snowflake) – The channel that should be before our current channel. This is mutually exclusive with beginning, end, and after.
after (Snowflake) – The channel that should be after our current channel. This is mutually exclusive with beginning, end, and before.
offset (int) – The number of channels to offset the move by. For example, an offset of 2 with beginning=True would move it 2 after the beginning. A positive number moves it below while a negative number moves it above. Note that this number is relative and computed after the beginning, end, before, and after parameters.
category (Optional[Snowflake]) – The category to move this channel under. If None is given then it moves it out of the category. This parameter is ignored if moving a category channel.
sync_permissions (bool) – Whether to sync the permissions with the category (if given).
reason (str) – The reason for the move.

Raises

ValueError – An invalid position was given.
TypeError – A bad mix of arguments were passed.
Forbidden – You do not have permissions to move the channel.
HTTPException – Moving the channel failed.

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property overwrites¶

Returns all of the channel’s overwrites.

This is returned as a dictionary where the key contains the target which can be either a Role or a Member and the value is the overwrite as a PermissionOverwrite.

Changed in version 2.0: Overwrites can now be type-aware Object in case of cache lookup failure

Returns: The channel’s permission overwrites.
Return type: Dict[Union[Role, Member, Object], PermissionOverwrite]

overwrites_for(obj)¶

Returns the channel-specific overwrites for a member or a role.

Parameters: obj (Union[Role, User, Object]) – The role or user denoting whose overwrite to get.
Returns: The permission overwrites for this object.
Return type: PermissionOverwrite

property permissions_synced¶

Whether or not the permissions for this channel are synced with the category it belongs to.

If there is no category then this is False.

New in version 1.3.

Type: bool

await set_permissions(target, *, overwrite=see - below, reason=None, **permissions)¶

This function is a coroutine.

Sets the channel specific permission overwrites for a target in the channel.

The target parameter should either be a Member or a Role that belongs to guild.

If the overwrite parameter is None, then the permission overwrites are deleted.

You must have manage_roles to do this.

Note

This method replaces the old overwrites with the ones given.

Examples

Setting allow and deny:

await message.channel.set_permissions(message.author, read_messages=True,
                                                      send_messages=False)

Deleting overwrites

await channel.set_permissions(member, overwrite=None)

overwrite = discord.PermissionOverwrite()
overwrite.send_messages = False
overwrite.read_messages = True
await channel.set_permissions(member, overwrite=overwrite)

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

target (Union[Member, Role]) – The member or role to overwrite permissions for.
overwrite (Optional[PermissionOverwrite]) – The permissions to allow and deny to the target, or None to delete the overwrite.
**permissions – A keyword argument list of permissions to set for ease of use. Cannot be mixed with overwrite.
reason (Optional[str]) – The reason for doing this action. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit channel specific permissions.
HTTPException – Editing channel specific permissions failed.
NotFound – The role or member being edited is not part of the guild.
TypeError – The overwrite parameter was invalid or the target type was not Role or Member.
ValueError – The overwrite parameter and positions parameters were both unset.

PrivateChannel¶

Attributes

acked_message
acked_message_id
acked_pin_timestamp
call
created_at
guild
id
jump_url
last_message
last_message_id
last_pin_timestamp
last_viewed_timestamp
me
mention_count
notification_settings
read_state
recipient
requested_at
type

Methods

asyncaccept
asyncack
asyncack_pins
asyncapplication_commands
asyncclose
asyncconnect
asyncdecline
asyncfetch_message
defget_partial_message
asyncgreet
async forhistory
defis_accepted
defis_message_request
defis_spam
defpermissions_for
asyncpins
defsearch
asyncsend
defslash_commands
deftyping
asyncunack
asyncupload_files
defuser_commands

class discord.DMChannel¶

Represents a Discord direct message channel.

x == y: Checks if two channels are equal.

x != y: Checks if two channels are not equal.

hash(x): Returns the channel’s hash.

str(x): Returns a string representation of the channel

id¶

The direct message channel ID.

Type: int

recipient¶

The user you are participating with in the direct message channel.

Type: User

me¶

The user presenting yourself.

Type: ClientUser

last_message_id¶

The last message ID of the message sent to this channel. It may not point to an existing or valid message.

New in version 2.0.

Type: Optional[int]

last_pin_timestamp¶

When the last pinned message was pinned. None if there are no pinned messages.

New in version 2.0.

Type: Optional[datetime.datetime]

async with typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

async for ... in slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

async for ... in user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property call¶

The channel’s currently active call.

Type: Optional[PrivateCall]

property type¶

The channel’s Discord type.

Type: ChannelType

property created_at¶

Returns the direct message channel’s creation time in UTC.

Type: datetime.datetime

property guild¶

The guild this DM channel belongs to. Always None.

This is mainly provided for compatibility purposes in duck typing.

New in version 2.0.

Type: Optional[Guild]

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

property read_state¶

Returns the read state for this channel.

New in version 2.1.

Type: ReadState

property last_message¶

Retrieves the last message from this channel in cache.

The message might not be valid or point to an existing message.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

Returns: The last message in this channel or None if not found.
Return type: Optional[Message]

property acked_message_id¶

The last message ID that the user has acknowledged. It may not point to an existing or valid message.

New in version 2.1.

Type: int

property acked_message¶

Retrieves the last message that the user has acknowledged in cache.

The message might not be valid or point to an existing message.

New in version 2.1.

Reliable Fetching

For a slightly more reliable method of fetching the last acknowledged message, consider using either history() or fetch_message() with the acked_message_id attribute.

Returns: The last acknowledged message in this channel or None if not found.
Return type: Optional[Message]

property acked_pin_timestamp¶

When the channel’s pins were last acknowledged.

New in version 2.1.

Type: Optional[datetime.datetime]

property mention_count¶

Returns how many unread mentions the user has in this channel.

New in version 2.1.

Type: int

property last_viewed_timestamp¶

When the channel was last viewed.

New in version 2.1.

Type: datetime.date

property requested_at¶

Returns the message request’s creation time in UTC, if applicable.

New in version 2.0.

Type: Optional[datetime.datetime]

is_message_request()¶: bool: Indicates if the direct message is/was a message request.

New in version 2.0.

is_accepted()¶: bool: Indicates if the message request is accepted. For regular direct messages, this is always True.

New in version 2.0.

is_spam()¶: bool: Indicates if the direct message is a spam message request.

New in version 2.0.

permissions_for(obj=None, /)¶

Handles permission resolution for a User.

This function is there for compatibility with other channel types.

Actual direct messages do not really have the concept of permissions.

This returns all the Text related permissions set to True except:

send_tts_messages: You cannot send TTS messages in a DM.
manage_messages: You cannot delete others messages in a DM.
create_private_threads: There are no threads in a DM.
create_public_threads: There are no threads in a DM.
manage_threads: There are no threads in a DM.
send_messages_in_threads: There are no threads in a DM.

Changed in version 2.0: obj parameter is now positional-only.

Changed in version 2.0: Thread related permissions are now set to False.

Parameters: obj (Snowflake) – The user to check permissions for. This parameter is ignored but kept for compatibility with other permissions_for methods.
Returns: The resolved permissions.
Return type: Permissions

get_partial_message(message_id, /)¶

Creates a PartialMessage from the message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

New in version 1.6.

Changed in version 2.0: message_id parameter is now positional-only.

Parameters: message_id (int) – The message ID to create a partial message for.
Returns: The partial message.
Return type: PartialMessage

await close()¶

This function is a coroutine.

Closes/”deletes” the channel.

In reality, if you recreate a DM with the same user, all your message history will be there.

Raises: HTTPException – Closing the channel failed.

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, ring=True)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
ring (bool) – Whether to ring the other member(s) to join the call, if starting a new call. Defaults to True.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await accept()¶

This function is a coroutine.

Accepts a message request.

Raises

HTTPException – Accepting the message request failed.
TypeError – The channel is not a message request or the request is already accepted.

await decline()¶

This function is a coroutine.

Declines a message request. This closes the channel.

Raises

HTTPException – Declining the message request failed.
TypeError – The channel is not a message request or the request is already accepted.

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

await fetch_message(id, /)¶

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

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

Methods

asyncack
asyncack_pins
asyncadd_recipients
asyncapplication_commands
asyncclose
asyncconnect
asynccreate_invite
asyncedit
asyncfetch_message
asyncgreet
async forhistory
asyncinvites
asyncleave
defpermissions_for
asyncpins
asyncremove_recipients
defsearch
asyncsend
defslash_commands
deftyping
asyncunack
asyncupload_files
defuser_commands

class discord.GroupChannel¶

Represents a Discord group channel.

x == y: Checks if two channels are equal.

x != y: Checks if two channels are not equal.

hash(x): Returns the channel’s hash.

str(x): Returns a string representation of the channel

last_message_id¶

The last message ID of the message sent to this channel. It may not point to an existing or valid message.

New in version 2.0.

Type: Optional[int]

last_pin_timestamp¶

When the last pinned message was pinned. None if there are no pinned messages.

New in version 2.0.

Type: Optional[datetime.datetime]

recipients¶

The users you are participating with in the group channel.

Type: List[User]

me¶

The user presenting yourself.

Type: ClientUser

id¶

The group channel ID.

Type: int

owner_id¶

The owner ID that owns the group channel.

New in version 2.0.

Type: int

managed¶

Whether the group channel is managed by an application.

This restricts the operations that can be performed on the channel, and means owner will usually be None.

New in version 2.0.

Type: bool

application_id¶

The ID of the managing application, if any.

New in version 2.0.

Type: Optional[int]

name¶

The group channel’s name if provided.

Type: Optional[str]

nicks¶

A mapping of users to their respective nicknames in the group channel.

New in version 2.0.

Type: Dict[User, str]

async with typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

async for ... in slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

async for ... in user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property notification_settings¶

Returns the notification settings for this channel.

If not found, an instance is created with defaults applied. This follows Discord behaviour.

New in version 2.0.

Type: ChannelSettings

property owner¶

The owner that owns the group channel.

Type: Optional[User]

property call¶

The channel’s currently active call.

Type: Optional[PrivateCall]

property type¶

The channel’s Discord type.

Type: ChannelType

property guild¶

The guild this group channel belongs to. Always None.

This is mainly provided for compatibility purposes in duck typing.

New in version 2.0.

Type: Optional[Guild]

property icon¶

Returns the channel’s icon asset if available.

Type: Optional[Asset]

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

property jump_url¶

Returns a URL that allows the client to jump to the channel.

New in version 2.0.

Type: str

property read_state¶

Returns the read state for this channel.

New in version 2.1.

Type: ReadState

property last_message¶

Retrieves the last message from this channel in cache.

The message might not be valid or point to an existing message.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

Returns: The last message in this channel or None if not found.
Return type: Optional[Message]

property acked_message_id¶

The last message ID that the user has acknowledged. It may not point to an existing or valid message.

New in version 2.1.

Type: int

property acked_message¶

Retrieves the last message that the user has acknowledged in cache.

The message might not be valid or point to an existing message.

New in version 2.1.

Reliable Fetching

For a slightly more reliable method of fetching the last acknowledged message, consider using either history() or fetch_message() with the acked_message_id attribute.

Returns: The last acknowledged message in this channel or None if not found.
Return type: Optional[Message]

property acked_pin_timestamp¶

When the channel’s pins were last acknowledged.

New in version 2.1.

Type: Optional[datetime.datetime]

property mention_count¶

Returns how many unread mentions the user has in this channel.

New in version 2.1.

Type: int

property last_viewed_timestamp¶

When the channel was last viewed.

New in version 2.1.

Type: datetime.date

permissions_for(obj, /)¶

Handles permission resolution for a User.

This function is there for compatibility with other channel types.

Actual direct messages do not really have the concept of permissions.

If a recipient, this returns all the Text related permissions set to True except:

send_tts_messages: You cannot send TTS messages in a DM.
manage_messages: You cannot delete others messages in a DM.
create_private_threads: There are no threads in a DM.
create_public_threads: There are no threads in a DM.
manage_threads: There are no threads in a DM.
send_messages_in_threads: There are no threads in a DM.

This also checks the kick_members permission if the user is the owner.

Changed in version 2.0: obj parameter is now positional-only.

Changed in version 2.0: Thread related permissions are now set to False, and managed channel permissions are taken into account.

Parameters: obj (Snowflake) – The user to check permissions for.
Returns: The resolved permissions for the user.
Return type: Permissions

await add_recipients(*recipients, nicks=None)¶

This function is a coroutine.

Adds recipients to this group.

A group can only have a maximum of 10 members. Attempting to add more ends up in an exception. To add a recipient to the group, you must have a relationship with the user of type RelationshipType.friend.

Parameters

*recipients (Snowflake) – An argument list of users to add to this group. If the user is of type Object, then the nick attribute is used as the nickname for the added recipient.
nicks (Optional[Mapping[Snowflake, str]]) –
A mapping of user IDs to nicknames to use for the added recipients.

New in version 2.0.

Raises

Forbidden – You do not have permissions to add a recipient to this group.
HTTPException – Adding a recipient to this group failed.

await remove_recipients(*recipients)¶

This function is a coroutine.

Removes recipients from this group.

Parameters

*recipients (Snowflake) – An argument list of users to remove from this group.

Raises

Forbidden – You do not have permissions to remove a recipient from this group.
HTTPException – Removing a recipient from this group failed.

await edit(*, name=..., icon=..., owner=...)¶

This function is a coroutine.

Edits the group.

Changed in version 2.0: Edits are no longer in-place, the newly edited channel is returned instead.

Parameters

name (Optional[str]) – The new name to change the group to. Could be None to remove the name.
icon (Optional[bytes]) – A bytes-like object representing the new icon. Could be None to remove the icon.
owner (Snowflake) –
The new owner of the group.

New in version 2.0.

Raises

HTTPException – Editing the group failed.

await leave(*, silent=False)¶

This function is a coroutine.

Leave the group.

If you are the only one in the group, this deletes it as well.

There is an alias for this called close().

Parameters: silent (bool) – Whether to leave the group without sending a leave message.
Raises: HTTPException – Leaving the group failed.

await close(*, silent=False)¶

This function is a coroutine.

Leave the group.

If you are the only one in the group, this deletes it as well.

This is an alias of leave().

Parameters: silent (bool) – Whether to leave the group without sending a leave message.
Raises: HTTPException – Leaving the group failed.

await invites()¶

This function is a coroutine.

Returns a list of all active instant invites from this channel.

New in version 2.0.

Raises

Forbidden – You do not have proper permissions to get the information.
HTTPException – An error occurred while fetching the information.

Returns

The list of invites that are currently active.

Return type

List[Invite]

await create_invite(*, max_age=86400)¶

This function is a coroutine.

Creates an instant invite from a group channel.

New in version 2.0.

Parameters: max_age (int) – How long the invite should last in seconds. Defaults to 86400. Does not support 0.
Raises: HTTPException – Invite creation failed.
Returns: The invite that was created.
Return type: Invite

await connect(*, timeout=60.0, reconnect=True, cls=<class 'discord.voice_client.VoiceClient'>, ring=True)¶

This function is a coroutine.

Connects to voice and creates a VoiceClient to establish your connection to the voice server.

Parameters

timeout (float) – The timeout in seconds to wait for the voice endpoint.
reconnect (bool) – Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down.
cls (Type[VoiceProtocol]) – A type that subclasses VoiceProtocol to connect with. Defaults to VoiceClient.
ring (bool) – Whether to ring the other member(s) to join the call, if starting a new call. Defaults to True.

Raises

asyncio.TimeoutError – Could not connect to the voice channel in time.
ClientException – You are already connected to a voice channel.
OpusNotLoaded – The opus library has not been loaded.

Returns

A voice client that is fully connected to the voice server.

Return type

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

await fetch_message(id, /)¶

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

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

PartialMessageable¶

Attributes

created_at
guild
guild_id
id
jump_url
name
read_state
type

Methods

asyncack
asyncack_pins
asyncapplication_commands
asyncfetch_message
defget_partial_message
asyncgreet
async forhistory
defpermissions_for
asyncpins
defsearch
asyncsend
defslash_commands
deftyping
asyncunack
asyncupload_files
defuser_commands

class discord.PartialMessageable¶

Represents a partial messageable to aid with working messageable channels when only a channel ID is present.

The only way to construct this class is through Client.get_partial_messageable().

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

x == y: Checks if two partial messageables are equal.

x != y: Checks if two partial messageables are not equal.

hash(x): Returns the partial messageable’s hash.

New in version 2.0.

id¶

The channel ID associated with this partial messageable.

Type: int

type¶

The channel type associated with this partial messageable, if given.

Type: Optional[ChannelType]

name¶

The channel name associated with this partial messageable, if given.

Type: Optional[str]

guild_id¶

The guild ID associated with this partial messageable.

Type: Optional[int]

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

await fetch_message(id, /)¶

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

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property guild¶

The guild this partial messageable is in.

Type: Optional[Guild]

property jump_url¶

Returns a URL that allows the client to jump to the channel.

Type: str

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

property read_state¶

Returns the read state for this channel.

New in version 2.1.

Type: ReadState

permissions_for(obj=None, /)¶

Handles permission resolution for a User.

This function is there for compatibility with other channel types.

Since partial messageables cannot reasonably have the concept of permissions, this will always return Permissions.none().

Parameters: obj (User) – The user to check permissions for. This parameter is ignored but kept for compatibility with other permissions_for methods.
Returns: The resolved permissions.
Return type: Permissions

get_partial_message(message_id, /)¶

Creates a PartialMessage from the message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

Parameters: message_id (int) – The message ID to create a partial message for.
Returns: The partial message.
Return type: PartialMessage

Thread¶

Methods

asyncack
asyncack_pins
asyncadd_tags
asyncadd_user
asyncapplication_commands
asyncdelete
asyncdelete_messages
asyncedit
asyncfetch_members
asyncfetch_message
defget_partial_message
asyncgreet
async forhistory
defis_news
defis_nsfw
defis_private
asyncjoin
asyncleave
defpermissions_for
asyncpins
asyncpurge
asyncremove_tags
asyncremove_user
defsearch
asyncsend
defslash_commands
deftyping
asyncunack
asyncupload_files
defuser_commands

class discord.Thread¶

Represents a Discord thread.

x == y: Checks if two threads are equal.

x != y: Checks if two threads are not equal.

hash(x): Returns the thread’s hash.

str(x): Returns the thread’s name.

New in version 2.0.

name¶

The thread name.

Type: str

guild¶

The guild the thread belongs to.

Type: Guild

id¶

The thread ID. This is the same as the thread starter message ID.

Type: int

parent_id¶

The ID of the parent TextChannel or ForumChannel this thread belongs to.

Type: int

owner_id¶

The ID of the user that created this thread.

Type: int

last_message_id¶

The last message ID of the message sent to this thread. It may not point to an existing or valid message.

Type: Optional[int]

last_pin_timestamp¶

When the last pinned message was pinned. None if there are no pinned messages.

Type: Optional[datetime.datetime]

slowmode_delay¶

The number of seconds a member must wait between sending messages in this thread. A value of 0 denotes that it is disabled. Bots and users with manage_channels or manage_messages bypass slowmode.

Type: int

message_count¶

An approximate number of messages in this thread.

Type: int

member_count¶

An approximate number of members in this thread. This caps at 50.

Type: int

archived¶

Whether the thread is archived.

Type: bool

locked¶

Whether the thread is locked.

Type: bool

invitable¶

Whether non-moderators can add other non-moderators to this thread. This is always True for public threads.

Type: bool

auto_archive_duration¶

The duration in minutes until the thread is automatically hidden from the channel list. Usually a value of 60, 1440, 4320 and 10080.

Type: int

archive_timestamp¶

An aware timestamp of when the thread’s archived status was last updated in UTC.

Type: datetime.datetime

async with typing()¶

Returns an asynchronous context manager that allows you to send a typing indicator to the destination for an indefinite period of time, or 10 seconds if the context manager is called using await.

Example Usage:

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

await channel.send('Done!')

Example Usage:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

Changed in version 2.0: This no longer works with the with syntax, async with must be used instead.

Changed in version 2.0: Added functionality to await the context manager to send a typing indicator for 10 seconds.

async for ... in slash_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the slash commands available in the channel.

Deprecated since version 2.1.

Examples

Usage

async for command in channel.slash_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in channel.slash_commands()]
# commands is now a list of SlashCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

SlashCommand – A slash command.

async for ... in user_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the user commands available to use on the user.

Deprecated since version 2.1.

Examples

Usage

async for command in user.user_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in user.user_commands()]
# commands is now a list of UserCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0. Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

UserCommand – A user command.

property type¶

The channel’s Discord type.

Type: ChannelType

property parent¶

The parent channel this thread belongs to.

There is an alias for this named channel.

Type: Optional[Union[ForumChannel, TextChannel]]

property channel¶

The parent channel this thread belongs to.

This is an alias of parent.

Type: Optional[Union[ForumChannel, TextChannel]]

property flags¶

The flags associated with this thread.

Type: ChannelFlags

property owner¶

The member this thread belongs to.

Type: Optional[Member]

property mention¶

The string that allows you to mention the thread.

Type: str

property created_at¶

Returns the thread’s creation time in UTC.

Note

This may be inaccurate for threads created before January 9th, 2022.

Type: datetime.datetime

property jump_url¶

Returns a URL that allows the client to jump to the thread.

Type: str

property members¶

A list of thread members in this thread.

Initial members are not provided by Discord. You must call fetch_members().

Type: List[ThreadMember]

property applied_tags¶

A list of tags applied to this thread.

Type: List[ForumTag]

property read_state¶

Returns the read state for this channel.

New in version 2.1.

Type: ReadState

property starter_message¶

Returns the thread starter message from the cache.

The message might not be cached, valid, or point to an existing message.

Note that the thread starter message ID is the same ID as the thread.

Returns: The thread starter message or None if not found.
Return type: Optional[Message]

property last_message¶

Returns the last message from this thread from the cache.

The message might not be valid or point to an existing message.

Reliable Fetching

For a slightly more reliable method of fetching the last message, consider using either history() or fetch_message() with the last_message_id attribute.

Returns: The last message in this channel or None if not found.
Return type: Optional[Message]

property acked_message_id¶

The last message ID that the user has acknowledged. It may not point to an existing or valid message.

New in version 2.1.

Type: int

property acked_message¶

Retrieves the last message that the user has acknowledged in cache.

The message might not be valid or point to an existing message.

New in version 2.1.

Reliable Fetching

For a slightly more reliable method of fetching the last acknowledged message, consider using either history() or fetch_message() with the acked_message_id attribute.

Returns: The last acknowledged message in this channel or None if not found.
Return type: Optional[Message]

property acked_pin_timestamp¶

When the channel’s pins were last acknowledged.

New in version 2.1.

Type: Optional[datetime.datetime]

property mention_count¶

Returns how many unread mentions the user has in this channel.

New in version 2.1.

Type: int

property last_viewed_timestamp¶

When the channel was last viewed.

New in version 2.1.

Type: datetime.date

property category¶

The category channel the parent channel belongs to, if applicable.

Raises: ClientException – The parent channel was not cached and returned None.
Returns: The parent channel’s category.
Return type: Optional[CategoryChannel]

property category_id¶

The category channel ID the parent channel belongs to, if applicable.

Raises: ClientException – The parent channel was not cached and returned None.
Returns: The parent channel’s category ID.
Return type: Optional[int]

property me¶

A thread member representing yourself, if you’ve joined the thread.

This might not be available.

Type: Optional[ThreadMember]

is_private()¶

bool: Whether the thread is a private thread.

A private thread is only viewable by those that have been explicitly invited or have manage_threads.

is_news()¶

bool: Whether the thread is a news thread.

A news thread is a thread that has a parent that is a news channel, i.e. TextChannel.is_news() is True.

is_nsfw()¶

bool: Whether the thread is NSFW or not.

An NSFW thread is a thread that has a parent that is an NSFW channel, i.e. TextChannel.is_nsfw() is True.

permissions_for(obj, /)¶

Handles permission resolution for the Member or Role.

Since threads do not have their own permissions, they mostly inherit them from the parent channel with some implicit permissions changed.

Parameters: obj (Union[Member, Role]) – The object to resolve permissions for. This could be either a member or a role. If it’s a role then member overwrites are not computed.
Raises: ClientException – The parent channel was not cached and returned None
Returns: The resolved permissions for the member or role.
Return type: Permissions

await delete_messages(messages, /, *, reason=None)¶

This function is a coroutine.

Deletes a list of messages. This is similar to Message.delete() except it bulk deletes multiple messages.

You must have manage_messages to use this (unless they’re your own).

Note

Users do not have access to the message bulk-delete endpoint. Since messages are just iterated over and deleted one-by-one, it’s easy to get ratelimited using this method.

Parameters

messages (Iterable[abc.Snowflake]) – An iterable of messages denoting which ones to bulk delete.
reason (Optional[str]) – The reason for deleting the messages. Shows up on the audit log.

Raises

Forbidden – You do not have proper permissions to delete the messages.
HTTPException – Deleting the messages failed.

await purge(*, limit=100, check=..., before=None, after=None, around=None, oldest_first=None, reason=None)¶

This function is a coroutine.

Purges a list of messages that meet the criteria given by the predicate check. If a check is not provided then all messages are deleted without discrimination.

Having read_message_history is needed to retrieve message history.

Examples

Deleting bot’s messages

def is_me(m):
    return m.author == client.user

deleted = await channel.purge(limit=100, check=is_me)
await channel.send(f'Deleted {len(deleted)} message(s)')

Parameters

limit (Optional[int]) – The number of messages to search through. This is not the number of messages that will be deleted, though it can be.
check (Callable[[Message], bool]) – The function used to check if a message should be deleted. It must take a Message as its sole parameter.
before (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as before in history().
after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as after in history().
around (Optional[Union[abc.Snowflake, datetime.datetime]]) – Same as around in history().
oldest_first (Optional[bool]) – Same as oldest_first in history().
reason (Optional[str]) – The reason for purging the messages. Shows up on the audit log.

Raises

Forbidden – You do not have proper permissions to do the actions required.
HTTPException – Purging the messages failed.

Returns

The list of messages that were deleted.

Return type

List[Message]

await edit(*, name=..., archived=..., locked=..., invitable=..., pinned=..., slowmode_delay=..., auto_archive_duration=..., applied_tags=..., reason=None)¶

This function is a coroutine.

Edits the thread.

Editing the thread requires Permissions.manage_threads. The thread creator can also edit name, archived or auto_archive_duration. Note that if the thread is locked then only those with Permissions.manage_threads can unarchive a thread.

The thread must be unarchived to be edited.

Parameters

name (str) – The new name of the thread.
archived (bool) – Whether to archive the thread or not.
locked (bool) – Whether to lock the thread or not.
pinned (bool) – Whether to pin the thread or not. This only works if the thread is part of a forum.
invitable (bool) – Whether non-moderators can add other non-moderators to this thread. Only available for private threads.
auto_archive_duration (int) – The new duration in minutes before a thread is automatically hidden from the channel list. Must be one of 60, 1440, 4320, or 10080.
slowmode_delay (int) – Specifies the slowmode rate limit for user in this thread, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600.
applied_tags (Sequence[ForumTag]) – The new tags to apply to the thread. There can only be up to 5 tags applied to a thread.
reason (Optional[str]) – The reason for editing this thread. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to edit the thread.
HTTPException – Editing the thread failed.

Returns

The newly edited thread.

Return type

await add_tags(*tags, reason=None)¶

This function is a coroutine.

Adds the given forum tags to a thread.

You must have manage_threads to use this or the thread must be owned by you.

Tags that have ForumTag.moderated set to True require manage_threads to be added.

The maximum number of tags that can be added to a thread is 5.

The parent channel must be a ForumChannel.

Parameters

*tags (abc.Snowflake) – An argument list of abc.Snowflake representing a ForumTag to add to the thread.
reason (Optional[str]) – The reason for adding these tags.

Raises

Forbidden – You do not have permissions to add these tags.
HTTPException – Adding tags failed.

await remove_tags(*tags, reason=None)¶

This function is a coroutine.

Remove the given forum tags to a thread.

You must have manage_threads to use this or the thread must be owned by you.

The parent channel must be a ForumChannel.

Parameters

*tags (abc.Snowflake) – An argument list of abc.Snowflake representing a ForumTag to remove to the thread.
reason (Optional[str]) – The reason for removing these tags.

Raises

Forbidden – You do not have permissions to remove these tags.
HTTPException – Removing tags failed.

await join()¶

This function is a coroutine.

Joins this thread.

You must have send_messages_in_threads to join a thread. If the thread is private, manage_threads is also needed.

Raises

Forbidden – You do not have permissions to join the thread.
HTTPException – Joining the thread failed.

await leave()¶

This function is a coroutine.

Leaves this thread.

Raises: HTTPException – Leaving the thread failed.

await add_user(user, /)¶

This function is a coroutine.

Adds a user to this thread.

You must have send_messages_in_threads to add a user to a thread. If the thread is private and invitable is False then manage_messages is required to add a user to the thread.

Parameters

user (abc.Snowflake) – The user to add to the thread.

Raises

Forbidden – You do not have permissions to add the user to the thread.
HTTPException – Adding the user to the thread failed.

await remove_user(user, /)¶

This function is a coroutine.

Removes a user from this thread.

You must have manage_threads or be the creator of the thread to remove a user.

Parameters

user (abc.Snowflake) – The user to remove from the thread.

Raises

Forbidden – You do not have permissions to remove the user from the thread.
HTTPException – Removing the user from the thread failed.

await fetch_members()¶

This function is a coroutine.

Retrieves all ThreadMember that are in this thread, along with their respective Member.

Raises: InvalidData – Discord didn’t respond with the members.
Returns: All thread members in the thread.
Return type: List[ThreadMember]

await delete()¶

This function is a coroutine.

Deletes this thread.

You must have manage_threads to delete threads.

Raises

Forbidden – You do not have permissions to delete this thread.
HTTPException – Deleting the thread failed.

get_partial_message(message_id, /)¶

Creates a PartialMessage from the message ID.

This is useful if you want to work with a message and only have its ID without doing an unnecessary API call.

Parameters: message_id (int) – The message ID to create a partial message for.
Returns: The partial message.
Return type: PartialMessage

await ack()¶

This function is a coroutine.

Marks every message in this channel as read.

New in version 1.9.

Raises: HTTPException – Acking the channel failed.

await ack_pins()¶

This function is a coroutine.

Marks a channel’s pins as viewed.

New in version 1.9.

Raises: HTTPException – Acking the pinned messages failed.

await application_commands()¶

This function is a coroutine.

Returns a list of application commands available in the channel.

New in version 2.1.

Note

Commands that the user does not have permission to use will not be returned.

Raises

TypeError – Attempted to fetch commands in a DM with a non-bot user.
ValueError – Could not resolve the channel’s guild ID.
HTTPException – Getting the commands failed.

Returns

A list of application commands.

Return type

List[Union[SlashCommand, UserCommand, MessageCommand]]

await fetch_message(id, /)¶

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

await greet(sticker, *, allowed_mentions=..., reference=..., mention_author=...)¶

This function is a coroutine.

Sends a sticker greeting to the destination.

A sticker greeting is used to begin a new DM or reply to a system message.

New in version 2.0.

Parameters

sticker (Union[GuildSticker, StickerItem]) – The sticker to greet with.
allowed_mentions (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. In the case of greeting, only replied_user is considered.
reference (Union[Message, MessageReference, PartialMessage]) – A reference to the Message to which you are replying, this can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.
mention_author (bool) – If set, overrides the replied_user attribute of allowed_mentions.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.
TypeError – The reference object is not a Message, MessageReference or PartialMessage.

Returns

The sticker greeting that was sent.

Return type

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

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

You must have read_message_history to do 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 = [message async for message in channel.history(limit=123)]
# 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[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[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[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.

await pins()¶

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

Forbidden – You do not have the permission to retrieve pinned messages.
HTTPException – Retrieving the pinned messages failed.

Returns

The messages that are currently pinned.

Return type

List[Message]

Returns an asynchronous iterator that enables searching the channel’s messages.

You must have read_message_history to do this.

Note

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

New in version 2.1.

Examples

Usage

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

Flattening into a list:

messages = [message async for message in channel.search('test', limit=123)]
# messages is now a list of Message...

All parameters are optional.

Parameters

content (str) – The message content to search for.
limit (Optional[int]) – The number of messages to retrieve. If None, retrieves every message in the results. Note, however, that this would make it a slow operation. Additionally, note that the search API has a maximum pagination offset of 5000 (subject to change), so a limit of over 5000 or None may eventually raise an exception.
offset (int) – The pagination offset to start at.
before (Union[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 (Union[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.
authors (List[User]) – The authors to filter by.
author_types (List[str]) – The author types to filter by. Can be one of user, bot, or webhook. These can be negated by prefixing with -, which will exclude them.
mentions (List[User]) – The mentioned users to filter by.
mention_everyone (bool) – Whether to filter by messages that do or do not mention @everyone.
pinned (bool) – Whether to filter by messages that are or are not pinned.
has (List[str]) – The message attributes to filter by. Can be one of image, sound, video, file, sticker, embed, or link. These can be negated by prefixing with -, which will exclude them.
embed_types (List[str]) – The embed types to filter by.
embed_providers (List[str]) – The embed providers to filter by (e.g. tenor).
link_hostnames (List[str]) – The link hostnames to filter by (e.g. google.com).
attachment_filenames (List[str]) – The attachment filenames to filter by.
attachment_extensions (List[str]) – The attachment extensions to filter by (e.g. txt).
application_commands (List[ApplicationCommand]) – The used application commands to filter by.
oldest_first (bool) – Whether to return the oldest results first.
most_relevant (bool) – Whether to sort the results by relevance. Using this with oldest_first will return the least relevant results first.

Raises

Forbidden – You do not have permissions to search the channel’s messages.
HTTPException – The request to search messages failed.
ValueError – Could not resolve the channel’s guild ID.

Yields

Message – The message with the message data parsed.

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). If the content is set to None (the default), then a sticker or file must be sent.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Parameters

content (Optional[str]) – The content of the message to send.
tts (bool) – Indicates if the message should be sent using text-to-speech.
file (Union[File, CloudFile]) – The file to upload.
files (List[Union[File, CloudFile]]) – A list of files to upload. Must be a maximum of 10.
nonce (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. Generates one by default.
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 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.

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 to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

New in version 1.6.
mention_author (Optional[bool]) –
If set, overrides the replied_user attribute of allowed_mentions.

New in version 1.6.
stickers (Sequence[Union[GuildSticker, StickerItem]]) –
A list of stickers to upload. Must be a maximum of 3.

New in version 2.0.
suppress_embeds (bool) –
Whether to suppress embeds for the message. This sends the message without any embeds if set to True.

New in version 2.0.
silent (bool) –
Whether to suppress push and desktop notifications for the message. This will increment the mention counter in the UI, but will not actually send a notification.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size.
TypeError – You specified both file and files, or the reference object is not a Message, MessageReference or PartialMessage.

Returns

The message that was sent.

Return type

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks every message in this channel as unread. This manually sets the read state to a message ID of 0.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking the channel failed.

await upload_files(*files)¶

This function is a coroutine.

Pre-uploads files to Discord’s GCP bucket for use with send().

This method is useful if you have local files that you want to upload and reuse multiple times.

New in version 2.1.

Parameters

*files (File) – A list of files to upload. Must be a maximum of 10.

Raises

HTTPException – Uploading the files failed.
Forbidden – You do not have the proper permissions to upload files.

Returns

The files that were uploaded. These can be used in lieu of normal Files in send().

Return type

List[CloudFile]

Attributes

flags
id
joined_at
member
thread
thread_id

class discord.ThreadMember¶

Represents a Discord thread member.

x == y: Checks if two thread members are equal.

x != y: Checks if two thread members are not equal.

hash(x): Returns the thread member’s hash.

str(x): Returns the thread member’s name.

New in version 2.0.

id¶

The thread member’s ID.

Type: int

thread_id¶

The thread’s ID.

Type: int

joined_at¶

The time the member joined the thread in UTC. Only reliably available for yourself or members joined while the client is connected to the Gateway.

Type: Optional[datetime.datetime]

flags¶

The thread member’s flags. Will be its own class in the future. Only reliably available for yourself or members joined while the client is connected to the Gateway.

Type: int

property thread¶

The thread this member belongs to.

Type: Thread

property member¶

The member this ThreadMember represents. If the member is not cached then this will be None.

Type: Optional[Member]

StageInstance¶

Attributes

channel
channel_id
discoverable
discoverable_disabled
guild
id
invite_code
invite_url
participant_count
privacy_level
scheduled_event
scheduled_event_id
speakers
topic

Methods

asyncdelete
asyncedit

class discord.StageInstance¶

Represents a stage instance of a stage channel in a guild.

New in version 2.0.

x == y: Checks if two stage instances are equal.

x != y: Checks if two stage instances are not equal.

hash(x): Returns the stage instance’s hash.

id¶

The stage instance’s ID.

Type: int

guild¶

The guild that the stage instance is running in.

Type: Guild

channel_id¶

The ID of the channel that the stage instance is running in.

Type: int

topic¶

The topic of the stage instance.

Type: str

privacy_level¶

The privacy level of the stage instance.

Type: PrivacyLevel

discoverable_disabled¶

Whether discoverability for the stage instance is disabled.

Type: bool

invite_code¶

The invite code of the stage instance, if public.

New in version 2.1.

Type: Optional[str]

scheduled_event_id¶

The ID of the scheduled event that belongs to the stage instance, if any.

New in version 2.0.

Type: Optional[int]

property invite_url¶

The stage instance’s invite URL, if public.

New in version 2.1.

Type: Optional[str]

property discoverable¶

Whether the stage instance is discoverable.

Type: bool

property channel¶

The channel that stage instance is running in.

Type: Optional[StageChannel]

property scheduled_event¶

The scheduled event that belongs to the stage instance.

Type: Optional[ScheduledEvent]

property speakers¶

The members that are speaking in the stage instance.

New in version 2.1.

Type: List[Member]

property participant_count¶

The number of participants in the stage instance.

New in version 2.1.

Type: int

await edit(*, topic=..., privacy_level=..., reason=None)¶

This function is a coroutine.

Edits the stage instance.

You must have manage_channels to do this.

Parameters

topic (str) – The stage instance’s new topic.
privacy_level (PrivacyLevel) – The stage instance’s new privacy level.
reason (str) – The reason the stage instance was edited. Shows up on the audit log.

Raises

TypeError – If the privacy_level parameter is not the proper type.
Forbidden – You do not have permissions to edit the stage instance.
HTTPException – Editing a stage instance failed.

await delete(*, reason=None)¶

This function is a coroutine.

Deletes the stage instance.

You must have manage_channels to do this.

Parameters

reason (str) – The reason the stage instance was deleted. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to delete the stage instance.
HTTPException – Deleting the stage instance failed.

Call¶

Attributes

channel
connected
initiator
members
message
region
ringing
unavailable
voice_states

Methods

asyncchange_region
asyncfetch_message
defvoice_state_for

class discord.PrivateCall¶

Represents the actual group call from Discord.

This is accompanied with a CallMessage denoting the information.

New in version 1.9.

channel¶

The channel the call is in.

Type: DMChannel

unavailable¶

Denotes if this call is unavailable.

Type: bool

region¶

The region the call is being hosted at.

Changed in version 2.0: The type of this attribute has changed to str.

Type: str

property ringing¶

A list of users that are currently being rung to join the call.

Type: List[abc.User]

property initiator¶

Returns the user that started the call. Returns None if the message is not cached.

Type: Optional[abc.User]

property connected¶

Returns whether you’re in the call (this does not mean you’re in the call through the library).

Type: bool

property members¶

Returns all users that are currently in this call.

Type: List[abc.User]

property voice_states¶

Returns a mapping of user IDs who have voice states in this call.

Type: Mapping[int, VoiceState]

message¶

The message associated with this call. Sometimes may not be cached.

Type: Optional[Message]

await fetch_message()¶

This function is a coroutine.

Fetches and caches the message associated with this call.

Raises: HTTPException – Retrieving the message failed.
Returns: The message associated with this call.
Return type: Message

await change_region(region)¶

This function is a coroutine.

Changes the channel’s voice region.

Parameters

region (str) –

A region to change the voice region to.

Changed in version 2.0: The type of this parameter has changed to str.

Raises

HTTPException – Failed to change the channel’s voice region.

voice_state_for(user)¶

Retrieves the VoiceState for a specified User.

If the User has no voice state then this function returns None.

Parameters: user (User) – The user to retrieve the voice state for.
Returns: The voice state associated with this user.
Return type: Optional[VoiceState]

Attributes

channel
connected
initiator
members
message
region
ringing
unavailable
voice_states

Methods

asyncchange_region
asyncfetch_message
defvoice_state_for

class discord.GroupCall¶

Represents a Discord group call.

This is accompanied with a CallMessage denoting the information.

channel¶

The channel the group call is in.

Type: GroupChannel

unavailable¶

Denotes if this group call is unavailable.

Type: bool

region¶

The region the group call is being hosted in.

Changed in version 2.0: The type of this attribute has changed to str.

Type: str

await change_region(region)¶

This function is a coroutine.

Changes the channel’s voice region.

Parameters

region (str) –

A region to change the voice region to.

Changed in version 2.0: The type of this parameter has changed to str.

Raises

HTTPException – Failed to change the channel’s voice region.

property connected¶

Returns whether you’re in the call (this does not mean you’re in the call through the library).

Type: bool

await fetch_message()¶

This function is a coroutine.

Fetches and caches the message associated with this call.

Raises: HTTPException – Retrieving the message failed.
Returns: The message associated with this call.
Return type: Message

property initiator¶

Returns the user that started the call. Returns None if the message is not cached.

Type: Optional[abc.User]

property members¶

Returns all users that are currently in this call.

Type: List[abc.User]

message¶

The message associated with this call. Sometimes may not be cached.

Type: Optional[Message]

property ringing¶

A list of users that are currently being rung to join the call.

Type: List[abc.User]

voice_state_for(user)¶

Retrieves the VoiceState for a specified User.

If the User has no voice state then this function returns None.

Parameters: user (User) – The user to retrieve the voice state for.
Returns: The voice state associated with this user.
Return type: Optional[VoiceState]

property voice_states¶

Returns a mapping of user IDs who have voice states in this call.

Type: Mapping[int, VoiceState]

Attributes

call_ended
channel
duration
ended_timestamp
initiator
message
participants

class discord.CallMessage¶

Represents a group call message from Discord.

This is only received in cases where the message type is equivalent to MessageType.call.

ended_timestamp¶

An aware UTC datetime object that represents the time that the call has ended.

Type: Optional[datetime.datetime]

participants¶

A list of users that participated in the call.

Type: List[User]

message¶

The message associated with this call message.

Type: Message

property call_ended¶

Indicates if the call has ended.

Type: bool

property initiator¶

Returns the user that started the call.

Type: abc.User

property channel¶

The private channel associated with this message.

Type: abc.PrivateChannel

property duration¶

Queries the duration of the call.

If the call has not ended then the current duration will be returned.

Returns: The timedelta object representing the duration.
Return type: datetime.timedelta

Message¶

Methods

asyncack
asyncadd_files
asyncadd_reaction
asyncclear_reaction
asyncclear_reactions
asynccreate_thread
asyncdelete
asyncedit
asyncfetch
asyncgreet
defis_acked
defis_system
defmessage_commands
asyncpin
asyncpublish
asyncremove_attachments
asyncremove_reaction
asyncreply
defto_reference
asyncunack
asyncunpin

class discord.Message¶

Represents a message from Discord.

x == y: Checks if two messages are equal.

x != y: Checks if two messages are not equal.

hash(x): Returns the message’s hash.

tts¶

Specifies if the message was done with text-to-speech. This can only be accurately received in on_message() due to a discord limitation.

Type: bool

type¶

The type of message. In most cases this should not be checked, but it is helpful in cases where it might be a system message for system_content.

Type: MessageType

author¶

A Member that sent the message. If channel is a private channel or the user has the left the guild, then it is a User instead.

Type: Union[Member, abc.User]

content¶

The actual contents of the message.

Type: str

nonce¶

The value used by Discord clients to verify that the message is successfully sent. This is not stored long term within Discord’s servers and is only used ephemerally.

Type: Optional[Union[str, int]]

embeds¶

A list of embeds the message has.

Type: List[Embed]

channel¶

The TextChannel or Thread that the message was sent from. Could be a DMChannel or GroupChannel if it’s a private message.

Type: Union[TextChannel, StageChannel, VoiceChannel, Thread, DMChannel, GroupChannel, PartialMessageable]

call¶

The call that the message refers to. This is only applicable to messages of type MessageType.call.

Type: Optional[CallMessage]

reference¶

The message that this message references. This is only applicable to messages of type MessageType.pins_add, crossposted messages created by a followed channel integration, or message replies.

New in version 1.5.

Type: Optional[MessageReference]

mention_everyone¶

Specifies if the message mentions everyone.

Note

This does not check if the @everyone or the @here text is in the message itself. Rather this boolean indicates if either the @everyone or the @here text is in the message and it did end up mentioning.

Type: bool

mentions¶

A list of Member that were mentioned. If the message is in a private message then the list will be of User instead. For messages that are not of type MessageType.default, this array can be used to aid in system messages. For more information, see system_content.

Warning

The order of the mentions list is not in any particular order so you should not rely on it. This is a Discord limitation, not one with the library.

Type: List[abc.User]

channel_mentions¶

A list of abc.GuildChannel or Thread that were mentioned. If the message is in a private message then the list is always empty.

Type: List[Union[abc.GuildChannel, Thread]]

role_mentions¶

A list of Role that were mentioned. If the message is in a private message then the list is always empty.

Type: List[Role]

id¶

The message ID.

Type: int

webhook_id¶

If this message was sent by a webhook, then this is the webhook ID’s that sent this message.

Type: Optional[int]

attachments¶

A list of attachments given to a message.

Type: List[Attachment]

pinned¶

Specifies if the message is currently pinned.

Type: bool

flags¶

Extra features of the message.

New in version 1.3.

Type: MessageFlags

reactions¶

Reactions to a message. Reactions can be either custom emoji or standard unicode emoji.

Type: List[Reaction]

activity¶

The activity associated with this message. Sent with Rich-Presence related messages that for example, request joining, spectating, or listening to or with another member.

It is a dictionary with the following optional keys:

type: An integer denoting the type of message activity being requested.
party_id: The party ID associated with the party.

Type: Optional[dict]

application¶

The rich presence enabled application associated with this message.

Changed in version 2.0: Type is now IntegrationApplication instead of dict.

Type: Optional[IntegrationApplication]

stickers¶

A list of sticker items given to the message.

New in version 1.6.

Type: List[StickerItem]

components¶

A list of components in the message.

New in version 2.0.

Type: List[Union[ActionRow, Button, SelectMenu]]

role_subscription¶

The data of the role subscription purchase or renewal that prompted this MessageType.role_subscription_purchase message.

New in version 2.0.

Type: Optional[RoleSubscriptionInfo]

application_id¶

The application ID of the application that created this message if this message was sent by an application-owned webhook or an interaction.

New in version 2.0.

Type: Optional[int]

position¶

A generally increasing integer with potentially gaps or duplicates that represents the approximate position of the message in a thread.

New in version 2.0.

Type: Optional[int]

guild_id¶

The ID of the guild that the partial message belongs to, if applicable.

New in version 2.1.

Type: Optional[int]

guild¶

The guild that the message belongs to, if applicable.

Type: Optional[Guild]

interaction¶

The interaction that this message is a response to.

New in version 2.0.

Type: Optional[Interaction]

hit¶

Whether the message was a hit in a search result. As surrounding messages are no longer returned in search results, this is always True for search results.

New in version 2.1.

Type: bool

total_results¶

The total number of results for the search query. This is only present in search results.

New in version 2.1.

Type: Optional[int]

analytics_id¶

The search results analytics ID. This is only present in search results.

New in version 2.1.

Type: Optional[str]

doing_deep_historical_index¶

The status of the document’s current deep historical indexing operation, if any. This is only present in search results.

New in version 2.1.

Type: Optional[bool]

async for ... in message_commands(query=None, *, limit=None, command_ids=None, application=None, with_applications=True)¶

Returns a asynchronous iterator of the message commands available to use on the message.

Deprecated since version 2.1.

Examples

Usage

async for command in message.message_commands():
    print(command.name)

Flattening into a list

commands = [command async for command in message.message_commands()]
# commands is now a list of MessageCommand...

All parameters are optional.

Parameters

query (Optional[str]) – The query to search for. Specifying this limits results to 25 commands max.
limit (Optional[int]) – The maximum number of commands to send back. If None, returns all commands.
command_ids (Optional[List[int]]) –
List of up to 100 command IDs to search for. If the command doesn’t exist, it won’t be returned.

If limit is passed alongside this parameter, this parameter will serve as a “preferred commands” list. This means that the endpoint will return the found commands + up to limit more, if available.
application (Optional[Snowflake]) – Whether to return this application’s commands. Always set to DM recipient in a private channel context.
with_applications (bool) – Whether to include applications in the response.

Raises

TypeError – Both query and command_ids are passed. Attempted to fetch commands in a DM with a non-bot user.
ValueError – The limit was not greater than or equal to 0.
HTTPException – Getting the commands failed.
Forbidden – You do not have permissions to get the commands.
HTTPException – The request to get the commands failed.

Yields

MessageCommand – A message command.

raw_mentions¶

A property that returns an array of user IDs matched with the syntax of <@user_id> in the message content.

This allows you to receive the user IDs of mentioned users even in a private message context.

Type: List[int]

await ack(*, manual=False, mention_count=None)¶

This function is a coroutine.

Marks this message as read.

Note

This sets the last acknowledged message to this message, which will mark acknowledged messages created after this one as unread.

Parameters

manual (bool) –
Whether to manually set the channel read state to this message.

New in version 2.1.
mention_count (Optional[int]) –
The mention count to set the channel read state to. Only applicable for manual acknowledgements.

New in version 2.1.

Raises

HTTPException – Acking failed.

await add_reaction(emoji, /)¶

This function is a coroutine.

Adds a reaction to the message.

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

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

Changed in version 2.0: emoji parameter is now positional-only.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

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.
TypeError – 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 must have manage_messages to do this.

New in version 1.3.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

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.
TypeError – The emoji parameter is invalid.

await clear_reactions()¶

This function is a coroutine.

Removes all the reactions from the message.

You must have manage_messages to do this.

Raises

HTTPException – Removing the reactions failed.
Forbidden – You do not have the proper permissions to remove all the reactions.

await create_thread(*, name, auto_archive_duration=..., slowmode_delay=None, reason=None)¶

This function is a coroutine.

Creates a public thread from this message.

You must have create_public_threads in order to create a public thread from a message.

The channel this message belongs in must be a TextChannel.

New in version 2.0.

Parameters

name (str) – The name of the thread.
auto_archive_duration (int) –
The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

Must be one of 60, 1440, 4320, or 10080, if provided.
slowmode_delay (Optional[int]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is 21600. By default no slowmode rate limit if this is None.
reason (Optional[str]) – The reason for creating a new thread. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to create a thread.
HTTPException – Creating the thread failed.
ValueError – This message does not have guild info attached.

Returns

The created thread.

Return type

await delete(*, delay=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 must have manage_messages.

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.

Raises

Forbidden – You do not have proper permissions to delete the message.
NotFound – The message was deleted already
HTTPException – Deleting the message failed.

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

await greet(sticker, **kwargs)¶

This function is a coroutine.

A shortcut method to abc.Messageable.greet() to reply to the Message with a sticker greeting.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.

Returns

The sticker greeting that was sent.

Return type

property jump_url¶

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

Type: str

await pin(*, reason=None)¶

This function is a coroutine.

Pins the message.

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

Parameters

reason (Optional[str]) –

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

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

await publish()¶

This function is a coroutine.

Publishes this message to the channel’s followers.

The message must have been sent in a news channel. You must have send_messages to do this.

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

Raises

Forbidden – You do not have the proper permissions to publish this message or the channel is not a news channel.
HTTPException – Publishing the message failed.

raw_channel_mentions¶

A property that returns an array of channel IDs matched with the syntax of <#channel_id> in the message content.

Type: List[int]

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 manage_messages is needed.

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

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

emoji (Union[Emoji, Reaction, PartialEmoji, str]) – The emoji to remove.
member (abc.Snowflake) – The member for which to remove the reaction.

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.
TypeError – The emoji parameter is invalid.

await reply(content=None, **kwargs)¶

This function is a coroutine.

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

New in version 1.6.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size
TypeError – You specified both file and files.

Returns

The message that was sent.

Return type

to_reference(*, fail_if_not_exists=True)¶

Creates a MessageReference from the current message.

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

New in version 1.7.

Returns

The reference to this message.

Return type

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks this message as unread. This manually sets the read state to the current message’s ID - 1.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking failed.

await unpin(*, reason=None)¶

This function is a coroutine.

Unpins the message.

You must have manage_messages 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.

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

raw_role_mentions¶

A property that returns an array of role IDs matched with the syntax of <@&role_id> in the message content.

Type: List[int]

clean_content¶

A property that returns the content in a “cleaned up” manner. This basically means that mentions are transformed into the way the client shows it. e.g. <#id> will transform into #name.

This will also transform @everyone and @here mentions into non-mentions.

Note

This does not affect markdown. If you want to escape or remove markdown then use utils.escape_markdown() or utils.remove_markdown() respectively, along with this function.

Type: str

property created_at¶

The message’s creation time in UTC.

Type: datetime.datetime

property edited_at¶

An aware UTC datetime object containing the edited time of the message.

Type: Optional[datetime.datetime]

is_system()¶

bool: Whether the message is a system message.

A system message is a message that is constructed entirely by the Discord API in response to something.

New in version 1.3.

is_acked()¶: bool: Whether the message has been marked as read.

New in version 2.1.

system_content¶

A property that returns the content that is rendered regardless of the Message.type.

In the case of MessageType.default and MessageType.reply, this just returns the regular Message.content. Otherwise this returns an English message denoting the contents of the system message.

Type: str

await edit(content=..., attachments=..., suppress=False, delete_after=None, allowed_mentions=...)¶

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: Edits are no longer in-place, the newly edited message is returned instead.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

content (Optional[str]) – The new content to replace the message with. Could be None to remove the content.
attachments (List[Union[Attachment, File, CloudFile]]) –
A list of attachments to keep in the message as well as new files to upload. If [] is passed then all attachments are removed.

Note

New files will always appear after current attachments.

New in version 2.0.
suppress (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. Using this parameter requires manage_messages.
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.

New in version 1.4.

Raises

HTTPException – Editing the message failed.
Forbidden – Tried to suppress a message without permissions or edit a message that isn’t yours.

Returns

The newly edited message.

Return type

await add_files(*files)¶

This function is a coroutine.

Adds new files to the end of the message attachments.

New in version 2.0.

Parameters

*files (Union[File, CloudFile]) – New files to add to the message.

Raises

HTTPException – Editing the message failed.
Forbidden – Tried to edit a message that isn’t yours.

Returns

The newly edited message.

Return type

await remove_attachments(*attachments)¶

This function is a coroutine.

Removes attachments from the message.

New in version 2.0.

Parameters

*attachments (Attachment) – Attachments to remove from the message.

Raises

HTTPException – Editing the message failed.
Forbidden – Tried to edit a message that isn’t yours.

Returns

The newly edited message.

Return type

Attributes

channel
created_at
guild
guild_id
id
jump_url

Methods

asyncack
asyncadd_reaction
asyncclear_reaction
asyncclear_reactions
asynccreate_thread
asyncdelete
asyncedit
asyncfetch
asyncgreet
asyncpin
asyncpublish
asyncremove_reaction
asyncreply
defto_reference
asyncunack
asyncunpin

class discord.PartialMessage¶

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 the following:

TextChannel.get_partial_message()
VoiceChannel.get_partial_message()
StageChannel.get_partial_message()
Thread.get_partial_message()
DMChannel.get_partial_message()

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

New 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[PartialMessageable, TextChannel, StageChannel, VoiceChannel, Thread, DMChannel]

id¶

The message ID.

Type: int

guild_id¶

The ID of the guild that the partial message belongs to, if applicable.

New in version 2.1.

Type: Optional[int]

guild¶

The guild that the partial message belongs to, if applicable.

Type: Optional[Guild]

property created_at¶

The partial message’s creation time in UTC.

Type: datetime.datetime

property jump_url¶

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

Type: str

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

await delete(*, delay=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 must have manage_messages.

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.

Raises

Forbidden – You do not have proper permissions to delete the message.
NotFound – The message was deleted already
HTTPException – Deleting the message failed.

await edit(content=..., attachments=..., delete_after=None, allowed_mentions=...)¶

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 2.0: Edits are no longer in-place, the newly edited message is returned instead.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

content (Optional[str]) – The new content to replace the message with. Could be None to remove the content.
attachments (List[Union[Attachment, File, CloudFile]]) –
A list of attachments to keep in the message as well as new files to upload. If [] is passed then all attachments are removed.

Note

New files will always appear after current attachments.

New in version 2.0.
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.

New in version 1.4.

Raises

HTTPException – Editing the message failed.
Forbidden – Tried to suppress a message without permissions or edited a message’s content or embed that isn’t yours.
TypeError – You specified both embed and embeds

Returns

The newly edited message.

Return type

await publish()¶

This function is a coroutine.

Publishes this message to the channel’s followers.

The message must have been sent in a news channel. You must have send_messages to do this.

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

Raises

Forbidden – You do not have the proper permissions to publish this message or the channel is not a news channel.
HTTPException – Publishing the message failed.

await pin(*, reason=None)¶

This function is a coroutine.

Pins the message.

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

Parameters

reason (Optional[str]) –

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

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

await unpin(*, reason=None)¶

This function is a coroutine.

Unpins the message.

You must have manage_messages 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.

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

Adds a reaction to the message.

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

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

Changed in version 2.0: emoji parameter is now positional-only.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

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.
TypeError – 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 manage_messages is needed.

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

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

Parameters

emoji (Union[Emoji, Reaction, PartialEmoji, str]) – The emoji to remove.
member (abc.Snowflake) – The member for which to remove the reaction.

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.
TypeError – 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 must have manage_messages to do this.

New in version 1.3.

Changed in version 2.0: This function will now raise TypeError instead of InvalidArgument.

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.
TypeError – The emoji parameter is invalid.

await clear_reactions()¶

This function is a coroutine.

Removes all the reactions from the message.

You must have manage_messages to do this.

Raises

HTTPException – Removing the reactions failed.
Forbidden – You do not have the proper permissions to remove all the reactions.

await create_thread(*, name, auto_archive_duration=..., slowmode_delay=None, reason=None)¶

This function is a coroutine.

Creates a public thread from this message.

You must have create_public_threads in order to create a public thread from a message.

The channel this message belongs in must be a TextChannel.

New in version 2.0.

Parameters

name (str) – The name of the thread.
auto_archive_duration (int) –
The duration in minutes before a thread is automatically hidden from the channel list. If not provided, the channel’s default auto archive duration is used.

Must be one of 60, 1440, 4320, or 10080, if provided.
slowmode_delay (Optional[int]) – Specifies the slowmode rate limit for user in this channel, in seconds. The maximum value possible is 21600. By default no slowmode rate limit if this is None.
reason (Optional[str]) – The reason for creating a new thread. Shows up on the audit log.

Raises

Forbidden – You do not have permissions to create a thread.
HTTPException – Creating the thread failed.
ValueError – This message does not have guild info attached.

Returns

The created thread.

Return type

await ack(*, manual=False, mention_count=None)¶

This function is a coroutine.

Marks this message as read.

Note

This sets the last acknowledged message to this message, which will mark acknowledged messages created after this one as unread.

Parameters

manual (bool) –
Whether to manually set the channel read state to this message.

New in version 2.1.
mention_count (Optional[int]) –
The mention count to set the channel read state to. Only applicable for manual acknowledgements.

New in version 2.1.

Raises

HTTPException – Acking failed.

await unack(*, mention_count=None)¶

This function is a coroutine.

Marks this message as unread. This manually sets the read state to the current message’s ID - 1.

New in version 2.1.

Parameters: mention_count (Optional[int]) – The mention count to set the channel read state to.
Raises: HTTPException – Unacking failed.

await reply(content=None, **kwargs)¶

This function is a coroutine.

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

New in version 1.6.

Changed in version 2.0: This function will now raise TypeError or ValueError instead of InvalidArgument.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message.
ValueError – The files list is not of the appropriate size
TypeError – You specified both file and files.

Returns

The message that was sent.

Return type

await greet(sticker, **kwargs)¶

This function is a coroutine.

A shortcut method to abc.Messageable.greet() to reply to the Message with a sticker greeting.

New in version 2.0.

Raises

HTTPException – Sending the message failed.
Forbidden – You do not have the proper permissions to send the message, or this is not a valid greet context.

Returns

The sticker greeting that was sent.

Return type

to_reference(*, fail_if_not_exists=True)¶

Creates a MessageReference from the current message.

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

New in version 1.7.

Returns

The reference to this message.

Return type

Attributes

content_type
description
duration
ephemeral
filename
flags
height
id
proxy_url
size
url
waveform
width

Methods

defis_spoiler
defis_voice_message
asyncread
asyncsave
asyncto_file

class discord.Attachment¶

Represents an attachment from Discord.

str(x): Returns the URL of the attachment.

x == y: Checks if the attachment is equal to another attachment.

x != y: Checks if the attachment is not equal to another attachment.

hash(x): Returns the hash of the attachment.

Changed in version 1.7: Attachment can now be casted to str and is hashable.

id¶

The attachment ID.

Type: int

size¶

The attachment size in bytes.

Type: int

height¶

The attachment’s height, in pixels. Only applicable to images and videos.

Type: Optional[int]

width¶

The attachment’s width, in pixels. Only applicable to images and videos.

Type: Optional[int]

filename¶

The attachment’s filename.

Type: str

url¶

The attachment URL. If the message this attachment was attached to is deleted, then this will 404.

Type: str

proxy_url¶

The proxy URL. This is a cached version of the url in the case of images. When the message is deleted, this URL might be valid for a few minutes or not valid at all.

Type: str

content_type¶

The attachment’s media type

New in version 1.7.

Type: Optional[str]

description¶

The attachment’s description. Only applicable to images.

New in version 2.0.

Type: Optional[str]

ephemeral¶

Whether the attachment is ephemeral.

New in version 2.0.

Type: bool

duration¶

The duration of the audio file in seconds. Returns None if it’s not a voice message.

New in version 2.1.

Type: Optional[float]

waveform¶

The waveform (amplitudes) of the audio in bytes. Returns None if it’s not a voice message.

New in version 2.1.

Type: Optional[bytes]

property flags¶

The attachment’s flags.

Type: AttachmentFlags

is_spoiler()¶: bool: Whether this attachment contains a spoiler.

is_voice_message()¶: bool: Whether this attachment is a voice message.

New in version 2.1.

await save(fp, *, seek_begin=True, use_cached=False)¶

This function is a coroutine.

Saves this attachment into a file-like object.

Parameters

fp (Union[io.BufferedIOBase, os.PathLike]) – The file-like object to save this attachment to or the filename to use. If a filename is passed then a file is created with that filename and used instead.
seek_begin (bool) – Whether to seek to the beginning of the file after saving is successfully done.
use_cached (bool) – Whether to use proxy_url rather than url when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

Raises

HTTPException – Saving the attachment failed.
NotFound – The attachment was deleted.

Returns

The number of bytes written.

Return type

await read(*, use_cached=False)¶

This function is a coroutine.

Retrieves the content of this attachment as a bytes object.

New in version 1.1.

Parameters

use_cached (bool) – Whether to use proxy_url rather than url when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

Raises

HTTPException – Downloading the attachment failed.
Forbidden – You do not have permissions to access this attachment
NotFound – The attachment was deleted.

Returns

The contents of the attachment.

Return type

await to_file(*, filename=..., description=..., use_cached=False, spoiler=False)¶

This function is a coroutine.

Converts the attachment into a File suitable for sending via abc.Messageable.send().

New in version 1.3.

Parameters

filename (Optional[str]) –
The filename to use for the file. If not specified then the filename of the attachment is used instead.

New in version 2.0.
description (Optional[str]) –
The description to use for the file. If not specified then the description of the attachment is used instead.

New in version 2.0.
use_cached (bool) –
Whether to use proxy_url rather than url when downloading the attachment. This will allow attachments to be saved after deletion more often, compared to the regular URL which is generally deleted right after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed and it does not work on some types of attachments.

New in version 1.4.
spoiler (bool) –
Whether the file is a spoiler.

New in version 1.4.

Raises

HTTPException – Downloading the attachment failed.
Forbidden – You do not have permissions to access this attachment
NotFound – The attachment was deleted.

Returns

The attachment as a file suitable for sending.

Return type

Attributes

cached_message
channel_id
fail_if_not_exists
guild_id
jump_url
message_id
resolved

Methods

clsMessageReference.from_message

class discord.MessageReference¶

Represents a reference to a Message.

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

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

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

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

New in version 1.7.

Returns

A reference to the message.

Return type

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.

New in version 1.7.

Type: str

Attributes

channel_id
guild_id
id

class discord.DeletedReferencedMessage¶

A special sentinel type given when the resolved message reference points to a deleted message.

The purpose of this class is to separate referenced messages that could not be fetched and those that were previously fetched but have since been deleted.

New in version 1.6.

property id¶

The message ID of the deleted referenced message.

Type: int

property channel_id¶

The channel ID of the deleted referenced message.

Type: int

property guild_id¶

The guild ID of the deleted referenced message.

Type: Optional[int]

Attributes

is_renewal
role_subscription_listing_id
tier_name
total_months_subscribed

class discord.RoleSubscriptionInfo¶

Represents a message’s role subscription information.

This is currently only attached to messages of type MessageType.role_subscription_purchase.

New in version 2.0.

role_subscription_listing_id¶

The ID of the SKU and listing that the user is subscribed to.

Type: int

tier_name¶

The name of the tier that the user is subscribed to.

Type: str

total_months_subscribed¶

The cumulative number of months that the user has been subscribed for.

Type: int

is_renewal¶

Whether this notification is for a renewal rather than a new purchase.

Type: bool

Reaction¶

Attributes

count
emoji
me
message

Methods

asyncclear
defis_custom_emoji
asyncremove
async forusers

class discord.Reaction¶

Represents a reaction to a message.

Depending on the way this object was created, some of the attributes can have a value of None.

x == y: Checks if two reactions are equal. This works by checking if the emoji is the same. So two messages with the same reaction will be considered “equal”.

x != y: Checks if two reactions are not equal.

hash(x): Returns the reaction’s hash.

str(x): Returns the string form of the reaction’s emoji.

emoji¶

The reaction emoji. May be a custom emoji, or a unicode emoji.

Type: Union[Emoji, PartialEmoji, str]

count¶

Number of times this reaction was made

Type: int

me¶

If the user sent this reaction.

Type: bool

message¶

Message this reaction is for.

Type: Message

is_custom_emoji()¶: bool: If this is a custom emoji.

await remove(user)¶

This function is a coroutine.

Remove the reaction by the provided User from the message.

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

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

Parameters

user (abc.Snowflake) – The user or member from which to remove the reaction.

Raises

HTTPException – Removing the reaction failed.
Forbidden – You do not have the proper permissions to remove the reaction.
NotFound – The user you specified, or the reaction’s message was not found.

await clear()¶

This function is a coroutine.

Clears this reaction from the message.

You must have manage_messages to do this.

New in version 1.3.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

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.
TypeError – The emoji parameter is invalid.

async for ... in users(*, limit=None, after=None)¶

Returns an asynchronous iterator representing the users that have reacted to the message.

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

Changed in version 2.0: limit and after parameters are now keyword-only.

Examples

Usage

# I do not actually recommend doing this
async for user in reaction.users():
    await channel.send(f'{user} has reacted with {reaction.emoji}!')

Flattening into a list:

users = [user async for user in reaction.users()]
# users is now a list of User...
winner = random.choice(users)
await channel.send(f'{winner} has won the raffle.')

Parameters

limit (Optional[int]) – The maximum number of results to return. If not provided, returns all the users who reacted to the message.
after (Optional[abc.Snowflake]) – For pagination, reactions are sorted by member.

Raises

HTTPException – Getting the users for the reaction failed.

Yields

Union[User, Member] – The member (if retrievable) or the user that has reacted to this message. The case where it can be a Member is in a guild message context. Sometimes it can be a User if the member has left the guild.

Interaction¶

Attributes

channel
guild
id
message
modal
name
nonce
successful
type
user

class discord.Interaction¶

Represents an interaction.

New in version 2.0.

x == y: Checks if two interactions are equal.

x != y: Checks if two interactions are not equal.

hash(x): Return the interaction’s hash.

str(x): Returns a string representation of the interaction, if any.

id¶

The interaction ID.

Type: int

type¶

The type of interaction.

Type: InteractionType

nonce¶

The interaction’s nonce. Not always present.

Type: Optional[Union[int, str]]

channel¶

The channel this interaction originated from.

Type: Union[TextChannel, VoiceChannel, Thread, DMChannel]

user¶

The Member who initiated the interaction. If channel is a private channel or the user has the left the guild, then it is a User instead.

Type: Union[Member, abc.User]

name¶

The name of the application command, if applicable.

Type: Optional[str]

successful¶

Whether the interaction succeeded. If this is your interaction, this is not immediately available. It is filled when Discord notifies us about the outcome of the interaction.

Type: bool

modal¶

The modal that is in response to this interaction. This is not immediately available and is filled when the modal is dispatched.

Type: Optional[Modal]

message¶

Returns the message that is the response to this interaction. May not exist or be cached.

Type: Optional[Message]

property guild¶

Returns the guild the interaction originated from.

Type: Optional[Guild]

Component¶

Attributes

type

class discord.Component¶

Represents a Discord Bot UI Kit Component.

Currently, the only components supported by Discord are:

ActionRow
Button
SelectMenu
TextInput

New in version 2.0.

property type¶

The type of component.

Type: ComponentType

Attributes

children
message
type

class discord.ActionRow¶

Represents a Discord Bot UI Kit Action Row.

This is a component that holds up to 5 children components in a row.

This inherits from Component.

New in version 2.0.

children¶

The children components that this holds, if any.

Type: List[Union[Button, SelectMenu, TextInput]]

message¶

The originating message.

Type: Message

property type¶

The type of component.

Type: ComponentType

Attributes

custom_id
disabled
emoji
label
message
style
type
url

Methods

asyncclick

class discord.Button¶

Represents a button from the Discord Bot UI Kit.

This inherits from Component.

New in version 2.0.

style¶

The style of the button.

Type: ButtonStyle

custom_id¶

The ID of the button that gets received during an interaction. If this button is for a URL, it does not have a custom ID.

Type: Optional[str]

url¶

The URL this button sends you to.

Type: Optional[str]

disabled¶

Whether the button is disabled or not.

Type: bool

label¶

The label of the button, if any.

Type: Optional[str]

emoji¶

The emoji of the button, if available.

Type: Optional[PartialEmoji]

message¶

The originating message.

Type: Message

property type¶

The type of component.

Type: ComponentType

await click()¶

This function is a coroutine.

Clicks the button.

Raises

InvalidData – Didn’t receive a response from Discord (doesn’t mean the interaction failed).
NotFound – The originating message was not found.
HTTPException – Clicking the button failed.

Returns

The button’s URL or the interaction that was created.

Return type

Union[str, Interaction]

Attributes

custom_id
disabled
max_values
message
min_values
options
placeholder
type

Methods

asyncchoose

class discord.SelectMenu¶

Represents a select menu from the Discord Bot UI Kit.

A select menu is functionally the same as a dropdown, however on mobile it renders a bit differently.

New in version 2.0.

custom_id¶

The ID of the select menu that gets received during an interaction.

Type: Optional[str]

placeholder¶

The placeholder text that is shown if nothing is selected, if any.

Type: Optional[str]

min_values¶

The minimum number of items that must be chosen for this select menu.

Type: int

max_values¶

The maximum number of items that must be chosen for this select menu.

Type: int

options¶

A list of options that can be selected in this menu.

Type: List[SelectOption]

disabled¶

Whether the select is disabled or not.

Type: bool

message¶

The originating message, if any.

Type: Message

property type¶

The type of component.

Type: ComponentType

await choose(*options)¶

This function is a coroutine.

Chooses the given options from the select menu.

Raises

InvalidData – Didn’t receive a response from Discord (doesn’t mean the interaction failed).
NotFound – The originating message was not found.
HTTPException – Choosing the options failed.

Returns

The interaction that was created.

Return type

Attributes

default
description
emoji
label
value

class discord.SelectOption¶

Represents a select menu’s option.

New in version 2.0.

label¶

The label of the option. This is displayed to users. Can only be up to 100 characters.

Type: str

value¶

The value of the option. This is not displayed to users. If not provided when constructed then it defaults to the label. Can only be up to 100 characters.

Type: str

description¶

An additional description of the option, if any. Can only be up to 100 characters.

Type: Optional[str]

emoji¶

The emoji of the option, if available.

Type: Optional[PartialEmoji]

default¶

Whether this option is selected by default.

Type: bool

Attributes

custom_id
default
label
max_length
min_length
placeholder
required
style
type
value

Methods

defanswer

class discord.TextInput¶

Represents a text input from the Discord Bot UI Kit.

New in version 2.0.

custom_id¶

The ID of the text input that gets received during an interaction.

Type: Optional[str]

label¶

The label to display above the text input.

Type: str

style¶

The style of the text input.

Type: TextStyle

placeholder¶

The placeholder text to display when the text input is empty.

Type: Optional[str]

required¶

Whether the text input is required.

Type: bool

min_length¶

The minimum length of the text input.

Type: Optional[int]

max_length¶

The maximum length of the text input.

Type: Optional[int]

property type¶

The type of component.

Type: ComponentType

property value¶

The current value of the text input. Defaults to default.

This can be set to change the answer to the text input.

Type: Optional[str]

property default¶

The default value of the text input.

Type: Optional[str]

answer(value, /)¶

A shorthand method to answer the text input.

Parameters: value (Optional[str]) – The value to set the answer to.
Raises: ValueError – The answer is shorter than min_length or longer than max_length.

ApplicationCommand¶

Attributes

application
application_id
default_member_permissions
description
dm_permission
guild
guild_id
id
mention
name
nsfw
target_channel
target_user
type
version

Methods

async__call__
defis_group

class discord.UserCommand¶

Represents a user command.

x == y: Checks if two commands are equal.

x != y: Checks if two commands are not equal.

hash(x): Return the command’s hash.

str(x): Returns the command’s name.

New in version 2.0.

Changed in version 2.1: Removed default_permission attribute.

id¶

The command’s ID.

Type: int

version¶

The command’s version.

Type: int

name¶

The command’s name.

Type: str

description¶

The command’s description, if any.

Type: str

dm_permission¶

Whether the command is enabled in DMs.

Type: bool

nsfw¶

Whether the command is marked NSFW and only available in NSFW channels.

Type: bool

application¶

The application this command belongs to. Only available if requested.

Type: Optional[IntegrationApplication]

application_id¶

The ID of the application this command belongs to.

Type: int

guild_id¶

The ID of the guild this command is registered in. A value of None denotes that it is a global command.

Type: Optional[int]

await __call__(user=None, *, channel=None)¶

This function is a coroutine.

Use the user command.

Parameters

user (Optional[User]) – The user to use the command on. Overrides target_user. Required if target_user is not set.
channel (Optional[abc.Messageable]) – The channel to use the command on. Overrides target_channel. Required if target_channel is not set.

Returns

The interaction that was created.

Return type

property type¶

The type of application command. This is always ApplicationCommandType.user.

Type: ApplicationCommandType

property target_user¶

The user this application command will be used on.

You can set this in order to use this command on a different user without re-fetching it.

Type: Optional[Snowflake]

property default_member_permissions¶

The default permissions required to use this command.

Note

This may be overrided on a guild-by-guild basis.

Type: Optional[Permissions]

property guild¶

Returns the guild this command is registered to if it exists.

Type: Optional[Guild]

is_group()¶: bool: Whether this command is a group.

property mention¶

Returns a string that allows you to mention the command.

Type: str

property target_channel¶

The channel this application command will be used on.

You can set this in order to use this command in a different channel without re-fetching it.

Type: Optional[abc.Messageable]

Attributes

application
application_id
default_member_permissions
description
dm_permission
guild
guild_id
id
mention
name
nsfw
target_channel
target_message
type
version

Methods

async__call__
defis_group

class discord.MessageCommand¶

Represents a message command.

x == y: Checks if two commands are equal.

x != y: Checks if two commands are not equal.

hash(x): Return the command’s hash.

str(x): Returns the command’s name.

New in version 2.0.

Changed in version 2.1: Removed default_permission attribute.

id¶

The command’s ID.

Type: int

version¶

The command’s version.

Type: int

name¶

The command’s name.

Type: str

description¶

The command’s description, if any.

Type: str

dm_permission¶

Whether the command is enabled in DMs.

Type: bool

nsfw¶

Whether the command is marked NSFW and only available in NSFW channels.

Type: bool

application¶

The application this command belongs to. Only available if requested.

Type: Optional[IntegrationApplication]

application_id¶

The ID of the application this command belongs to.

Type: int

guild_id¶

The ID of the guild this command is registered in. A value of None denotes that it is a global command.

Type: Optional[int]

await __call__(message=None, *, channel=None)¶

This function is a coroutine.

Use the message command.

Parameters

message (Optional[Message]) – The message to use the command on. Overrides target_message. Required if target_message is not set.
channel (Optional[abc.Messageable]) – The channel to use the command on. Overrides target_channel. Required if target_channel is not set.

Returns

The interaction that was created.

Return type

property type¶

The type of application command. This is always ApplicationCommandType.message.

Type: ApplicationCommandType

property target_message¶

The message this application command will be used on.

You can set this in order to use this command on a different message without re-fetching it.

Type: Optional[Message]

property default_member_permissions¶

The default permissions required to use this command.

Note

This may be overrided on a guild-by-guild basis.

Type: Optional[Permissions]

property guild¶

Returns the guild this command is registered to if it exists.

Type: Optional[Guild]

is_group()¶: bool: Whether this command is a group.

property mention¶

Returns a string that allows you to mention the command.

Type: str

property target_channel¶

The channel this application command will be used on.

You can set this in order to use this command in a different channel without re-fetching it.

Type: Optional[abc.Messageable]

Attributes

application
application_id
children
default_member_permissions
description
dm_permission
guild
guild_id
id
mention
name
nsfw
options
target_channel
type
version

Methods

async__call__
defis_group

class discord.SlashCommand¶

Represents a slash command.

x == y: Checks if two commands are equal.

x != y: Checks if two commands are not equal.

hash(x): Return the command’s hash.

str(x): Returns the command’s name.

New in version 2.0.

Changed in version 2.1: Removed default_permission attribute.

id¶

The command’s ID.

Type: int

version¶

The command’s version.

Type: int

name¶

The command’s name.

Type: str

description¶

The command’s description, if any.

Type: str

dm_permission¶

Whether the command is enabled in DMs.

Type: bool

nsfw¶

Whether the command is marked NSFW and only available in NSFW channels.

Type: bool

application¶

The application this command belongs to. Only available if requested.

Type: Optional[IntegrationApplication]

application_id¶

The ID of the application this command belongs to.

Type: int

guild_id¶

The ID of the guild this command is registered in. A value of None denotes that it is a global command.

Type: Optional[int]

options¶

The command’s options.

Type: List[Option]

children¶

The command’s subcommands. If a command has subcommands, it is a group and cannot be used.

Type: List[SubCommand]

await __call__(channel=None, /, **kwargs)¶

This function is a coroutine.

Use the slash command.

Parameters

channel (Optional[abc.Messageable]) – The channel to use the command on. Overrides target_channel. Required if target_channel is not set.
**kwargs (Any) – The options to use. These will be casted to the correct type. If an option has choices, they are automatically converted from name to value for you.

Raises

TypeError – Attempted to use a group.

Returns

The interaction that was created.

Return type

property type¶

The type of application command. This is always ApplicationCommandType.chat_input.

Type: ApplicationCommandType

is_group()¶

Query whether this command is a group.

Returns: Whether this command is a group.
Return type: bool

property default_member_permissions¶

The default permissions required to use this command.

Note

This may be overrided on a guild-by-guild basis.

Type: Optional[Permissions]

property guild¶

Returns the guild this command is registered to if it exists.

Type: Optional[Guild]

property mention¶

Returns a string that allows you to mention the command.

Type: str

property target_channel¶

The channel this application command will be used on.

You can set this in order to use this command in a different channel without re-fetching it.

Type: Optional[abc.Messageable]

Attributes

application
application_id
children
default_member_permissions
description
dm_permission
guild
guild_id
mention
name
nsfw
options
parent
qualified_name
target_channel
type
version

Methods

async__call__
defis_group

class discord.SubCommand¶

Represents a slash command child.

This could be a subcommand, or a subgroup.

str(x): Returns the command’s name.

New in version 2.0.

Changed in version 2.1: Removed default_permission property.

name¶

The subcommand’s name.

Type: str

description¶

The subcommand’s description, if any.

Type: str

parent¶

The parent command.

Type: Union[SlashCommand, SubCommand]

options¶

The subcommand’s options.

Type: List[Option]

children¶

The subcommand’s subcommands. If a subcommand has subcommands, it is a group and cannot be used.

Type: List[SubCommand]

await __call__(channel=None, /, **kwargs)¶

This function is a coroutine.

Use the sub command.

Parameters

channel (Optional[abc.Messageable]) – The channel to use the command on. Overrides target_channel. Required if target_channel is not set.
**kwargs (Any) – The options to use. These will be casted to the correct type. If an option has choices, they are automatically converted from name to value for you.

Raises

TypeError – Attempted to use a group.

Returns

The interaction that was created.

Return type

property type¶

The type of application command. Always ApplicationCommandType.chat_input.

Type: ApplicationCommandType

property qualified_name¶

Returns the fully qualified command name. The qualified name includes the parent name as well. For example, in a command like /foo bar the qualified name is foo bar.

Type: str

property mention¶

Returns a string that allows you to mention the subcommand.

Type: str

property application_id¶

The ID of the application this command belongs to.

Type: int

property version¶

The version of the command.

Type: int

property dm_permission¶

Whether the command is enabled in DMs.

Type: bool

property nsfw¶

Whether the command is marked NSFW and only available in NSFW channels.

Type: bool

property guild_id¶

The ID of the guild this command is registered in. A value of None denotes that it is a global command.

Type: Optional[int]

property guild¶

Returns the guild this command is registered to if it exists.

Type: Optional[Guild]

is_group()¶: bool: Whether this command is a group.

property application¶

The application this command belongs to. Only available if requested.

Type: Optional[IntegrationApplication]

property target_channel¶

The channel this command will be used on.

You can set this in order to use this command on a different channel without re-fetching it.

Type: Optional[abc.Messageable]

property default_member_permissions¶

The default permissions required to use this command.

Note

This may be overrided on a guild-by-guild basis.

Type: Optional[Permissions]

Attributes

autocomplete
channel_types
choices
description
max_value
min_value
name
required
type

class discord.Option¶

Represents a command option.

str(x): Returns the option’s name.

New in version 2.0.

name¶

The option’s name.

Type: str

description¶

The option’s description, if any.

Type: str

type¶

The type of option.

Type: ApplicationCommandOptionType

required¶

Whether the option is required.

Type: bool

min_value¶

Minimum value of the option. Only applicable to ApplicationCommandOptionType.integer and ApplicationCommandOptionType.number.

Type: Optional[Union[int, float]]

max_value¶

Maximum value of the option. Only applicable to ApplicationCommandOptionType.integer and ApplicationCommandOptionType.number.

Type: Optional[Union[int, float]]

choices¶

A list of possible choices to choose from. If these are present, you must choose one from them.

Only applicable to ApplicationCommandOptionType.string, ApplicationCommandOptionType.integer, and ApplicationCommandOptionType.number.

Type: List[OptionChoice]

channel_types¶

A list of channel types that you can choose from. If these are present, you must choose a channel that is one of these types.

Only applicable to ApplicationCommandOptionType.channel.

Type: List[ChannelType]

autocomplete¶

Whether the option autocompletes.

Only applicable to ApplicationCommandOptionType.string, ApplicationCommandOptionType.integer, and ApplicationCommandOptionType.number. Always False if choices are present.

Type: bool

Attributes

name
value

class discord.OptionChoice¶

Represents a choice for an option.

New in version 2.0.

str(x): Returns the choice’s name.

name¶

The choice’s displayed name.

Type: str

value¶

The choice’s value. The type of this depends on the option’s type.

Type: Union[str, int, float]

Invite¶

class discord.Invite¶

Represents a Discord Guild or abc.GuildChannel invite.

Depending on the way this object was created, some of the attributes can have a value of None.

x == y: Checks if two invites are equal.

x != y: Checks if two invites are not equal.

hash(x): Returns the invite hash.

str(x): Returns the invite URL.

The following table illustrates what methods will obtain the attributes:

Attribute	Method
`max_age`	`abc.GuildChannel.invites()`, `Guild.invites()`
`max_uses`	`abc.GuildChannel.invites()`, `Guild.invites()`
`created_at`	`abc.GuildChannel.invites()`, `Guild.invites()`
`temporary`	`abc.GuildChannel.invites()`, `Guild.invites()`
`uses`	`abc.GuildChannel.invites()`, `Guild.invites()`
`approximate_member_count`	`Client.fetch_invite()` with `with_counts` enabled
`approximate_presence_count`	`Client.fetch_invite()` with `with_counts` enabled

If it’s not in the table above then it is available by all methods.

Changed in version 2.1.

The revoked attribute has been removed.

max_age¶

How long before the invite expires in seconds. A value of 0 indicates that it doesn’t expire.

Type: Optional[int]

code¶

The URL fragment used for the invite.

Type: str

type¶

The type of invite.

New in version 2.0.

Type: InviteType

guild¶

The guild the invite is for. Can be None if not a guild invite.

Type: Optional[Union[Guild, Object, PartialInviteGuild]]

created_at¶

An aware UTC datetime object denoting the time the invite was created.

Type: Optional[datetime.datetime]

temporary¶

Indicates that the invite grants temporary membership. If True, members who joined via this invite will be kicked upon disconnect.

Type: Optional[bool]

uses¶

How many times the invite has been used.

Type: Optional[int]

max_uses¶

How many times the invite can be used. A value of 0 indicates that it has unlimited uses.

Type: Optional[int]

inviter¶

The user who created the invite.

Type: Optional[User]

approximate_member_count¶

The approximate number of members in the guild.

Type: Optional[int]

approximate_presence_count¶

The approximate number of members currently active in the guild. This includes idle, dnd, online, and invisible members. Offline members are excluded.

Type: Optional[int]

expires_at¶

The expiration date of the invite. If the value is None (unless received through Client.fetch_invite() with with_expiration disabled), the invite will never expire.

New in version 2.0.

Type: Optional[datetime.datetime]

channel¶

The channel the invite is for. Can be None if not a guild invite.

Type: Optional[Union[abc.GuildChannel, GroupChannel, Object, PartialInviteChannel]]

target_type¶

The type of target for the voice channel invite.

New in version 2.0.

Type: InviteTarget

target_user¶

The user whose stream to display for this invite, if any.

New in version 2.0.

Type: Optional[User]

target_application¶

The embedded application the invite targets, if any.

New in version 2.0.

Type: Optional[PartialApplication]

scheduled_event¶

The scheduled event associated with this invite, if any.

New in version 2.0.

Type: Optional[ScheduledEvent]

scheduled_event_id¶

The ID of the scheduled event associated with this invite, if any.

New in version 2.0.

Type: Optional[int]

welcome_screen¶

The guild’s welcome screen, if available.

New in version 2.0.

Type: Optional[WelcomeScreen]

new_member¶

Whether the user was not previously a member of the guild.

New in version 2.0.

Note

This is only possibly True in accepted invite objects (i.e. the objects received from accept() and use()).

Type: bool

show_verification_form¶

Whether the user should be shown the guild’s membership screening form.

New in version 2.0.

Note

This is only possibly True in accepted invite objects (i.e. the objects received from accept() and use()).

Type: bool

property id¶

Returns the proper code portion of the invite.

Type: str

property url¶

A property that retrieves the invite URL.

Type: str

property flags¶

Returns the invite’s flags.

New in version 2.1.

Type: InviteFlags

set_scheduled_event(scheduled_event, /)¶

Sets the scheduled event for this invite.

New in version 2.0.

Parameters: scheduled_event (Snowflake) – The ID of the scheduled event.
Returns: The invite with the new scheduled event.
Return type: Invite

await use()¶

This function is a coroutine.

Uses the invite. Either joins a guild, joins a group DM, or adds a friend.

There is an alias for this called accept().

New in version 1.9.

Raises: HTTPException – Using the invite failed.
Returns: The accepted invite.
Return type: Invite

await accept()¶

This function is a coroutine.

Uses the invite. Either joins a guild, joins a group DM, or adds a friend.

This is an alias of use().

New in version 1.9.

Raises: HTTPException – Using the invite failed.
Returns: The accepted invite.
Return type: Invite

await delete(*, reason=None)¶

This function is a coroutine.

Revokes the instant invite.

In a guild context, you must have manage_channels to do this.

Changed in version 2.0: The function now returns the deleted invite.

Parameters

reason (Optional[str]) –

The reason for deleting this invite. Shows up on the audit log.

Only applicable to guild invites.

Raises

Forbidden – You do not have permissions to revoke invites.
NotFound – The invite is invalid or expired.
HTTPException – Revoking the invite failed.

Returns

The deleted invite.

Return type

Attributes

banner
created_at
description
features
icon
id
name
nsfw_level
premium_subscription_count
splash
vanity_url
vanity_url_code
verification_level

class discord.PartialInviteGuild¶

Represents a “partial” invite guild.

This model will be given when the user is not part of the guild the Invite resolves to.

x == y: Checks if two partial guilds are the same.

x != y: Checks if two partial guilds are not the same.

hash(x): Return the partial guild’s hash.

str(x): Returns the partial guild’s name.

name¶

The partial guild’s name.

Type: str

id¶

The partial guild’s ID.

Type: int

verification_level¶

The partial guild’s verification level.

Type: VerificationLevel

features¶

A list of features the guild has. See Guild.features for more information.

Type: List[str]

description¶

The partial guild’s description.

Type: Optional[str]

nsfw_level¶

The partial guild’s NSFW level.

New in version 2.0.

Type: NSFWLevel

vanity_url_code¶

The partial guild’s vanity URL code, if available.

New in version 2.0.

Type: Optional[str]

premium_subscription_count¶

The number of “boosts” the partial guild currently has.

New in version 2.0.

Type: int

property created_at¶

Returns the guild’s creation time in UTC.

Type: datetime.datetime

property vanity_url¶

The Discord vanity invite URL for this partial guild, if available.

New in version 2.0.

Type: Optional[str]

property icon¶

Returns the guild’s icon asset, if available.

Type: Optional[Asset]

property banner¶

Returns the guild’s banner asset, if available.

Type: Optional[Asset]

property splash¶

Returns the guild’s invite splash asset, if available.

Type: Optional[Asset]

Attributes

created_at
icon
id
mention
name
recipients
type

class discord.PartialInviteChannel¶

Represents a “partial” invite channel.

This model will be given when the user is not part of the guild or group channel the Invite resolves to.

x == y: Checks if two partial channels are the same.

x != y: Checks if two partial channels are not the same.

hash(x): Return the partial channel’s hash.

str(x): Returns the partial channel’s name.

name¶

The partial channel’s name.

Type: Optional[str]

id¶

The partial channel’s ID.

Type: int

type¶

The partial channel’s type.

Type: ChannelType

recipients¶

The partial channel’s recipient names. This is applicable to channels of type ChannelType.group.

New in version 2.0.

Type: Optional[List[str]]

property mention¶

The string that allows you to mention the channel.

Type: str

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

property icon¶

Returns the channel’s icon asset if available.

Only applicable to channels of type ChannelType.group.

New in version 2.0.

Type: Optional[Asset]

Template¶

Attributes

code
created_at
creator
description
is_dirty
name
source_guild
updated_at
url
uses

Methods

asynccreate_guild
asyncdelete
asyncedit
asyncsync

class discord.Template¶

Represents a Discord template.

New in version 1.4.

code¶

The template code.

Type: str

uses¶

How many times the template has been used.

Type: int

name¶

The name of the template.

Type: str

description¶

The description of the template.

Type: str

creator¶

The creator of the template.

Type: User

created_at¶

An aware datetime in UTC representing when the template was created.

Type: datetime.datetime

updated_at¶

An aware datetime in UTC representing when the template was last updated. This is referred to as “last synced” in the official Discord client.

Type: datetime.datetime

source_guild¶

The guild snapshot that represents the data that this template currently holds.

Type: Guild

is_dirty¶

Whether the template has unsynced changes.

New in version 2.0.

Type: Optional[bool]

await create_guild(name, icon=...)¶

This function is a coroutine.

Creates a Guild using the template.

Changed in version 2.0: The region parameter has been removed.

Changed in version 2.0: This function will now raise ValueError instead of InvalidArgument.

Parameters

name (str) – The name of the guild.
icon (bytes) – The bytes-like object representing the icon. See ClientUser.edit() for more details on what is expected.

Raises

HTTPException – Guild creation failed.
ValueError – Invalid icon image format given. Must be PNG or JPG.

Returns

The guild created. This is not the same guild that is added to cache.

Return type

await sync()¶

This function is a coroutine.

Sync the template to the guild’s current state.

You must have manage_guild in the source guild to do this.

New in version 1.7.

Changed in version 2.0: The template is no longer edited in-place, instead it is returned.

Raises

HTTPException – Editing the template failed.
Forbidden – You don’t have permissions to edit the template.
NotFound – This template does not exist.

Returns

The newly edited template.

Return type

Template

await edit(*, name=..., description=...)¶

This function is a coroutine.

Edit the template metadata.

You must have manage_guild in the source guild to do this.

New in version 1.7.

Changed in version 2.0: The template is no longer edited in-place, instead it is returned.

Parameters

name (str) – The template’s new name.
description (Optional[str]) – The template’s new description.

Raises

HTTPException – Editing the template failed.
Forbidden – You don’t have permissions to edit the template.
NotFound – This template does not exist.

Returns

The newly edited template.

Return type

Template

await delete()¶

This function is a coroutine.

Delete the template.

You must have manage_guild in the source guild to do this.

New in version 1.7.

Raises

HTTPException – Editing the template failed.
Forbidden – You don’t have permissions to edit the template.
NotFound – This template does not exist.

property url¶

The template url.

New in version 2.0.

Type: str

Widget¶

Attributes

channels
created_at
id
invite_url
json_url
members
name
presence_count

Methods

asyncfetch_invite

class discord.Widget¶

Represents a Guild widget.

x == y: Checks if two widgets are the same.

x != y: Checks if two widgets are not the same.

str(x): Returns the widget’s JSON URL.

id¶

The guild’s ID.

Type: int

name¶

The guild’s name.

Type: str

channels¶

The accessible voice channels in the guild.

Type: List[WidgetChannel]

members¶

The online members in the guild. Offline members do not appear in the widget.

Note

Due to a Discord limitation, if this data is available the users will be “anonymized” with linear IDs and discriminator information being incorrect. Likewise, the number of members retrieved is capped.

Type: List[WidgetMember]

presence_count¶

The approximate number of online members in the guild. Offline members are not included in this count.

New in version 2.0.

Type: int

property created_at¶

Returns the member’s creation time in UTC.

Type: datetime.datetime

property json_url¶

The JSON URL of the widget.

Type: str

property invite_url¶

The invite URL for the guild, if available.

Type: Optional[str]

await fetch_invite(*, with_counts=True)¶

This function is a coroutine.

Retrieves an Invite from the widget’s invite URL. This is the same as Client.fetch_invite(); the invite code is abstracted away.

Parameters: with_counts (bool) – Whether to include count information in the invite. This fills the Invite.approximate_member_count and Invite.approximate_presence_count fields.
Returns: The invite from the widget’s invite URL, if available.
Return type: Optional[Invite]

Attributes

created_at
id
mention
name
position

class discord.WidgetChannel¶

Represents a “partial” widget channel.

x == y: Checks if two partial channels are the same.

x != y: Checks if two partial channels are not the same.

hash(x): Return the partial channel’s hash.

str(x): Returns the partial channel’s name.

id¶

The channel’s ID.

Type: int

name¶

The channel’s name.

Type: str

position¶

The channel’s position

Type: int

property mention¶

The string that allows you to mention the channel.

Type: str

property created_at¶

Returns the channel’s creation time in UTC.

Type: datetime.datetime

class discord.WidgetMember¶

Represents a “partial” member of the widget’s guild.

x == y: Checks if two widget members are the same.

x != y: Checks if two widget members are not the same.

hash(x): Return the widget member’s hash.

str(x): Returns the widget member’s handle (e.g. name or name#discriminator).

id¶

The member’s ID.

Type: int

name¶

The member’s username.

Type: str

discriminator¶

The member’s discriminator. This is a legacy concept that is no longer used.

Type: str

global_name¶

The member’s global nickname, taking precedence over the username in display.

New in version 2.1.

Type: Optional[str]

bot¶

Whether the member is a bot.

Type: bool

status¶

The member’s status.

Type: Status

nick¶

The member’s guild-specific nickname. Takes precedence over the global name.

Type: Optional[str]

avatar¶

The member’s avatar hash.

Type: Optional[str]

activity¶

The member’s activity.

Type: Optional[Union[BaseActivity, Spotify]]

deafened¶

Whether the member is currently deafened.

Type: Optional[bool]

muted¶

Whether the member is currently muted.

Type: Optional[bool]

suppress¶

Whether the member is currently being suppressed.

Type: Optional[bool]

connected_channel¶

Which channel the member is connected to.

Type: Optional[WidgetChannel]

property display_name¶

Returns the member’s display name.

Type: str

property accent_color¶

Returns the user’s accent color, if applicable.

A user’s accent color is only shown if they do not have a banner. This will only be available if the user explicitly sets a color.

There is an alias for this named accent_colour.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

property accent_colour¶

Returns the user’s accent colour, if applicable.

A user’s accent colour is only shown if they do not have a banner. This will only be available if the user explicitly sets a colour.

There is an alias for this named accent_color.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Colour]

property avatar_decoration¶

Returns an Asset for the avatar decoration the user has.

If the user does not have a avatar decoration, None is returned.

New in version 2.0.

Type: Optional[Asset]

property avatar_decoration_sku_id¶

Returns the avatar decoration’s SKU ID.

If the user does not have a preset avatar decoration, None is returned.

New in version 2.1.

Type: Optional[int]

property banner¶

Returns the user’s banner asset, if available.

New in version 2.0.

Note

This information is only available via Client.fetch_user().

Type: Optional[Asset]

property color¶

A property that returns a color denoting the rendered color for the user. This always returns Colour.default().

There is an alias for this named colour.

Type: Colour

property colour¶

A property that returns a colour denoting the rendered colour for the user. This always returns Colour.default().

There is an alias for this named color.

Type: Colour

property created_at¶

Returns the user’s creation time in UTC.

This is when the user’s Discord account was created.

Type: datetime.datetime

property default_avatar¶

Returns the default avatar for a given user.

Type: Asset

property display_avatar¶

Returns the user’s display avatar.

For regular users this is just their default avatar or uploaded avatar.

New in version 2.0.

Type: Asset

property display_banner¶

Returns the user’s banner asset, if available.

This is the same as banner and is here for compatibility.

New in version 2.0.

Type: Optional[Asset]

await fetch_mutual_friends()¶

This function is a coroutine.

Fetches mutual friends with the user.

New in version 2.1.

Raises: HTTPException – Fetching the mutual friends failed.
Returns: The mutual friends with the user.
Return type: List[User]

is_blocked()¶: bool: Checks if the user is blocked.

is_friend()¶: bool: Checks if the user is your friend.

is_pomelo()¶: bool: Checks if the user has migrated to Discord’s new unique username system

New in version 2.1.

property mention¶

Returns a string that allows you to mention the given user.

Type: str

mentioned_in(message)¶

Checks if the user is mentioned in the specified message.

Parameters: message (Message) – The message to check if you’re mentioned in.
Returns: Indicates if the user is mentioned in the message.
Return type: bool

note¶

Returns an object representing the user’s note.

New in version 2.0.

Note

The underlying note is cached and updated from gateway events.

Type: Note

property premium¶: Indicates if the user is a premium user (i.e. has Discord Nitro).

await profile(*, with_mutual_guilds=True, with_mutual_friends_count=False, with_mutual_friends=True)¶

This function is a coroutine.

A shorthand method to retrieve a UserProfile for the user.

Parameters

with_mutual_guilds (bool) –
Whether to fetch mutual guilds. This fills in UserProfile.mutual_guilds.

New in version 2.0.
with_mutual_friends_count (bool) –
Whether to fetch the number of mutual friends. This fills in UserProfile.mutual_friends_count.

New in version 2.0.
with_mutual_friends (bool) –
Whether to fetch mutual friends. This fills in UserProfile.mutual_friends and UserProfile.mutual_friends_count, but requires an extra API call.

New in version 2.0.

Raises

Forbidden – Not allowed to fetch this profile.
HTTPException – Fetching the profile failed.

Returns

The profile of the user.

Return type