Guilds

This section documents everything related to Guilds - main hubs for communication in Discord, referred to as Servers in the official UI.

Discord Models

Guild

Attributes
Methods
class disnake.Guild[source]

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’s 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

afk_channel

The channel that denotes the AFK channel. None if it doesn’t exist.

Type:

Optional[VoiceChannel]

id

The guild’s ID.

Type:

int

owner_id

The guild owner’s ID. Use Guild.owner if you need a Member object instead.

Type:

int

unavailable

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

Note

This attribute is only available via Client.fetch_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]

max_stage_video_channel_users

The maximum amount of users in a stage video channel.

Type:

Optional[int]

description

The guild’s description.

Type:

Optional[str]

mfa_level

Indicates the guild’s two-factor authentication level. If this value is 0 then the guild does not require 2FA for their administrative members to take moderation actions. If the value is 1, then 2FA is required.

Type:

int

verification_level

The guild’s verification level.

Type:

VerificationLevel

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.

A partial list of features is below:

  • ANIMATED_BANNER: Guild can upload an animated banner.

  • ANIMATED_ICON: Guild can upload an animated icon.

  • AUTO_MODERATION: Guild has set up auto moderation rules.

  • BANNER: Guild can upload and use a banner. (i.e. banner)

  • COMMUNITY: Guild is a community server.

  • CREATOR_MONETIZABLE_PROVISIONAL: Guild has enabled monetization.

  • CREATOR_STORE_PAGE: Guild has enabled the role subscription promo page.

  • DEVELOPER_SUPPORT_SERVER: Guild is set as a support server in the app directory.

  • DISCOVERABLE: Guild shows up in Server Discovery.

  • ENABLED_DISCOVERABLE_BEFORE: Guild had Server Discovery enabled at least once.

  • FEATURABLE: Guild is able to be featured in Server Discovery.

  • HAS_DIRECTORY_ENTRY: Guild is listed in a student hub.

  • HUB: Guild is a student hub.

  • INVITE_SPLASH: Guild’s invite page can have a special splash.

  • INVITES_DISABLED: Guild has paused invites, preventing new users from joining.

  • LINKED_TO_HUB: Guild is linked to a student hub.

  • MEMBER_VERIFICATION_GATE_ENABLED: Guild has Membership Screening enabled.

  • MORE_EMOJI: Guild has increased custom emoji slots.

  • MORE_STICKERS: Guild has increased custom sticker slots.

  • NEWS: Guild can create news channels.

  • NEW_THREAD_PERMISSIONS: Guild is using the new thread permission system.

  • PARTNERED: Guild is a partnered server.

  • PREVIEW_ENABLED: Guild can be viewed before being accepted via Membership Screening.

  • PRIVATE_THREADS: Guild has access to create private threads (no longer has any effect).

  • RAID_ALERTS_DISABLED: Guild has disabled alerts for join raids in the configured safety alerts channel.

  • ROLE_ICONS: Guild has access to role icons.

  • ROLE_SUBSCRIPTIONS_AVAILABLE_FOR_PURCHASE: Guild has role subscriptions that can be purchased.

  • ROLE_SUBSCRIPTIONS_ENABLED: Guild has enabled role subscriptions.

  • SEVEN_DAY_THREAD_ARCHIVE: Guild has access to the seven day archive time for threads (no longer has any effect).

  • TEXT_IN_VOICE_ENABLED: Guild has text in voice channels enabled (no longer has any effect).

  • THREE_DAY_THREAD_ARCHIVE: Guild has access to the three day archive time for threads (no longer has any effect).

  • THREADS_ENABLED: Guild has access to threads (no longer has any effect).

  • TICKETED_EVENTS_ENABLED: Guild has enabled ticketed events (no longer has any effect).

  • VANITY_URL: Guild can have a vanity invite URL (e.g. discord.gg/disnake).

  • VERIFIED: Guild is a verified server.

  • VIP_REGIONS: Guild has VIP voice regions.

  • WELCOME_SCREEN_ENABLED: Guild has enabled the welcome screen.

Type:

List[str]

premium_progress_bar_enabled

Whether the server boost progress bar is enabled.

Type:

bool

premium_tier

The premium tier for this guild. Corresponds to “Nitro Server” in the official UI. The number goes from 0 to 3 inclusive.

Type:

int

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.5: Changed to Locale instead of str.

Type:

Locale

nsfw_level

The guild’s NSFW level.

New in version 2.0.

Type:

NSFWLevel

approximate_member_count

The approximate number of members in the guild. Only available for manually fetched guilds.

New in version 2.3.

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. Only available for manually fetched guilds.

New in version 2.3.

Type:

Optional[int]

widget_enabled

Whether the widget is enabled.

New in version 2.5.

Note

This value is unreliable and will only be set after the guild was updated at least once. Avoid using this and use widget_settings() instead.

Type:

Optional[bool]

widget_channel_id

The widget channel ID, if set.

New in version 2.5.

Note

This value is unreliable and will only be set after the guild was updated at least once. Avoid using this and use widget_settings() instead.

Type:

Optional[int]

vanity_url_code

The vanity invite code for this guild, if set.

To get a full Invite object, see Guild.vanity_invite.

New in version 2.5.

Type:

Optional[str]

async for ... in fetch_members(*, limit=1000, after=None)[source]

Retrieves an AsyncIterator that enables receiving the guild’s members.

In order to use this, the members intent must be enabled in the developer portal.

Note

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

New in version 1.3.

Changed in version 2.9: No longer requires the intent to be enabled on the websocket connection.

All parameters are optional.

Parameters:

  • limit (Optional[int]) – The number of members to retrieve. Defaults to 1000. Pass None to fetch all members. Note that this is potentially slow.

  • after (Optional[Union[abc.Snowflake, datetime.datetime]]) – Retrieve members after this date or object. 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:
Yields:

Member – The member with the member data parsed.

Examples

Usage

async for member in guild.fetch_members(limit=150):
    print(member.name)

Flattening into a list

members = await guild.fetch_members(limit=150).flatten()
# members is now a list of Member...
async for ... in audit_logs(*, limit=100, before=None, after=None, user=None, action=None, oldest_first=False)[source]

Returns an AsyncIterator that enables receiving the guild’s audit logs.

You must have view_audit_log permission to use this.

Entries are returned in order from newest to oldest by default; pass oldest_first=True to reverse the iteration order.

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=disnake.AuditLogAction.ban):
    print(f'{entry.user} banned {entry.target}')

Getting entries made by a specific user:

entries = await guild.audit_logs(limit=None, user=guild.me).flatten()
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 (Optional[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 (Optional[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.

  • user (Optional[abc.Snowflake]) – The moderator to filter entries from.

  • action (Optional[AuditLogAction]) – The action to filter with.

  • oldest_first (bool) –

    If set to True, return entries in oldest->newest order. Defaults to False.

    New in version 2.9.

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.

get_command(application_command_id, /)[source]

Gets a cached application command matching the specified ID.

Parameters:

application_command_id (int) – The application command ID to search for.

Returns:

The application command if found, or None otherwise.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

get_command_named(name, /)[source]

Gets a cached application command matching the specified name.

Parameters:

name (str) – The application command name to search for.

Returns:

The application command if found, or None otherwise.

Return type:

Optional[Union[APIUserCommand, APIMessageCommand, APISlashCommand]]

property channels[source]

A list of channels that belong to this guild.

Type:

List[abc.GuildChannel]

property threads[source]

A list of threads that you have permission to view.

New in version 2.0.

Type:

List[Thread]

property large[source]

Whether 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

property voice_channels[source]

A list of voice channels that belong to this guild.

This is sorted by the position and are in UI order from top to bottom.

Type:

List[VoiceChannel]

property stage_channels[source]

A list of stage channels that belong 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 forum_channels[source]

A list of forum channels that belong to this guild.

This is sorted by the position and are in UI order from top to bottom.

New in version 2.5.

Type:

List[ForumChannel]

property media_channels[source]

A list of media channels that belong to this guild.

This is sorted by the position and are in UI order from top to bottom.

New in version 2.10.

Type:

List[MediaChannel]

property me[source]

Similar to Client.user except an instance of Member. This is essentially used to get the member version of yourself.

Type:

Member

property voice_client[source]

Returns the VoiceProtocol associated with this guild, if any.

Type:

Optional[VoiceProtocol]

property text_channels[source]

A list of text channels that belong to this guild.

This is sorted by the position and are in UI order from top to bottom.

Type:

List[TextChannel]

property categories[source]

A list of categories that belong to this guild.

This is sorted by the position and are in UI order from top to bottom.

Type:

List[CategoryChannel]

by_category()[source]

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, /)[source]

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 or thread or None if not found.

Return type:

Optional[Union[Thread, abc.GuildChannel]]

get_channel(channel_id, /)[source]

Returns a channel with the given ID.

Note

This does not search for threads.

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, /)[source]

Returns a thread with the given ID.

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]

property system_channel[source]

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

Returns the guild’s system channel settings.

Type:

SystemChannelFlags

property rules_channel[source]

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

Returns the guild’s channel where admins and moderators of the guild 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 safety_alerts_channel[source]

Returns the guild’s channel where admins and moderators of the guild receive safety alerts from Discord. The guild must be a Community guild.

If no channel is set, then this returns None.

New in version 2.9.

Type:

Optional[TextChannel]

property emoji_limit[source]

The maximum number of emoji slots this guild has.

Premium emojis (i.e. those associated with subscription roles) count towards a separate limit of 25.

Type:

int

property sticker_limit[source]

The maximum number of sticker slots this guild has.

New in version 2.0.

Type:

int

property bitrate_limit[source]

The maximum bitrate for voice channels this guild can have. For stage channels, the maximum bitrate is 64000.

Type:

float

property filesize_limit[source]

The maximum number of bytes files can have when uploaded to this guild.

Type:

int

property members[source]

A list of members that belong to this guild.

Type:

List[Member]

get_member(user_id, /)[source]

Returns a member with the given ID.

Parameters:

user_id (int) – The ID to search for.

Returns:

The member or None if not found.

Return type:

Optional[Member]

property premium_subscribers[source]

A list of members who have “boosted” this guild.

Type:

List[Member]

property roles[source]

Returns a list of the guild’s roles in hierarchy order.

The first element of this list will be the lowest role in the hierarchy.

Type:

List[Role]

get_role(role_id, /)[source]

Returns a role with the given ID.

Parameters:

role_id (int) – The ID to search for.

Returns:

The role or None if not found.

Return type:

Optional[Role]

property default_role[source]

Gets the @everyone role that all members have by default.

Type:

Role

property premium_subscriber_role[source]

Gets the premium subscriber role, AKA “boost” role, in this guild, if any.

New in version 1.6.

Type:

Optional[Role]

property self_role[source]

Gets the role associated with this client’s user, if any.

New in version 1.6.

Type:

Optional[Role]

property stage_instances[source]

Returns a list of the guild’s stage instances that are currently running.

New in version 2.0.

Type:

List[StageInstance]

get_stage_instance(stage_instance_id, /)[source]

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

Returns a list of existing guild scheduled events.

New in version 2.3.

Type:

List[GuildScheduledEvent]

get_scheduled_event(event_id, /)[source]

Returns a guild scheduled event with the given ID.

New in version 2.3.

Parameters:

event_id (int) – The ID to search for.

Returns:

The guild scheduled event or None if not found.

Return type:

Optional[GuildScheduledEvent]

property owner[source]

Returns the member that owns the guild.

Type:

Optional[Member]

property icon[source]

Returns the guild’s icon asset, if available.

Type:

Optional[Asset]

property banner[source]

Returns the guild’s banner asset, if available.

Type:

Optional[Asset]

property splash[source]

Returns the guild’s invite splash asset, if available.

Type:

Optional[Asset]

property discovery_splash[source]

Returns the guild’s discovery splash asset, if available.

Type:

Optional[Asset]

property member_count[source]

Returns the true member count regardless of it being loaded fully or not.

Warning

Due to a Discord limitation, in order for this attribute to remain up-to-date and accurate, it requires Intents.members to be specified.

Type:

int

property region[source]

The region the guild belongs on.

Deprecated since version 2.5: VoiceRegion is no longer set on the guild, and is set on the individual voice channels instead. See VoiceChannel.rtc_region and StageChannel.rtc_region instead.

Changed in version 2.5: No longer a VoiceRegion instance.

Type:

Optional[str]

property chunked[source]

Whether the guild is “chunked”.

A chunked guild means that 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 shard_id[source]

Returns the shard ID for this guild if applicable.

Type:

int

property created_at[source]

Returns the guild’s creation time in UTC.

Type:

datetime.datetime

get_member_named(name, /)[source]

Returns the first member found that matches the name provided.

The lookup strategy is as follows (in order):

  1. Lookup by nickname.

  2. Lookup by global name.

  3. Lookup by username.

The name can have an optional discriminator argument, e.g. “Jake#0001”, in which case it will be treated as a username + discriminator combo (note: this only works with usernames, not nicknames).

If no member is found, None is returned.

Changed in version 2.9: Now takes User.global_name into account.

Parameters:

name (str) – The name of the member to lookup (with an optional discriminator).

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, position=..., topic=..., slowmode_delay=..., default_thread_slowmode_delay=..., default_auto_archive_duration=..., nsfw=..., news=..., overwrites=...)[source]

This function is a coroutine.

Creates a TextChannel for the guild.

You need manage_channels permission 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.6: Raises 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: disnake.PermissionOverwrite(view_channel=False),
    guild.me: disnake.PermissionOverwrite(view_channel=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[abc.Snowflake]) – 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 (Optional[str]) – The channel’s topic.

  • slowmode_delay (int) – Specifies the slowmode rate limit for users in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600. If not provided, slowmode is disabled.

  • default_thread_slowmode_delay (int) –

    Specifies the slowmode rate limit at which users can send messages in newly created threads in this channel, in seconds. A value of 0 disables slowmode by default. The maximum value possible is 21600. If not provided, slowmode is disabled.

    New in version 2.8.

  • default_auto_archive_duration (Union[int, ThreadArchiveDuration]) –

    The 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.5.

  • nsfw (bool) – Whether to mark the channel as NSFW.

  • news (bool) –

    Whether to make a news channel. News channels are text channels that can be followed. This is only available to guilds that contain NEWS in Guild.features.

    New in version 2.5.

  • 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, *, category=None, position=..., bitrate=..., user_limit=..., rtc_region=..., video_quality_mode=..., nsfw=..., slowmode_delay=..., overwrites=..., reason=None)[source]

This function is a coroutine.

This is similar to create_text_channel() except makes a VoiceChannel instead.

Changed in version 2.6: Raises 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[abc.Snowflake]) – 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[Union[str, VoiceRegion]]) –

    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.

  • nsfw (bool) –

    Whether to mark the channel as NSFW.

    New in version 2.5.

  • slowmode_delay (int) –

    Specifies the slowmode rate limit for users in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600. If not provided, slowmode is disabled.

    New in version 2.6.

  • 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, *, topic=..., position=..., bitrate=..., user_limit=..., rtc_region=..., video_quality_mode=..., overwrites=..., category=None, nsfw=..., slowmode_delay=..., reason=None)[source]

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.6: Raises TypeError instead of InvalidArgument.

Parameters:

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

  • topic (Optional[str]) –

    The channel’s topic.

    Changed in version 2.5: This is no longer required to be provided.

  • 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[abc.Snowflake]) – 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.6.

  • rtc_region (Optional[Union[str, VoiceRegion]]) –

    The region for the stage channel’s voice communication. A value of None indicates automatic voice region detection.

    New in version 2.5.

  • nsfw (bool) –

    Whether to mark the channel as NSFW.

    New in version 2.9.

  • slowmode_delay (int) –

    Specifies the slowmode rate limit for users in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600. If not provided, slowmode is disabled.

    New in version 2.9.

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_forum_channel(name, *, topic=None, category=None, position=..., slowmode_delay=..., default_thread_slowmode_delay=..., default_auto_archive_duration=None, nsfw=..., overwrites=..., available_tags=None, default_reaction=None, default_sort_order=None, default_layout=None, reason=None)[source]

This function is a coroutine.

This is similar to create_text_channel() except makes a ForumChannel instead.

New in version 2.5.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

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

  • topic (Optional[str]) – The channel’s topic.

  • category (Optional[abc.Snowflake]) – 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.

  • slowmode_delay (int) – Specifies the slowmode rate limit at which users can create threads in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600. If not provided, slowmode is disabled.

  • default_thread_slowmode_delay (int) –

    Specifies the slowmode rate limit at which users can send messages in newly created threads in this channel, in seconds. A value of 0 disables slowmode by default. The maximum value possible is 21600. If not provided, slowmode is disabled.

    New in version 2.6.

  • default_auto_archive_duration (Union[int, ThreadArchiveDuration]) – The default auto archive duration in minutes for threads created in this channel. Must be one of 60, 1440, 4320, or 10080.

  • nsfw (bool) – Whether to mark the channel as NSFW.

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

  • available_tags (Optional[Sequence[ForumTag]]) –

    The tags available for threads in this channel.

    New in version 2.6.

  • default_reaction (Optional[Union[str, Emoji, PartialEmoji]]) –

    The default emoji shown for reacting to threads.

    New in version 2.6.

  • default_sort_order (Optional[ThreadSortOrder]) –

    The default sort order of threads in this channel.

    New in version 2.6.

  • default_layout (ThreadLayout) –

    The default layout of threads in this channel.

    New in version 2.10.

  • 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:

ForumChannel

await create_media_channel(name, *, topic=None, category=None, position=..., slowmode_delay=..., default_thread_slowmode_delay=..., default_auto_archive_duration=None, nsfw=..., overwrites=..., available_tags=None, default_reaction=None, default_sort_order=None, reason=None)[source]

This function is a coroutine.

This is similar to create_text_channel() except makes a MediaChannel instead.

New in version 2.10.

Parameters:

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

  • topic (Optional[str]) – The channel’s topic.

  • category (Optional[abc.Snowflake]) – 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.

  • slowmode_delay (int) – Specifies the slowmode rate limit at which users can create threads in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600. If not provided, slowmode is disabled.

  • default_thread_slowmode_delay (int) – Specifies the slowmode rate limit at which users can send messages in newly created threads in this channel, in seconds. A value of 0 disables slowmode by default. The maximum value possible is 21600. If not provided, slowmode is disabled.

  • default_auto_archive_duration (Union[int, ThreadArchiveDuration]) – The default auto archive duration in minutes for threads created in this channel. Must be one of 60, 1440, 4320, or 10080.

  • nsfw (bool) – Whether to mark the channel as NSFW.

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

  • available_tags (Optional[Sequence[ForumTag]]) – The tags available for threads in this channel.

  • default_reaction (Optional[Union[str, Emoji, PartialEmoji]]) – The default emoji shown for reacting to threads.

  • default_sort_order (Optional[ThreadSortOrder]) – The default sort order of threads in this channel.

  • 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:

MediaChannel

await create_category(name, *, overwrites=..., reason=None, position=...)[source]

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.6: Raises TypeError instead of InvalidArgument.

Parameters:

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

  • overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite which can be synced to channels.

  • position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

  • reason (Optional[str]) – The reason for creating this category. 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:

CategoryChannel

await create_category_channel(name, *, overwrites=..., reason=None, position=...)[source]

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.6: Raises TypeError instead of InvalidArgument.

Parameters:

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

  • overwrites (Dict[Union[Role, Member], PermissionOverwrite]) – A dict of target (either a role or a member) to PermissionOverwrite which can be synced to channels.

  • position (int) – The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0.

  • reason (Optional[str]) – The reason for creating this category. 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:

CategoryChannel

await leave()[source]

This function is a coroutine.

Leaves the guild.

Note

You cannot leave the guild that you own, you must delete it instead via delete().

Raises:

HTTPException – Leaving the guild failed.

await delete()[source]

This function is a coroutine.

Deletes the guild. You must be the guild owner to delete the guild.

Raises:
await edit(*, reason=..., name=..., description=..., icon=..., banner=..., splash=..., discovery_splash=..., community=..., invites_disabled=..., raid_alerts_disabled=..., 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=..., safety_alerts_channel=..., premium_progress_bar_enabled=...)[source]

This function is a coroutine.

Edits the guild.

You must have manage_guild permission to use this.

Changed in version 1.4: The rules_channel and public_updates_channel keyword-only parameters were added.

Changed in version 2.0: The discovery_splash and community keyword-only parameters were added.

Changed in version 2.0: The newly updated guild is returned.

Changed in version 2.5: Removed the region parameter. Use VoiceChannel.edit() or StageChannel.edit() with rtc_region instead.

Changed in version 2.6: Raises 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. This is only available to guilds that contain COMMUNITY in Guild.features.

  • icon (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    The new guild icon. Only PNG/JPG is supported. GIF is only available to guilds that contain ANIMATED_ICON in Guild.features. Could be None to denote removal of the icon.

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • banner (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    The new guild banner. 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.

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • splash (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    The new guild invite splash. Only PNG/JPG is supported. Could be None to denote removing the splash. This is only available to guilds that contain INVITE_SPLASH in Guild.features.

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • discovery_splash (Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]) –

    The new guild discovery splash. Only PNG/JPG is supported. Could be None to denote removing the splash. This is only available to guilds that contain DISCOVERABLE in Guild.features.

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • community (bool) – Whether the guild should be a Community guild. If set to True, both rules_channel and public_updates_channel parameters are required.

  • invites_disabled (bool) –

    Whether the guild has paused invites, preventing new users from joining.

    This is only available to guilds that contain COMMUNITY in Guild.features.

    This cannot be changed at the same time as the community feature due a Discord API limitation.

    New in version 2.6.

  • raid_alerts_disabled (bool) –

    Whether the guild has disabled join raid alerts.

    This is only available to guilds that contain COMMUNITY in Guild.features.

    This cannot be changed at the same time as the community feature due a Discord API limitation.

    New in version 2.9.

  • 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. This can be set to 60, 300, 900, 1800, and 3600.

  • 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.5: Changed to Locale 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.

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

  • safety_alerts_channel (Optional[TextChannel]) –

    The new channel that is used for safety alerts. This is only available to guilds that contain COMMUNITY in Guild.features. Could be None for no safety alerts channel.

    New in version 2.9.

  • premium_progress_bar_enabled (bool) – Whether the server boost progress bar is enabled.

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

Raises:

  • NotFound – At least one of the assets (icon, banner, splash or discovery_splash) couldn’t be found.

  • Forbidden – You do not have permissions to edit the guild.

  • HTTPException – Editing the guild failed.

  • TypeError – At least one of the assets (icon, banner, splash or discovery_splash) is a lottie sticker (see Sticker.read()), or one of the parameters default_notifications, verification_level, explicit_content_filter, or system_channel_flags was of the incorrect type.

  • ValueError – community was set without setting both rules_channel and public_updates_channel parameters, or if you are not the owner of the guild and request an ownership transfer, or the image format passed in to icon is invalid, or both community and invites_disabled` or ``raid_alerts_disabled were provided.

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:

Guild

await fetch_channels()[source]

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:
Returns:

All channels that the guild has.

Return type:

Sequence[abc.GuildChannel]

await active_threads()[source]

This function is a coroutine.

Returns a list of active Thread that the client can access.

This includes both private and public threads.

New in version 2.0.

Raises:

HTTPException – The request to get the active threads failed.

Returns:

The active threads.

Return type:

List[Thread]

await fetch_scheduled_events(*, with_user_count=False)[source]

This function is a coroutine.

Retrieves a list of all GuildScheduledEvent instances that the guild has.

New in version 2.3.

Parameters:

with_user_count (bool) – Whether to include number of users subscribed to each event.

Raises:

HTTPException – Retrieving the guild scheduled events failed.

Returns:

The existing guild scheduled events.

Return type:

List[GuildScheduledEvent]

await fetch_scheduled_event(event_id, *, with_user_count=False)[source]

This function is a coroutine.

Retrieves a GuildScheduledEvent with the given ID.

New in version 2.3.

Parameters:

  • event_id (int) – The ID to look for.

  • with_user_count (bool) – Whether to include number of users subscribed to the event.

Raises:

HTTPException – Retrieving the guild scheduled event failed.

Returns:

The guild scheduled event.

Return type:

GuildScheduledEvent

await create_scheduled_event(*, name, scheduled_start_time, channel=..., entity_type=..., scheduled_end_time=..., privacy_level=..., entity_metadata=..., description=..., image=..., reason=None)[source]

This function is a coroutine.

Creates a GuildScheduledEvent.

You must have manage_events permission to do this.

Based on the channel/entity type, there are different restrictions regarding other parameter values, as shown in this table:

channel

entity_type

scheduled_end_time

entity_metadata with location

abc.Snowflake with type attribute being ChannelType.voice

voice (set automatically)

optional

unset

abc.Snowflake with type attribute being ChannelType.stage_voice

stage_instance (set automatically)

optional

unset

abc.Snowflake with missing/other type attribute

required

optional

unset

None

external (set automatically)

required

required

unset

external

required

required

New in version 2.3.

Changed in version 2.6: Now raises TypeError instead of ValueError for invalid parameter types.

Changed in version 2.6: Removed channel_id parameter in favor of channel.

Changed in version 2.6: Naive datetime parameters are now assumed to be in the local timezone instead of UTC.

Changed in version 2.6: Infer entity_type from channel if provided.

Parameters:

  • name (str) – The name of the guild scheduled event.

  • description (str) – The description of the guild scheduled event.

  • image (Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]) –

    The cover image of the guild scheduled event.

    New in version 2.4.

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • channel (Optional[abc.Snowflake]) –

    The channel in which the guild scheduled event will be hosted. Passing in None assumes the entity_type to be GuildScheduledEventEntityType.external

    New in version 2.6.

  • privacy_level (GuildScheduledEventPrivacyLevel) – The privacy level of the guild scheduled event.

  • scheduled_start_time (datetime.datetime) – The time to schedule the guild scheduled event. If the datetime is naive, it is assumed to be local time.

  • scheduled_end_time (Optional[datetime.datetime]) – The time when the guild scheduled event is scheduled to end. If the datetime is naive, it is assumed to be local time.

  • entity_type (GuildScheduledEventEntityType) – The entity type of the guild scheduled event.

  • entity_metadata (GuildScheduledEventMetadata) – The entity metadata of the guild scheduled event.

  • reason (Optional[str]) – The reason for creating the guild scheduled event. Shows up on the audit log.

Raises:

  • NotFound – The image asset couldn’t be found.

  • HTTPException – The request failed.

  • TypeError – The image asset is a lottie sticker (see Sticker.read()), one of entity_type, privacy_level, or entity_metadata is not of the correct type, or the entity_type was not provided and could not be assumed from the channel.

Returns:

The newly created guild scheduled event.

Return type:

GuildScheduledEvent

await welcome_screen()[source]

This function is a coroutine.

Retrieves the guild’s WelcomeScreen.

Requires the manage_guild permission if the welcome screen is not enabled.

Note

To determine whether the welcome screen is enabled, check for the presence of WELCOME_SCREEN_ENABLED in Guild.features.

New in version 2.5.

Raises:

  • NotFound – The welcome screen is not set up, or you do not have permission to view it.

  • HTTPException – Retrieving the welcome screen failed.

Returns:

The guild’s welcome screen.

Return type:

WelcomeScreen

await edit_welcome_screen(*, enabled=..., channels=..., description=..., reason=None)[source]

This function is a coroutine.

This is a lower level method to WelcomeScreen.edit() that allows you to edit the welcome screen without fetching it and save an API request.

This requires ‘COMMUNITY’ in Guild.features.

New in version 2.5.

Parameters:

  • enabled (bool) – Whether the welcome screen is enabled.

  • description (Optional[str]) – The new guild description in the welcome screen.

  • channels (Optional[List[WelcomeScreenChannel]]) – The new welcome channels.

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

Raises:
Returns:

The newly edited welcome screen.

Return type:

WelcomeScreen

await fetch_member(member_id, /)[source]

This function is a coroutine.

Retrieves a Member with the given ID.

Note

This method is an API call. If you have Intents.members and member cache enabled, consider get_member() instead.

Parameters:

member_id (int) – The member’s ID to fetch from.

Raises:

  • NotFound – A member with this ID does not exist in the guild.

  • Forbidden – You do not have access to the guild.

  • HTTPException – Retrieving the member failed.

Returns:

The member from the member ID.

Return type:

Member

await fetch_ban(user)[source]

This function is a coroutine.

Retrieves the BanEntry for a user.

You must have ban_members permission to use this.

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, /)[source]

This function is a coroutine.

Retrieves a abc.GuildChannel or Thread with the given 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]

bans(*, limit=1000, before=None, after=None)[source]

Returns an AsyncIterator that enables receiving the destination’s bans.

You must have the ban_members permission to get this information.

Changed in version 2.5: Due to a breaking change in Discord’s API, this now returns an AsyncIterator instead of a list.

Examples

Usage

counter = 0
async for ban in guild.bans(limit=200):
    if not ban.user.bot:
        counter += 1

Flattening into a list:

bans = await guild.bans(limit=123).flatten()
# 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 (Optional[Snowflake]) – Retrieve bans before this user.

  • after (Optional[Snowflake]) – Retrieve bans after this user.

Raises:

  • Forbidden – You do not have permissions to get the bans.

  • HTTPException – An error occurred while fetching the bans.

Yields:

BanEntry – The ban with the ban data parsed.

await prune_members(*, days, compute_prune_count=True, roles=..., reason=None)[source]

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 the manage_guild and kick_members permissions to use 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.6: Raises TypeError instead of InvalidArgument.

Parameters:

  • days (int) – The number of days before counting as inactive.

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

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

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()[source]

This function is a coroutine.

Gets the list of templates from this guild.

You must have manage_guild permission to use 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()[source]

This function is a coroutine.

Gets the list of webhooks from this guild.

You must have manage_webhooks permission to use 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=...)[source]

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.6: Raises 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:

int

await invites()[source]

This function is a coroutine.

Returns a list of all active instant invites from the guild.

You must have manage_guild permission to use this.

Note

This method does not include the guild’s vanity URL invite. To get the vanity URL Invite, refer to Guild.vanity_invite().

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=...)[source]

This function is a coroutine.

Creates a template for the guild.

You must have manage_guild permission to use this.

New in version 1.7.

Parameters:

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

  • description (str) – The description of the template.

Returns:

The created template.

Return type:

Template

await create_integration(*, type, id)[source]

This function is a coroutine.

Deprecated since version 2.5: No longer supported, bots cannot use this endpoint anymore.

Attaches an integration to the guild.

You must have manage_guild permission to use this.

New in version 1.4.

Parameters:

  • type (str) – The integration type (e.g. Twitch).

  • id (int) – The integration ID.

Raises:

  • Forbidden – You do not have permission to create the integration.

  • HTTPException – The account could not be found.

await integrations()[source]

This function is a coroutine.

Returns a list of all integrations attached to the guild.

You must have manage_guild permission to use this.

New in version 1.4.

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 fetch_stickers()[source]

This function is a coroutine.

Retrieves a list of all Stickers that the guild has.

New in version 2.0.

Note

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

Raises:

HTTPException – Retrieving the stickers failed.

Returns:

The retrieved stickers.

Return type:

List[GuildSticker]

await fetch_sticker(sticker_id, /)[source]

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 – Retrieving the sticker failed.

Returns:

The retrieved sticker.

Return type:

GuildSticker

await create_sticker(*, name, description=None, emoji, file, reason=None)[source]

This function is a coroutine.

Creates a Sticker for the guild.

You must have manage_guild_expressions permission to do this.

New in version 2.0.

Parameters:

  • name (str) – The sticker name. Must be at least 2 characters.

  • description (Optional[str]) – The sticker’s description. You can pass None or an empty string to not set a 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 (Optional[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 newly created sticker.

Return type:

GuildSticker

await delete_sticker(sticker, *, reason=None)[source]

This function is a coroutine.

Deletes the custom Sticker from the guild.

You must have manage_guild_expressions permission 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 this sticker.

  • HTTPException – An error occurred deleting the sticker.

await fetch_emojis()[source]

This function is a coroutine.

Retrieves all custom Emojis that the guild has.

Note

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

Raises:

HTTPException – Retrieving the emojis failed.

Returns:

The retrieved emojis.

Return type:

List[Emoji]

await fetch_emoji(emoji_id, /)[source]

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.

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

This function is a coroutine.

Creates a custom Emoji for the guild.

Depending on the boost level of your guild (which can be obtained via premium_tier), the amount of custom emojis that can be created changes:

Boost level

Max custom emoji limit

0

50

1

100

2

150

3

250

Emojis with subscription roles (see roles below) are considered premium emoji, and count towards a separate limit of 25 emojis.

You must have manage_guild_expressions permission to do this.

Parameters:

  • name (str) – The emoji name. Must be at least 2 characters.

  • image (Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]) –

    The image data of the emoji. Only JPG, PNG and GIF images are supported.

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • roles (List[Role]) –

    A list of roles that can use this emoji. Leave empty to make it available to everyone.

    An emoji cannot have both subscription roles (see RoleTags.integration_id) and non-subscription roles, and emojis can’t be converted between premium and non-premium after creation.

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

Raises:
Returns:

The newly created emoji.

Return type:

Emoji

await delete_emoji(emoji, *, reason=None)[source]

This function is a coroutine.

Deletes the custom Emoji from the guild.

You must have manage_guild_expressions permission to do this.

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 this emoji.

  • HTTPException – An error occurred deleting the emoji.

await fetch_role(role_id, /)[source]

This function is a coroutine.

Retrieve a Role.

Note

This method is an API call. For general usage, consider get_role() or roles instead.

New in version 2.10.

Parameters:

role_id (int) – The ID of the role to retrieve.

Raises:
Returns:

The retrieved role.

Return type:

Role

await fetch_roles()[source]

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 that the guild has.

Return type:

List[Role]

await get_or_fetch_member(member_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the member from the cache. If it fails, fetches the member from the API and caches it.

If you want to make a bulk get-or-fetch call, use get_or_fetch_members().

This only propagates exceptions when the strict parameter is enabled.

Parameters:

  • member_id (int) – The ID to search for.

  • strict (bool) – Whether to propagate exceptions from fetch_member() instead of returning None in case of failure (e.g. if the member wasn’t found). Defaults to False.

Returns:

The member with the given ID, or None if not found and strict is set to False.

Return type:

Optional[Member]

await getch_member(member_id, *, strict=False)[source]

This function is a coroutine.

Tries to get the member from the cache. If it fails, fetches the member from the API and caches it.

If you want to make a bulk get-or-fetch call, use get_or_fetch_members().

This only propagates exceptions when the strict parameter is enabled.

Parameters:

  • member_id (int) – The ID to search for.

  • strict (bool) – Whether to propagate exceptions from fetch_member() instead of returning None in case of failure (e.g. if the member wasn’t found). Defaults to False.

Returns:

The member with the given ID, or None if not found and strict is set to False.

Return type:

Optional[Member]

await create_role(*, name=..., permissions=..., color=..., colour=..., hoist=..., icon=..., emoji=..., mentionable=..., reason=None)[source]

This function is a coroutine.

Creates a Role for the guild.

All fields are optional.

You must have manage_roles permission to do this.

Changed in version 1.6: Can now pass int to colour keyword-only parameter.

Changed in version 2.6: Raises TypeError instead of InvalidArgument.

Parameters:

  • name (str) – The role name. Defaults to ‘new role’.

  • permissions (Permissions) – The permissions the role should 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) – Whether the role should be shown separately in the member list. Defaults to False.

  • icon (Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]) –

    The role’s icon image (if the guild has the ROLE_ICONS feature).

    Changed in version 2.5: Now accepts various resource types in addition to bytes.

  • emoji (str) – The role’s unicode emoji.

  • mentionable (bool) – Whether the role should be mentionable by others. Defaults to False.

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

Raises:

  • NotFound – The icon asset couldn’t be found.

  • Forbidden – You do not have permissions to create the role.

  • HTTPException – Creating the role failed.

  • TypeError – An invalid keyword argument was given, or the icon asset is a lottie sticker (see Sticker.read()).

Returns:

The newly created role.

Return type:

Role

await edit_role_positions(positions, *, reason=None)[source]

This function is a coroutine.

Bulk edits a list of Role in the guild.

You must have manage_roles permission to do this.

New in version 1.4.

Changed in version 2.6: Raises 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 kick(user, *, reason=None)[source]

This function is a coroutine.

Kicks a user from the guild.

The user must meet the abc.Snowflake abc.

You must have kick_members permission to do this.

Parameters:

  • user (abc.Snowflake) – The user to kick from the guild.

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

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

This function is a coroutine.

Bans a user from the guild.

The user must meet the abc.Snowflake abc.

You must have ban_members permission to do this.

Parameters:

  • user (abc.Snowflake) – The user to ban from the guild.

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

    The timespan (seconds or timedelta) of messages to delete from the user in the guild, up to 7 days (604800 seconds). Defaults to 1 day (86400 seconds).

    This is incompatible with delete_message_days.

    New in version 2.6.

    Note

    This may not be accurate with small durations (e.g. a few minutes) and delete a couple minutes’ worth of messages more than specified.

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

    This is incompatible with clean_history_duration.

    Deprecated since version 2.6: Use clean_history_duration instead.

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

Raises:

  • TypeError – Both clean_history_duration and delete_message_days were provided, or clean_history_duration has an invalid type.

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

  • HTTPException – Banning failed.

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

This function is a coroutine.

Unbans a user from the guild.

The user must meet the abc.Snowflake abc.

You must have ban_members permission to do this.

Parameters:

  • user (abc.Snowflake) – The user to unban.

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

Raises:
await bulk_ban(users, *, clean_history_duration=0, reason=None)[source]

This function is a coroutine.

Bans multiple users from the guild at once.

The users must meet the abc.Snowflake abc.

You must have ban_members and manage_guild permissions to do this.

New in version 2.10.

Parameters:

  • users (Iterable[abc.Snowflake]) – The users to ban from the guild, up to 200.

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

    The timespan (seconds or timedelta) of messages to delete from the users in the guild, up to 7 days (604800 seconds). Defaults to 0.

    Note

    This may not be accurate with small durations (e.g. a few minutes) and delete a couple minutes’ worth of messages more than specified.

  • reason (Optional[str]) – The reason for banning the users. Shows up on the audit log.

Raises:

  • TypeError – clean_history_duration has an invalid type.

  • Forbidden – You do not have the proper permissions to bulk ban.

  • HTTPException – Banning failed. This is also raised if none of the users could be banned.

Returns:

An object containing the successful and failed bans.

Return type:

BulkBanResult

await vanity_invite(*, use_cached=False)[source]

This function is a coroutine.

Returns the guild’s special vanity invite.

The guild must have VANITY_URL in features.

If use_cached is False, then you must have manage_guild permission to use this.

Parameters:

use_cached (bool) –

Whether to use the cached Guild.vanity_url_code and attempt to convert it into a full invite.

Note

If set to True, the Invite.uses information will not be accurate.

New in version 2.5.

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]

await widget()[source]

This function is a coroutine.

Retrieves the widget of the guild.

Note

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

Raises:
Returns:

The guild’s widget.

Return type:

Widget

await widget_settings()[source]

This function is a coroutine.

Retrieves the widget settings of the guild.

To edit the widget settings, you may also use edit_widget().

New in version 2.5.

Raises:

  • Forbidden – You do not have permission to view the widget settings.

  • HTTPException – Retrieving the widget settings failed.

Returns:

The guild’s widget settings.

Return type:

WidgetSettings

await edit_widget(*, enabled=..., channel=..., reason=None)[source]

This function is a coroutine.

Edits the widget of the guild.

You must have manage_guild permission to use this.

New in version 2.0.

Changed in version 2.5: Returns the new widget settings.

Parameters:

  • enabled (bool) – Whether to enable the widget for the guild.

  • channel (Optional[Snowflake]) – The new widget channel. None removes the widget channel. If set, an invite link for this channel will be generated, which allows users to join the guild from the widget.

  • reason (Optional[str]) –

    The reason for editing the widget. Shows up on the audit log.

    New in version 2.4.

Raises:
Returns:

The new widget settings.

Return type:

WidgetSettings

widget_image_url(style=<WidgetStyle.shield: 'shield'>)[source]

Returns an URL to the widget’s .png image.

New in version 2.5.

Parameters:

style (WidgetStyle) – The widget style.

Returns:

The widget image URL.

Return type:

str

await edit_mfa_level(mfa_level, *, reason=None)[source]

This function is a coroutine.

Edits the two-factor authentication level of the guild.

You must be the guild owner to use this.

New in version 2.6.

Parameters:

  • mfa_level (int) – The new 2FA level. If set to 0, the guild does not require 2FA for their administrative members to take moderation actions. If set to 1, then 2FA is required.

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

Raises:
await chunk(*, cache=True)[source]

This function is a coroutine.

Returns a list of all guild members.

Requests all members that belong to this guild. In order to use this, Intents.members() must be enabled.

This is a websocket operation and can be slow.

New in version 1.5.

Parameters:

cache (bool) – Whether to cache the members as well.

Raises:

ClientException – The members intent is not enabled.

Returns:

Returns a list of all the members within the guild.

Return type:

Optional[List[Member]]

await query_members(query=None, *, limit=5, user_ids=None, presences=False, cache=True)[source]

This function is a coroutine.

Request members that belong to this guild whose name starts with the query given.

This is a websocket operation and can be slow.

See also search_members().

New in version 1.3.

Parameters:

  • query (Optional[str]) – The string that the names 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 False.

    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.

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

Raises:
Returns:

The list of members that have matched the query.

Return type:

List[Member]

await search_members(query, *, limit=1, cache=True)[source]

This function is a coroutine.

Retrieves members that belong to this guild whose name starts with the query given.

Note that unlike query_members(), this is not a websocket operation, but an HTTP operation.

See also query_members().

New in version 2.5.

Parameters:

  • query (str) – The string that the names start with.

  • limit (int) – The maximum number of members to send back. This must be a number between 1 and 1000.

  • cache (bool) – Whether to cache the members internally. This makes operations such as get_member() work for those that matched.

Raises:

ValueError – Invalid parameters were passed to the function

Returns:

The list of members that have matched the query.

Return type:

List[Member]

await get_or_fetch_members(user_ids, *, presences=False, cache=True)[source]

This function is a coroutine.

Tries to get the guild members matching the provided IDs from cache. If some of them were not found, the method requests the missing members using websocket operations. If cache kwarg is True (default value) the missing members will be cached.

If more than 100 members are missing, several websocket operations are made.

Websocket operations can be slow, however, this method is cheaper than multiple get_or_fetch_member() calls.

New in version 2.4.

Parameters:

  • user_ids (List[int]) – List of user IDs to search for. If the user ID is not in the guild then it won’t be returned.

  • presences (bool) – Whether to request for presences to be provided. Defaults to False.

  • cache (bool) – Whether to cache the missing members internally. This makes operations such as get_member() work for those that matched. It also speeds up this method on repeated calls. Defaults to True.

Raises:
Returns:

The list of members with the given IDs, if they exist.

Return type:

List[Member]

await getch_members(user_ids, *, presences=False, cache=True)[source]

This function is a coroutine.

Tries to get the guild members matching the provided IDs from cache. If some of them were not found, the method requests the missing members using websocket operations. If cache kwarg is True (default value) the missing members will be cached.

If more than 100 members are missing, several websocket operations are made.

Websocket operations can be slow, however, this method is cheaper than multiple get_or_fetch_member() calls.

New in version 2.4.

Parameters:

  • user_ids (List[int]) – List of user IDs to search for. If the user ID is not in the guild then it won’t be returned.

  • presences (bool) – Whether to request for presences to be provided. Defaults to False.

  • cache (bool) – Whether to cache the missing members internally. This makes operations such as get_member() work for those that matched. It also speeds up this method on repeated calls. Defaults to True.

Raises:
Returns:

The list of members with the given IDs, if they exist.

Return type:

List[Member]

await fetch_voice_regions()[source]

This function is a coroutine.

Retrieves a list of VoiceRegion for this guild.

New in version 2.5.

Raises:

HTTPException – Retrieving voice regions failed.

await fetch_voice_state(member_id, /)[source]

This function is a coroutine.

Fetches the VoiceState of a member.

Note

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

New in version 2.10.

Parameters:

member_id (int) – The ID of the member.

Raises:

  • NotFound – The member for which you tried to fetch a voice state is not connected to a channel in this guild.

  • Forbidden – You do not have permission to fetch the member’s voice state.

  • HTTPException – Fetching the voice state failed.

Returns:

The voice state of the member.

Return type:

VoiceState

await change_voice_state(*, channel, self_mute=False, self_deaf=False)[source]

This function is a coroutine.

Changes client’s voice state in the guild.

New in version 1.4.

Parameters:

  • channel (Optional[VoiceChannel]) – The channel the client wants to join. Use None to disconnect.

  • self_mute (bool) – Whether the client should be self-muted.

  • self_deaf (bool) – Whether the client should be self-deafened.

await bulk_fetch_command_permissions()[source]

This function is a coroutine.

Requests a list of GuildApplicationCommandPermissions configured for this guild.

New in version 2.1.

await fetch_command_permissions(command_id)[source]

This function is a coroutine.

Retrieves GuildApplicationCommandPermissions for a specific command.

New in version 2.1.

Parameters:

command_id (int) –

The ID of the application command, or the application ID to fetch application-wide permissions.

Changed in version 2.5: Can now also fetch application-wide permissions.

Returns:

The application command permissions.

Return type:

GuildApplicationCommandPermissions

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

This function is a coroutine.

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

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

The user must meet the abc.Snowflake abc.

You must have the moderate_members permission to do this.

New in version 2.3.

Parameters:

  • user (abc.Snowflake) – The member to timeout.

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

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

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

Raises:

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

  • HTTPException – Timing out the member failed.

Returns:

The newly updated member.

Return type:

Member

await fetch_automod_rule(rule_id, /)[source]

This function is a coroutine.

Retrieves an auto moderation rules from the guild. See also fetch_automod_rules().

Requires the manage_guild permission.

New in version 2.6.

Raises:

  • Forbidden – You do not have proper permissions to retrieve auto moderation rules.

  • NotFound – An auto moderation rule with the provided ID does not exist in the guild.

  • HTTPException – Retrieving the rule failed.

Returns:

The auto moderation rule.

Return type:

AutoModRule

await fetch_automod_rules()[source]

This function is a coroutine.

Retrieves the guild’s auto moderation rules. See also fetch_automod_rule().

Requires the manage_guild permission.

New in version 2.6.

Raises:

  • Forbidden – You do not have proper permissions to retrieve auto moderation rules.

  • NotFound – The guild does not have any auto moderation rules set up.

  • HTTPException – Retrieving the rules failed.

Returns:

The guild’s auto moderation rules.

Return type:

List[AutoModRule]

await create_automod_rule(*, name, event_type, trigger_type, actions, trigger_metadata=None, enabled=False, exempt_roles=None, exempt_channels=None, reason=None)[source]

This function is a coroutine.

Creates a new AutoModRule for the guild.

You must have Permissions.manage_guild permission to do this.

The maximum number of rules for each trigger type is limited, see the api docs for more details.

New in version 2.6.

Changed in version 2.9: Now raises a TypeError if given actions have an invalid type.

Parameters:

  • name (str) – The rule name.

  • event_type (AutoModEventType) – The type of events that this rule will be applied to.

  • trigger_type (AutoModTriggerType) – The type of trigger that determines whether this rule’s actions should run for a specific event. If set to keyword, keyword_preset, or mention_spam, trigger_metadata must be set accordingly. This cannot be changed after creation.

  • actions (Sequence[Union[AutoModBlockMessageAction, AutoModSendAlertAction, AutoModTimeoutAction, AutoModAction]]) – The list of actions that will execute if a matching event triggered this rule. Must contain at least one action.

  • trigger_metadata (Optional[AutoModTriggerMetadata]) – Additional metadata associated with the trigger type.

  • enabled (bool) – Whether to enable the rule. Defaults to False.

  • exempt_roles (Optional[Sequence[abc.Snowflake]]) – The roles that are exempt from this rule, up to 20. By default, no roles are exempt.

  • exempt_channels (Optional[Sequence[abc.Snowflake]]) – The channels that are exempt from this rule, up to 50. By default, no channels are exempt. Can also include categories, in which case all channels inside that category will be exempt.

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

Raises:

  • ValueError – The specified trigger type requires trigger_metadata to be set, or no actions have been provided.

  • TypeError – The specified actions are of an invalid type.

  • Forbidden – You do not have proper permissions to create auto moderation rules.

  • HTTPException – Creating the rule failed.

Returns:

The newly created auto moderation rule.

Return type:

AutoModRule

await onboarding()[source]

This function is a coroutine.

Retrieves the guild onboarding data.

New in version 2.9.

Raises:

HTTPException – Retrieving the guild onboarding data failed.

Returns:

The guild onboarding data.

Return type:

Onboarding

GuildPreview

Attributes
class disnake.GuildPreview[source]

Represents a Guild preview object.

New in version 2.5.

name

The guild’s name.

Type:

str

emojis

All emojis that the guild owns.

Type:

Tuple[Emoji, …]

stickers

All stickers that the guild owns.

Type:

Tuple[GuildSticker, …]

id

The ID of the guild this preview represents.

Type:

int

description

The guild’s description.

Type:

Optional[str]

features

A list of features that the guild has. The features that a guild can have are subject to arbitrary change by Discord.

See Guild.features for a list of features.

Type:

List[str]

approximate_member_count

The approximate number of members in the guild.

Type:

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:

int

property icon[source]

Returns the guild preview’s icon asset, if available.

Type:

Optional[Asset]

property splash[source]

Returns the guild preview’s invite splash asset, if available.

Type:

Optional[Asset]

property discovery_splash[source]

Returns the guild preview’s discovery splash asset, if available.

Type:

Optional[Asset]

Template

Attributes
Methods
class disnake.Template[source]

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 source guild.

Type:

Guild

is_dirty

Whether the template has unsynced changes.

New in version 2.0.

Type:

Optional[bool]

await create_guild(name, icon=None)[source]

This function is a coroutine.

Creates a Guild using the template.

Bot accounts in more than 10 guilds are not allowed to create guilds.

Changed in version 2.5: Removed the region parameter.

Changed in version 2.6: Raises ValueError instead of InvalidArgument.

Parameters:
Raises:
Returns:

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

Return type:

Guild

await sync()[source]

This function is a coroutine.

Syncs the template to the guild’s current state.

You must have the manage_guild permission 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=...)[source]

This function is a coroutine.

Edits the template metadata.

You must have the manage_guild permission 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()[source]

This function is a coroutine.

Deletes the template.

You must have the manage_guild permission 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[source]

The template url.

New in version 2.0.

Type:

str

WelcomeScreen

Attributes
Methods
class disnake.WelcomeScreen[source]

Represents a Discord welcome screen for a Guild.

New in version 2.5.

description

The guild description in the welcome screen.

Type:

Optional[str]

channels

The welcome screen’s channels.

Type:

List[WelcomeScreenChannel]

property enabled[source]

Whether the welcome screen is displayed to users. This is equivalent to checking if WELCOME_SCREEN_ENABLED is present in Guild.features.

Type:

bool

await edit(*, enabled=..., description=..., channels=..., reason=None)[source]

This function is a coroutine.

Edits the welcome screen.

You must have the manage_guild permission to use this.

This requires ‘COMMUNITY’ in Guild.features.

Parameters:

  • enabled (bool) – Whether the welcome screen is enabled.

  • description (Optional[str]) – The new guild description in the welcome screen.

  • channels (Optional[List[WelcomeScreenChannel]]) – The new welcome channels.

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

Raises:
Returns:

The newly edited welcome screen.

Return type:

WelcomeScreen

BanEntry

class disnake.BanEntry[source]

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

BulkBanResult

class disnake.BulkBanResult

A NamedTuple which represents the successful and failed bans returned from bulk_ban().

New in version 2.10.

banned

The users that were successfully banned.

Type:

Sequence[Object]

failed

The users that were not banned.

Type:

Sequence[Object]

Onboarding

Attributes
class disnake.Onboarding[source]

Represents a guild onboarding object.

New in version 2.9.

guild

The guild this onboarding is part of.

Type:

Guild

prompts

The prompts shown during onboarding and in community customization.

Type:

List[OnboardingPrompt]

enabled

Whether onboarding is enabled.

Type:

bool

default_channel_ids

The IDs of the channels that will be shown to new members by default.

Type:

FrozenSet[int]

property default_channels[source]

The list of channels that will be shown to new members by default.

Type:

List[abc.GuildChannel]

OnboardingPrompt

Attributes
class disnake.OnboardingPrompt[source]

Represents an onboarding prompt.

New in version 2.9.

id

The onboarding prompt’s ID.

Type:

int

type

The onboarding prompt’s type.

Type:

OnboardingPromptType

options

The onboarding prompt’s options.

Type:

List[OnboardingPromptOption]

title

The onboarding prompt’s title.

Type:

str

single_select

Whether users are limited to selecting one option for the prompt.

Type:

bool

required

Whether the prompt is required before a user completes the onboarding flow.

Type:

bool

in_onboarding

Whether the prompt is present in the onboarding flow. If False, the prompt will only appear in community customization.

Type:

bool

OnboardingPromptOption

Attributes
class disnake.OnboardingPromptOption[source]

Represents an onboarding prompt option.

New in version 2.9.

id

The prompt option’s ID.

Type:

int

emoji

The prompt option’s emoji.

Type:

Optional[Union[PartialEmoji, Emoji, str]]

title

The prompt option’s title.

Type:

str

description

The prompt option’s description.

Type:

Optional[str]

role_ids

The IDs of the roles that will be added to the user when they select this option.

Type:

FrozenSet[int]

channel_ids

The IDs of the channels that the user will see when they select this option.

Type:

FrozenSet[int]

property roles[source]

A list of roles that will be added to the user when they select this option.

Type:

List[Role]

property channels[source]

A list of channels that the user will see when they select this option.

Type:

List[abc.GuildChannel]

Data Classes

SystemChannelFlags

Attributes
class disnake.SystemChannelFlags[source]

Wraps up a Discord system channel flag value.

Similar to Permissions, the properties provided are two way. You can set and retrieve individual bits using the properties as if they were regular bools. This allows you to edit the system flags easily.

To construct an object you can pass keyword arguments denoting the flags to enable or disable. Arguments are applied in order, similar to Permissions.

x == y

Checks if two SystemChannelFlags instances are equal.

x != y

Checks if two SystemChannelFlags instances are not equal.

x <= y

Checks if a SystemChannelFlags instance is a subset of another SystemChannelFlags instance.

New in version 2.6.

x >= y

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

New in version 2.6.

x < y

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

New in version 2.6.

x > y

Checks if a SystemChannelFlags instance is a strict superset of another SystemChannelFlags instance.

New in version 2.6.

x | y, x |= y

Returns a new SystemChannelFlags instance with all enabled flags from both x and y. (Using |= will update in place).

New in version 2.6.

x & y, x &= y

Returns a new SystemChannelFlags instance with only flags enabled on both x and y. (Using &= will update in place).

New in version 2.6.

x ^ y, x ^= y

Returns a new SystemChannelFlags instance with only flags enabled on one of x or y, but not both. (Using ^= will update in place).

New in version 2.6.

~x

Returns a new SystemChannelFlags instance with all flags from x inverted.

New in version 2.6.

hash(x)

Return the flag’s hash.

iter(x)

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

Additionally supported are a few operations on class attributes.

SystemChannelFlags.y | SystemChannelFlags.z, SystemChannelFlags(y=True) | SystemChannelFlags.z

Returns a SystemChannelFlags instance with all provided flags enabled.

~SystemChannelFlags.y

Returns a SystemChannelFlags instance with all flags except y inverted from their default value.

value

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

Type:

int

join_notifications

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

Type:

bool

premium_subscriptions

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

Type:

bool

guild_reminder_notifications

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

New in version 2.0.

Type:

bool

join_notification_replies

Returns True if the system channel shows sticker reply buttons for member join notifications.

New in version 2.3.

Type:

bool

role_subscription_purchase_notifications

Returns True if the system channel shows role subscription purchase/renewal notifications.

New in version 2.9.

Type:

bool

role_subscription_purchase_notification_replies

Returns True if the system channel shows sticker reply buttons for role subscription purchase/renewal notifications.

New in version 2.9.

Type:

bool

WelcomeScreenChannel

Attributes
class disnake.WelcomeScreenChannel[source]

Represents a Discord welcome screen channel.

New in version 2.5.

id

The ID of the guild channel this welcome screen channel represents.

Type:

int

description

The description of this channel in the official UI.

Type:

str

emoji

The emoji associated with this channel’s welcome message, if any.

Type:

Optional[Union[Emoji, PartialEmoji]]

GuildBuilder

Attributes
Methods
class disnake.GuildBuilder[source]

A guild builder object, created by Client.guild_builder().

This allows for easier configuration of more complex guild setups, abstracting away some of the quirks of the guild creation endpoint.

New in version 2.8.

Note

Many methods of this class return unspecified placeholder IDs (called PlaceholderID below) that can be used to reference the created object in other objects, for example referencing a category when creating a new text channel, or a role when setting permission overwrites.

Examples

Basic usage:

builder = client.guild_builder("Cat Pics")
builder.add_text_channel("meow", topic="cat.")
guild = await builder.create()

Adding more channels + roles:

builder = client.guild_builder("More Cat Pics")
builder.add_text_channel("welcome")

# add roles
guests = builder.add_role("guests")
admins = builder.add_role(
    "catmins",
    permissions=Permissions(administrator=True),
    hoist=True,
)

# add cat-egory and text channel
category = builder.add_category("cats!")
meow_channel = builder.add_text_channel(
    "meow",
    topic="cat.",
    category=category,
    overwrites={guests: PermissionOverwrite(send_messages=False)}
)

# set as system channel
builder.system_channel = meow_channel

# add hidden voice channel
builder.add_voice_channel(
    "secret-admin-vc",
    category=category,
    overwrites={builder.everyone: PermissionOverwrite(view_channel=False)}
)

# finally, create the guild
guild = await builder.create()
name

The name of the new guild.

Type:

str

icon

The icon of the new guild.

Type:

Optional[Union[bytes, Asset, Emoji, PartialEmoji, StickerItem, Sticker]]

verification_level

The verification level of the new guild.

Type:

Optional[VerificationLevel]

default_notifications

The default notification level for the new guild.

Type:

Optional[NotificationLevel]

explicit_content_filter

The explicit content filter for the new guild.

Type:

Optional[ContentFilter]

afk_channel

The channel that is used as the AFK channel.

Type:

Optional[PlaceholderID]

afk_timeout

The number of seconds until someone is moved to the AFK channel.

Type:

Optional[int]

system_channel

The channel that is used as the system channel.

Type:

Optional[PlaceholderID]

system_channel_flags

The settings to use with the system channel.

Type:

Optional[SystemChannelFlags]

property everyone[source]

The placeholder ID used for the @everyone role.

Type:

PlaceholderID

await create()[source]

This function is a coroutine.

Creates the configured guild.

Raises:
Returns:

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

Note

Due to API limitations, this returned guild does not contain any of the configured channels.

Return type:

Guild

update_everyone_role(*, permissions=...)[source]

Updates attributes of the @everyone role.

Parameters:

permissions (Permissions) – The permissions the role should have.

Returns:

The placeholder ID for the @everyone role. Also available as everyone.

Return type:

PlaceholderID

add_role(name=..., *, permissions=..., color=..., colour=..., hoist=..., mentionable=...)[source]

Adds a role to the guild builder.

The default (@everyone) role can be referenced using everyone and configured through update_everyone_role().

Parameters:

  • name (str) – The role name. Defaults to ‘new role’.

  • permissions (Permissions) – The permissions the role should 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) – Whether the role should be shown separately in the member list. Defaults to False.

  • mentionable (bool) – Whether the role should be mentionable by others. Defaults to False.

Returns:

A placeholder ID for the created role.

Return type:

PlaceholderID

add_category(name, *, overwrites=...)[source]

Adds a category channel to the guild builder.

There is an alias for this named add_category_channel.

Parameters:
Returns:

A placeholder ID for the created category.

Return type:

PlaceholderID

add_text_channel(name, *, overwrites=..., category=..., topic=..., slowmode_delay=..., nsfw=..., default_auto_archive_duration=...)[source]

Adds a text channel to the guild builder.

Parameters:

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

  • overwrites (Dict[PlaceholderID, PermissionOverwrite]) – A dict of roles to PermissionOverwrites to apply to the channel.

  • category (PlaceholderID) –

    The category to place the new channel under.

    Warning

    Unlike Guild.create_text_channel(), the parent category’s permissions will not be synced to this new channel by default.

  • topic (Optional[str]) – The channel’s topic.

  • slowmode_delay (int) – Specifies the slowmode rate limit for users in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600. If not provided, slowmode is disabled.

  • nsfw (bool) – Whether to mark the channel as NSFW.

  • default_auto_archive_duration (Union[int, ThreadArchiveDuration]) – The default auto archive duration in minutes for threads created in this channel. Must be one of 60, 1440, 4320, or 10080.

Returns:

A placeholder ID for the created text channel.

Return type:

PlaceholderID

add_voice_channel(name, *, overwrites=..., category=..., slowmode_delay=..., nsfw=..., bitrate=..., user_limit=..., rtc_region=..., video_quality_mode=...)[source]

Adds a voice channel to the guild builder.

Parameters:

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

  • overwrites (Dict[PlaceholderID, PermissionOverwrite]) – A dict of roles to PermissionOverwrites to apply to the channel.

  • category (PlaceholderID) –

    The category to place the new channel under.

    Warning

    Unlike Guild.create_voice_channel(), the parent category’s permissions will not be synced to this new channel by default.

  • slowmode_delay (int) – Specifies the slowmode rate limit for users in this channel, in seconds. A value of 0 disables slowmode. The maximum value possible is 21600. If not provided, slowmode is disabled.

  • nsfw (bool) – Whether to mark the channel as NSFW.

  • 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[Union[str, VoiceRegion]]) – The region for the voice channel’s voice communication. A value of None indicates automatic voice region detection.

  • video_quality_mode (VideoQualityMode) – The camera video quality for the voice channel’s participants.

Returns:

A placeholder ID for the created voice channel.

Return type:

PlaceholderID

Enumerations

VerificationLevel

class disnake.VerificationLevel[source]

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.

NotificationLevel

class disnake.NotificationLevel[source]

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

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.

ContentFilter

class disnake.ContentFilter[source]

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

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.

NSFWLevel

class disnake.NSFWLevel[source]

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.

OnboardingPromptType

class disnake.OnboardingPromptType[source]

Represents the type of onboarding prompt.

New in version 2.9.

multiple_choice

The prompt is a multiple choice prompt.

dropdown

The prompt is a dropdown prompt.

Events