Guild

discord_http.guild module

class discord_http.guild.BanEntry(user, reason)

Bases: NamedTuple

Represents a ban entry for a guild member.

Parameters:
user: User

Alias for field number 0

reason: str | None

Alias for field number 1

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class discord_http.guild.Guild(*, state, data, populate_cache=True)

Bases: PartialGuild

Represents a guild (server) in Discord.

Parameters:
async ban(member, *, delete_message_days=0, delete_message_seconds=0, reason=None) → None

Ban a member from the server.

Parameters:

  • member (Member | PartialMember | int) – The member to ban

  • reason (str | None) – The reason for banning the member

  • delete_message_days (int | None) – How many days of messages to delete

  • delete_message_seconds (int | None) – How many seconds of messages to delete

Return type:

None

async begin_guild_prune(*, days=7, compute_prune_count=True, include_roles=None, reason=None) → int | None

Begin a guild prune.

Parameters:

  • days (int | None) – How many days of inactivity to prune for

  • compute_prune_count (bool) – Whether to return the amount of members that would be pruned

  • include_roles (list[Role | PartialRole | int] | None) – Which roles to include in the prune

  • reason (str | None) – The reason for beginning the prune

Return type:

int | None

Returns:

The amount of members that were pruned

async bulk_ban(*members, delete_message_days=0, delete_message_seconds=0, reason=None) → list[PartialMember]

Ban multiple members from the server.

Parameters:

  • *members (Member | PartialMember | int) – The members to ban

  • delete_message_days (int | None) – How many days of messages to delete

  • delete_message_seconds (int | None) – How many seconds of messages to delete

  • reason (str | None) – The reason for banning the members

Return type:

list[PartialMember]

Returns:

The banned members

property categories: list[CategoryChannel]

A list of all the category channels in the guild if they are cached.

property channels: list[BaseChannel | PartialChannel]

A list of all the channels in the guild if they are cached.

property chunked: bool

Whether the guild is chunked or not.

async create_automod_rule(name, *, event_type, trigger_type, keyword_filter=None, regex_patterns=None, presets=None, allow_list=None, mention_total_limit=None, mention_raid_protection_enabled=False, alert_channel=None, timeout_seconds=None, message=None, enabled=True, exempt_roles=None, exempt_channels=None, reason=None) → AutoModRule

Create an automod rule.

Parameters:

  • name (str) – Name of the automod

  • event_type (AutoModRuleEventType | int) – What type of event

  • trigger_type (AutoModRuleTriggerType | int) – What should make it get triggered

  • keyword_filter (list[str] | None) – Keywords to filter

  • regex_patterns (list[str] | None) – Keywords in regex pattern to filter

  • presets (list[AutoModRulePresetType] | None) – Automod presets to include

  • allow_list (list[str] | None) – List of keywords that are allowed

  • mention_total_limit (int | None) – How many unique mentions allowed before trigger

  • mention_raid_protection_enabled (bool) – If this should apply for raids

  • alert_channel (Snowflake | int | None) – Where the action should be logged

  • timeout_seconds (int | None) – How many seconds the user in question should be timed out

  • message (str | None) – What message the user gets when action is taken

  • enabled (bool) – If the automod should be enabled or not

  • exempt_roles (list[Snowflake | int] | None) – Which roles are allowed to bypass

  • exempt_channels (list[Snowflake | int] | None) – Which channels are allowed to bypass

  • reason (str | None) – Reason for creating the automod

Return type:

AutoModRule

Returns:

The automod that was just created

async create_category(name, *, overwrites=None, position=None, reason=None) → CategoryChannel

Create a category channel.

Parameters:

  • name (str) – The name of the category

  • overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category

  • position (int | None) – The position of the category

  • reason (str | None) – The reason for creating the category

Return type:

CategoryChannel

Returns:

The created category

async create_emoji(name, *, image, reason=None) → Emoji

Create an emoji.

Parameters:

  • name (str) – Name of the emoji

  • image (File | bytes) – File object to create an emoji from

  • reason (str | None) – The reason for creating the emoji

Return type:

Emoji

Returns:

The created emoji

async create_role(name, *, permissions=None, color=None, colour=None, unicode_emoji=None, icon=None, hoist=False, mentionable=False, reason=None) → Role

Create a role.

Parameters:

  • name (str) – The name of the role

  • permissions (Permissions | None) – The permissions of the role

  • color (tuple[Colour | int, ...] | Colour | Color | int | None) – Alias for colour

  • colour (tuple[Colour | int, ...] | Colour | Color | int | None) – The colour of the role. If tuple is provided, it switches to the new gradient role colours. The third value must be one of the following: - 16761760 - 11127295 - 16759788

  • hoist (bool) – Whether the role should be hoisted

  • mentionable (bool) – Whether the role should be mentionable

  • unicode_emoji (str | None) – The unicode emoji of the role

  • icon (File | bytes | None) – The icon of the role

  • reason (str | None) – The reason for creating the role

Return type:

Role

Returns:

The created role

async create_scheduled_event(name, *, start_time, end_time=None, channel=None, description=None, privacy_level=None, entity_type=None, external_location=None, image=None, recurrence_rule=None, reason=None) → ScheduledEvent

Create a scheduled event.

Parameters:
Return type:

ScheduledEvent

Returns:

The created event

async create_soundboard_sound(name, *, sound, volume=None, emoji_id=None, emoji_name=None, reason=None) → SoundboardSound

Create a soundboard sound.

Parameters:

  • name (str) – Name of the soundboard sound

  • sound (File | bytes) – File object to create a soundboard sound from

  • volume (int | None) – The volume of the soundboard sound

  • emoji_name (str | None) – The unicode emoji of the soundboard sound

  • emoji_id (str | None) – The ID of the custom emoji of the soundboard sound

  • reason (str | None) – The reason for creating the soundboard sound

Return type:

SoundboardSound

Returns:

The created soundboard sound

Raises:

ValueError – If both emoji_name and emoji_id are set

async create_stage_channel(name, *, bitrate=None, user_limit=None, overwrites=None, position=None, parent_id=None, video_quality_mode=None, reason=None) → StageChannel

Create a stage channel.

Parameters:

  • name (str) – The name of the channel

  • bitrate (int | None) – The bitrate of the channel

  • user_limit (int | None) – The user limit of the channel

  • overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category

  • position (int | None) – The position of the channel

  • video_quality_mode (VideoQualityType | int | None) – The video quality mode of the channel

  • parent_id (Snowflake | int | None) – The Category ID where the channel will be placed

  • reason (str | None) – The reason for creating the stage channel

Return type:

StageChannel

Returns:

The created channel

async create_sticker(name, *, description, emoji, file, reason=None) → Sticker

Create a sticker.

Parameters:

  • name (str) – Name of the sticker

  • description (str) – Description of the sticker

  • emoji (str) – Emoji that represents the sticker

  • file (File) – File object to create a sticker from

  • reason (str | None) – The reason for creating the sticker

Return type:

Sticker

Returns:

The created sticker

async create_template(name, *, description=None) → GuildTemplate

Creates a template based on the guild’s current state.

Requires the MANAGE_GUILD permission.

Parameters:

  • name (str) – The name of the template (1-100 characters)

  • description (str | None) – The description of the template, if any (0-120 characters)

Return type:

GuildTemplate

Returns:

The created template

async create_text_channel(name, *, topic=None, position=None, rate_limit_per_user=None, overwrites=None, parent_id=None, nsfw=None, reason=None) → TextChannel

Create a text channel.

Parameters:

  • name (str) – The name of the channel

  • topic (str | None) – The topic of the channel

  • position (int | None) – The position of the channel

  • rate_limit_per_user (int | None) – The rate limit per user of the channel

  • overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category

  • parent_id (Snowflake | int | None) – The Category ID where the channel will be placed

  • nsfw (bool | None) – Whether the channel is NSFW or not

  • reason (str | None) – The reason for creating the text channel

Return type:

TextChannel

Returns:

The created channel

async create_voice_channel(name, *, bitrate=None, user_limit=None, rate_limit_per_user=None, overwrites=None, position=None, video_quality_mode=None, parent_id=None, nsfw=None, reason=None) → VoiceChannel

Create a voice channel.

Parameters:

  • name (str) – The name of the channel

  • bitrate (int | None) – The bitrate of the channel

  • user_limit (int | None) – The user limit of the channel

  • rate_limit_per_user (int | None) – The rate limit per user of the channel

  • overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category

  • position (int | None) – The position of the channel

  • video_quality_mode (VideoQualityType | int | None) – The video quality mode of the channel

  • parent_id (Snowflake | int | None) – The Category ID where the channel will be placed

  • nsfw (bool | None) – Whether the channel is NSFW or not

  • reason (str | None) – The reason for creating the voice channel

Return type:

VoiceChannel

Returns:

The created channel

property created_at: datetime

The datetime of the snowflake.

async delete() → None

Delete the guild (the bot must own the server).

Return type:

None

async edit(*, name=<MISSING>, verification_level=<MISSING>, default_message_notifications=<MISSING>, explicit_content_filter=<MISSING>, afk_channel_id=<MISSING>, afk_timeout=<MISSING>, icon=<MISSING>, owner_id=<MISSING>, splash=<MISSING>, discovery_splash=<MISSING>, banner=<MISSING>, system_channel_id=<MISSING>, system_channel_flags=<MISSING>, rules_channel_id=<MISSING>, public_updates_channel_id=<MISSING>, preferred_locale=<MISSING>, description=<MISSING>, features=<MISSING>, premium_progress_bar_enabled=<MISSING>, safety_alerts_channel_id=<MISSING>, reason=None) → PartialGuild

Edit the guild.

Parameters:
Return type:

PartialGuild

Returns:

The edited guild

async edit_incident_actions(*, invites_disabled_until=<MISSING>, dms_disabled_until=<MISSING>) → GuildIncidentsData

Edits the guild’s security incident actions.

Requires the MANAGE_GUILD permission.

Parameters:

  • invites_disabled_until (datetime | timedelta | int | None) – When invites should be re-enabled, or None to re-enable them immediately. Can only be up to 24 hours in the future.

  • dms_disabled_until (datetime | timedelta | int | None) – When direct messages should be re-enabled, or None to re-enable them immediately. Can only be up to 24 hours in the future.

Return type:

GuildIncidentsData

Returns:

The updated security incident actions

async edit_onboarding(*, prompts=<MISSING>, default_channel_ids=<MISSING>, enabled=<MISSING>, mode=<MISSING>, reason=None) → GuildOnboarding

Edits the guild’s onboarding configuration.

Requires the MANAGE_GUILD and MANAGE_ROLES permissions.

Parameters:

  • prompts (list[OnboardingPrompt] | None) – New prompts shown during onboarding and in the Channels & Roles tab

  • default_channel_ids (list[Snowflake | int] | None) – New channel IDs that members get opted into automatically

  • enabled (bool | None) – Whether onboarding should be enabled

  • mode (OnboardingMode | int | None) – New constraint mode used for onboarding

  • reason (str | None) – The reason for editing the onboarding configuration

Return type:

GuildOnboarding

Returns:

The edited onboarding configuration

async edit_welcome_screen(*, enabled=<MISSING>, description=<MISSING>, welcome_channels=<MISSING>, reason=None) → WelcomeScreen

Edits the guild’s welcome screen.

Requires the MANAGE_GUILD permission.

Parameters:

  • enabled (bool | None) – Whether the welcome screen is enabled

  • description (str | None) – New description of the welcome screen

  • welcome_channels (list[WelcomeScreenChannel] | None) – New channels shown in the welcome screen (max 5)

  • reason (str | None) – The reason for editing the welcome screen

Return type:

WelcomeScreen

Returns:

The edited welcome screen

async edit_widget(*, enabled=<MISSING>, channel=<MISSING>, reason=None) → GuildWidgetSettings

Edits the guild’s widget settings.

Requires the MANAGE_GUILD permission.

Parameters:
Return type:

GuildWidgetSettings

Returns:

The edited widget settings

property emojis: list[Emoji | PartialEmoji]

A list of all the emojis in the guild if they are cached.

async fetch(*, with_counts=False) → Guild

Fetches more information about the guild.

Parameters:

with_counts (bool) – Whether to include approximate_member_count and approximate_presence_count or not

Return type:

Guild

Returns:

The guild object

async fetch_audit_logs(*, before=None, after=None, user=None, action=None, limit=100) → AsyncIterator[AuditLogEntry]

Fetches the audit logs for the guild.

Parameters:
Return type:

AsyncIterator[AuditLogEntry]

Returns:

The audit logs for the guild

async fetch_automod_rule(automod_id) → AutoModRule

Fetches a automod rule from the guild.

Return type:

AutoModRule

Parameters:

automod_id (int)

async fetch_automod_rules() → list[AutoModRule]

Fetches all the automod rules in the guild.

Return type:

list[AutoModRule]

async fetch_ban(user) → BanEntry

Fetches a user’s ban of the guild.

Parameters:

user (Snowflake | int) – The user to fetch the ban of

Return type:

BanEntry

Returns:

Ban entry that was found

async fetch_bans(*, before=None, after=None, limit=1000) → AsyncIterator[BanEntry]

Fetch the bans of the guild.

Parameters:

  • before (Snowflake | int | None) – Consider only users before given user id

  • after (Snowflake | int | None) – Consider only users after given user id

  • limit (int | None) – The maximum amount of messages to fetch. None will fetch all users.

Yields:

The message object

Return type:

AsyncIterator[BanEntry]

async fetch_channel(channel_id) → BaseChannel

Fetch a channel from the guild.

Parameters:

channel_id (int) – The ID of the channel

Return type:

BaseChannel

Returns:

The channel object

async fetch_channels() → list[type[BaseChannel]]

Fetches all the channels in the guild.

Return type:

list[type[BaseChannel]]

async fetch_emoji(emoji_id) → Emoji

Fetches an emoji from the guild.

Return type:

Emoji

Parameters:

emoji_id (int)

async fetch_emojis() → list[Emoji]

Fetches all the emojis in the guild.

Return type:

list[Emoji]

async fetch_guild_prune_count(*, days=7, include_roles=None) → int

Fetch the amount of members that would be pruned.

Parameters:
Return type:

int

Returns:

The amount of members that would be pruned

async fetch_integrations() → list[Integration]

Fetches the integrations for the guild.

This requires the MANAGE_GUILD permission.

Return type:

list[Integration]

Returns:

The integrations in the guild.

async fetch_invites() → list[Invite]

Fetches all the invites for the guild.

Return type:

list[Invite]

async fetch_member(member_id) → Member

Fetch a member from the guild.

Parameters:

member_id (int) – The ID of the member

Return type:

Member

Returns:

The member object

async fetch_members(*, limit=1000, after=None) → AsyncIterator[Member]

Fetches all the members in the guild.

Parameters:

  • limit (int | None) – The maximum amount of members to return

  • after (Snowflake | int | None) – The member to start after

Yields:

The members in the guild

Return type:

AsyncIterator[Member]

async fetch_onboarding() → GuildOnboarding

Fetches the guild’s onboarding configuration.

Return type:

GuildOnboarding

async fetch_preview() → GuildPreview

Fetches a preview of the guild, including for guilds the bot may not be in if discoverable.

Return type:

GuildPreview

async fetch_public_threads() → list[PublicThread]

Fetches all the public threads in the guild.

Return type:

list[PublicThread]

Returns:

The public threads in the guild

async fetch_regions() → list[VoiceRegion]

Fetches all the voice regions for the guild.

Return type:

list[VoiceRegion]

async fetch_roles() → list[Role]

Fetches all the roles in the guild.

Return type:

list[Role]

async fetch_scheduled_event(id) → ScheduledEvent

Fetches a scheduled event object.

Parameters:

id (int) – The ID of the scheduled event.

Return type:

ScheduledEvent

Returns:

The scheduled event object.

async fetch_scheduled_events_list() → list[ScheduledEvent]

Fetches all the scheduled events in the guild.

Return type:

list[ScheduledEvent]

async fetch_soundboard_sound(sound_id) → SoundboardSound

Fetches a soundboard sound from the guild.

Return type:

SoundboardSound

Parameters:

sound_id (int)

async fetch_soundboard_sounds() → list[SoundboardSound]

Fetches all the soundboard sounds in the guild.

Return type:

list[SoundboardSound]

async fetch_sticker(sticker_id) → Sticker

Fetch a sticker from the guild.

Parameters:

sticker_id (int) – The ID of the sticker

Return type:

Sticker

Returns:

The sticker object

async fetch_stickers() → list[Sticker]

Fetches all the stickers in the guild.

Return type:

list[Sticker]

async fetch_templates() → list[GuildTemplate]

Fetches the templates for the guild. Requires the MANAGE_GUILD permission.

Return type:

list[GuildTemplate]

async fetch_welcome_screen() → WelcomeScreen

Fetches the guild’s welcome screen.

Return type:

WelcomeScreen

async fetch_widget() → GuildWidget

Fetches the guild’s public widget. Requires no permissions or authentication.

Return type:

GuildWidget

async fetch_widget_settings() → GuildWidgetSettings

Fetches the guild’s widget settings. Requires the MANAGE_GUILD permission.

Return type:

GuildWidgetSettings

get_channel(channel_id) → BaseChannel | PartialChannel | None

Returns the channel from cache if it exists.

Parameters:

channel_id (int) – The ID of the channel to get.

Return type:

BaseChannel | PartialChannel | None

Returns:

The channel with the given ID, if it exists.

get_channel_voice_states(channel_id) → list[VoiceState | PartialVoiceState]

Returns the voice state of a channel.

Parameters:

channel_id (int) – The ID of the channel to get the voice state of.

Return type:

list[VoiceState | PartialVoiceState]

Returns:

The voice state of the channel

get_member(member_id) → Member | PartialMember | None

Returns the member from cache if it exists.

Parameters:

member_id (int) – The ID of the member to get.

Return type:

Member | PartialMember | None

Returns:

The member with the given ID, if it exists.

get_member_voice_state(member_id) → VoiceState | PartialVoiceState | None

Returns the voice state of a member from cache if it exists.

Parameters:

member_id (int) – The ID of the member to get the voice state of.

Return type:

VoiceState | PartialVoiceState | None

Returns:

The voice state of the member, if it exists.

get_partial_automod_rule(automod_id) → PartialAutoModRule

Returns a partial automod rule object.

Return type:

PartialAutoModRule

Parameters:

automod_id (int)

get_partial_channel(channel_id) → PartialChannel

Get a partial channel object.

Parameters:

channel_id (int) – The ID of the channel

Return type:

PartialChannel

Returns:

The partial channel object

get_partial_emoji(emoji_id) → PartialEmoji

Get a partial emoji object.

Parameters:

emoji_id (int) – The ID of the emoji

Return type:

PartialEmoji

Returns:

The partial emoji object

get_partial_member(member_id) → PartialMember

Get a partial member object.

Parameters:

member_id (int) – The ID of the member

Return type:

PartialMember

Returns:

The partial member object

get_partial_role(role_id) → PartialRole

Get a partial role object.

Parameters:

role_id (int) – The ID of the role

Return type:

PartialRole

Returns:

The partial role object

get_partial_scheduled_event(id) → PartialScheduledEvent

Creates a partial scheduled event object.

Parameters:

id (int) – The ID of the scheduled event.

Return type:

PartialScheduledEvent

Returns:

The partial scheduled event object.

get_partial_soundboard_sound(sound_id) → PartialSoundboardSound

Get a partial soundboard sound object.

Parameters:

sound_id (int) – The ID of the sound

Return type:

PartialSoundboardSound

Returns:

The partial soundboard sound object

get_partial_sticker(sticker_id) → PartialSticker

Get a partial sticker object.

Parameters:

sticker_id (int) – The ID of the sticker

Return type:

PartialSticker

Returns:

The partial sticker object

get_partial_template(code) → PartialGuildTemplate

Creates a partial template object under this guild, without fetching it.

Return type:

PartialGuildTemplate

Parameters:

code (str)

get_soundboard_sound(sound_id) → SoundboardSound | PartialSoundboardSound | None

Returns the soundboard sound from cache if it exists.

Parameters:

sound_id (int) – The ID of the soundboard sound to get.

Return type:

SoundboardSound | PartialSoundboardSound | None

Returns:

The soundboard sound with the given ID, if it exists.

get_thread(thread_id) → BaseChannel | PartialChannel | None

Returns the thread from cache if it exists.

Parameters:

thread_id (int) – The ID of the thread to get.

Return type:

BaseChannel | PartialChannel | None

Returns:

The thread with the given ID, if it exists.

get_voice_states() → list[VoiceState | PartialVoiceState]

Returns the voice state of the guild.

Return type:

list[VoiceState | PartialVoiceState]

id: int

The ID of the snowflake.

async kick(member, *, reason=None) → None

Kick a member from the server.

Parameters:
Return type:

None

property large: bool

Whether the guild is considered large.

async leave() → None

Leave the guild.

Return type:

None

property me: Member | PartialMember | None

The bot’s member object.

Only useable if you are using gateway and caching

member_count: int | None

The number of members in the guild, if available.

property members: list[Member | PartialMember]

A list of all the members in the guild if they are cached.

property roles: list[Role | PartialRole]

A list of all the roles in the guild if they are cached or if the guild was fetched.

async search_members(query, *, limit=100) → list[Member]

Search for members in the guild.

Parameters:

  • query (str) – The query to search for

  • limit (int | None) – The maximum amount of members to return

Return type:

list[Member]

Returns:

The members that matched the query

Raises:

ValueError – If the limit is not between 1 and 1000

async search_messages(*, query=None, limit=25, offset=0, max_id=None, min_id=None, slop=None, channel_id=None, author_type=None, author_id=None, mentions=None, mentions_role_id=None, mention_everyone=None, replied_to_user_id=None, replied_to_message_id=None, pinned=None, has=None, embed_type=None, embed_provider=None, link_hostname=None, attachment_filename=None, attachment_extension=None, sort_by='timestamp', sort_order='desc', include_nsfw=None) → AsyncIterator[Message]

Search for messages within the guild.

Parameters:

  • query (str | None) – The content to search for (max 1024 characters).

  • limit (int | None) – The maximum amount of messages to yield.

  • offset (int) – Number of messages to skip (max 9975).

  • max_id (Snowflake | int | None) – Get messages before this message ID.

  • min_id (Snowflake | int | None) – Get messages after this message ID.

  • slop (int | None) – The max number of words to skip between matching tokens in the search (default 2, max 100).

  • channel_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages by these channels (max 500).

  • author_type (Union[list[Literal['user', 'bot', 'webhook', '-user', '-bot', '-webhook']], Literal['user', 'bot', 'webhook', '-user', '-bot', '-webhook'], None]) – Filter messages by author type (e.g. ‘user’, ‘bot’, ‘webhook’). Negate with ‘-‘.

  • author_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages by these authors (max 100).

  • mentions (list[Snowflake | int] | Snowflake | int | None) – Filter messages that mention these users (max 100).

  • mentions_role_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages that mention these roles (max 100).

  • mention_everyone (bool | None) – Filter messages that do or do not mention @everyone.

  • replied_to_user_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages that reply to these users (max 100).

  • replied_to_message_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages that reply to these messages (max 100).

  • pinned (bool | None) – Filter messages by whether they are or are not pinned.

  • has (Union[list[Literal['image', 'sound', 'video', 'file', 'sticker', 'embed', 'link', 'poll', 'snapshot', '-image', '-sound', '-video', '-file', '-sticker', '-embed', '-link', '-poll', '-snapshot']], Literal['image', 'sound', 'video', 'file', 'sticker', 'embed', 'link', 'poll', 'snapshot', '-image', '-sound', '-video', '-file', '-sticker', '-embed', '-link', '-poll', '-snapshot'], None]) – Filter messages by whether or not they have specific things (e.g. ‘image’, ‘embed’).

  • embed_type (Union[list[Literal['image', 'video', 'gif', 'sound', 'article']], Literal['image', 'video', 'gif', 'sound', 'article'], None]) – Filter messages by embed type (e.g. ‘image’, ‘video’).

  • embed_provider (list[str] | str | None) – Filter messages by embed provider (case-sensitive, e.g. ‘Tenor’) (max 100).

  • link_hostname (list[str] | str | None) – Filter messages by link hostname (e.g. ‘discord.com’) (max 100).

  • attachment_filename (list[str] | str | None) – Filter messages by attachment filename (max 100).

  • attachment_extension (list[str] | str | None) – Filter messages by attachment extension (e.g. ‘txt’) (max 100).

  • sort_by (Literal['timestamp', 'relevance']) – The sorting algorithm to use (“timestamp” or “relevance”).

  • sort_order (Literal['asc', 'desc']) – The direction to sort (“asc” or “desc”).

  • include_nsfw (bool | None) – Whether to include results from age-restricted channels (default False).

Yields:

The message object matching the search.

Return type:

AsyncIterator[Message]

property soundboard_sounds: list[SoundboardSound | PartialSoundboardSound]

A list of all the soundboard sounds in the guild if they are cached.

property stickers: list[Sticker | PartialSticker]

A list of all the stickers in the guild if they are cached.

property text_channels: list[TextChannel]

A list of all the text channels in the guild if they are cached.

property threads: list[BaseChannel | PartialChannel]

A list of all the threads in the guild if they are cached.

unavailable: bool

Whether the guild is unavailable or not. This can be true during outages or when the bot is not a member of the guild.

async unban(member, *, reason=None) → None

Unban a member from the server.

Parameters:
Return type:

None

property voice_channels: list[VoiceChannel]

A list of all the voice channels in the guild if they are cached.

widget_image_url(*, style='shield') → str

Returns the URL for the guild’s widget image (PNG).

Requires no permissions or authentication to access.

Parameters:

style (str) – The style of the widget image (shield, banner1, banner2, banner3, or banner4)

Return type:

str

Returns:

The URL for the widget image

afk_channel_id: int | None

The ID of the AFK channel, if any.

afk_timeout: int

The AFK timeout in seconds.

application_id: int | None

The ID of the application that created the guild, if bot-created.

approximate_member_count: int | None

The approximate number of members in the guild, only available when fetched with with_counts.

approximate_presence_count: int | None

The approximate number of non-offline members in the guild, only available when fetched with with_counts.

default_message_notifications: int

The default message notification level of the guild.

description: str | None

The description of the guild.

explicit_content_filter: int

The explicit content filter level of the guild.

features: tuple[str, ...]

The features of the guild.

latest_onboarding_question_id: int | None

The ID of the latest onboarding question, if any.

max_members: int

The maximum number of members in the guild.

max_stage_video_channel_users: int

The maximum number of users in a stage video channel.

max_video_channel_users: int

The maximum number of users in a video channel.

mfa_level: MFALevel

The MFA level of the guild.

name: str

The name of the guild.

nsfw: bool

Whether the guild is marked as NSFW.

nsfw_level: NSFWLevel

The NSFW level of the guild.

owner_id: int | None

The ID of the owner of the guild, if any.

preferred_locale: str | None

The preferred locale of the guild.

premium_progress_bar_enabled: bool

Whether the premium progress bar is enabled.

premium_subscription_count: int

The number of premium subscriptions in the guild.

premium_tier: PremiumTier

The premium tier of the guild.

public_updates_channel_id: int | None

The ID of the public updates channel, if any.

region: str | None

The voice region of the guild, if any.

safety_alerts_channel_id: int | None

The ID of the safety alerts channel, if any.

system_channel_flags: int

The system channel flags of the guild.

system_channel_id: int | None

The ID of the system channel, if any.

vanity_url_code: str | None

The vanity URL code of the guild, if any.

verification_level: VerificationLevel

The verification level of the guild.

widget_channel_id: int | None

The ID of the widget channel, if any.

widget_enabled: bool

Whether the widget is enabled for the guild.

incidents_data: GuildIncidentsData | None

The security incident actions taken on the guild, if any.

welcome_screen: WelcomeScreen | None

The welcome screen of the guild, if it’s a Community guild and this was returned in an Invite’s guild object.

property owner: Member | PartialMember | None

The owner of the guild, if any.

property afk_channel: BaseChannel | PartialChannel | None

The AFK channel of the guild, if any.

property system_channel: BaseChannel | PartialChannel | None

The system channel of the guild, if any.

property public_updates_channel: BaseChannel | PartialChannel | None

The public updates channel of the guild, if any.

property safety_alerts_channel: BaseChannel | PartialChannel | None

The safety alerts channel of the guild, if any.

property widget_channel: BaseChannel | PartialChannel | None

The widget channel of the guild, if any.

property emojis_limit: int

The maximum amount of emojis the guild can have.

property stickers_limit: int

The maximum amount of stickers the guild can have.

property bitrate_limit: int

The maximum bitrate the guild can have.

property filesize_limit: int

The maximum filesize the guild can have.

property icon: Asset | None

The guild’s icon.

property banner: Asset | None

The guild’s banner.

property splash: Asset | None

The guild’s invite splash.

property discovery_splash: Asset | None

The guild’s discovery splash, only present for guilds with the DISCOVERABLE feature.

property default_role: Role

The guild’s default role, which is always provided.

property premium_subscriber_role: Role | None

The guild’s premium subscriber role if available.

property self_role: Role | None

The guild’s bot role if available.

get_role(role_id) → Role | None

Get a role from the guild.

This simply returns the role from the role list in this object if it exists

Parameters:

role_id (int) – The ID of the role to get

Return type:

Role | None

Returns:

The role with the given ID, if it exists.

get_role_by_name(role_name) → Role | None

Gets the first role with the specified name.

Parameters:

role_name (str) – The name of the role to get (case sensitive)

Return type:

Role | None

Returns:

The role with the given name, if it exists.

get_member_top_role(member) → Role | None

Get the top role of a member, because Discord API does not order roles.

Parameters:

member (Member) – The member to get the top role of

Return type:

Role | None

Returns:

The top role of the member

class discord_http.guild.GuildIncidentsData(invites_disabled_until, dms_disabled_until, dm_spam_detected_at, raid_detected_at)

Bases: NamedTuple

Represents the security incident actions taken on a guild.

Parameters:
invites_disabled_until: datetime | None

Alias for field number 0

dms_disabled_until: datetime | None

Alias for field number 1

dm_spam_detected_at: datetime | None

Alias for field number 2

raid_detected_at: datetime | None

Alias for field number 3

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class discord_http.guild.GuildOnboarding(*, state, data)

Bases: object

Represents a guild’s onboarding configuration.

Parameters:
guild_id: int

The ID of the guild this onboarding is part of.

prompts: list[OnboardingPrompt]

The prompts shown during onboarding and in the Channels & Roles tab.

default_channel_ids: list[int]

The channel IDs that members get opted into automatically.

enabled: bool

Whether onboarding is enabled in the guild.

mode: OnboardingMode

The constraint mode used for onboarding.

class discord_http.guild.GuildPreview(*, state, data)

Bases: PartialBase

Represents a preview of a guild, including ones the bot may not be in.

Parameters:
name: str

The name of the guild.

features: list[str]

The features of the guild.

approximate_member_count: int

The approximate number of members in the guild.

approximate_presence_count: int

The approximate number of online members in the guild.

description: str | None

The description of the guild, if any.

emojis: list[Emoji]

The custom emojis of the guild.

stickers: list[Sticker]

The custom stickers of the guild.

property icon: Asset | None

The guild’s icon.

property splash: Asset | None

The guild’s invite splash.

property discovery_splash: Asset | None

The guild’s discovery splash.

property created_at: datetime

The datetime of the snowflake.

id: int

The ID of the snowflake.

class discord_http.guild.GuildTemplate(*, state, data)

Bases: PartialGuildTemplate

Represents a guild template object.

Parameters:
name: str

The name of the template.

description: str | None

The description of the template, if any.

usage_count: int

The number of times this template has been used.

creator_id: int

The ID of the user who created the template.

source_guild_id: int

The ID of the guild this template is based on.

serialized_source_guild: dict

The raw guild snapshot this template contains.

This is not a real Guild object, placeholder IDs in it are given as plain integers.

is_dirty: bool

Whether the template has unsynced changes.

created_at: datetime

The time the template was created.

updated_at: datetime

The time the template was last synced to the source guild.

creator: User

The user who created the template.

property source_guild: Guild | PartialGuild

The guild this template is based on.

code: str

The code of the template.

async delete() → None

Deletes the template.

Return type:

None

async edit(*, name=<MISSING>, description=<MISSING>) → GuildTemplate

Edits the template’s metadata.

Parameters:

  • name (str | None) – New name of the template

  • description (str | None) – New description of the template

Return type:

GuildTemplate

Returns:

The edited template

async fetch() → GuildTemplate

Fetches the guild template.

Return type:

GuildTemplate

guild_id: int | None

The ID of the guild the template belongs to, if known.

async sync() → GuildTemplate

Syncs the template to the guild’s current state.

Return type:

GuildTemplate

class discord_http.guild.GuildWidget(*, state, data)

Bases: object

Represents a guild’s public widget.

Parameters:
id: int

The ID of the guild.

name: str

The name of the guild.

instant_invite: str | None

The instant invite for the guild’s widget channel, if any.

channels: list[GuildWidgetChannel]

The voice/stage channels accessible by @everyone.

members: list[GuildWidgetMember]

The anonymized members currently visible in the widget (up to 100).

presence_count: int

The number of online members in the guild.

class discord_http.guild.GuildWidgetChannel(*, state, guild_id, data)

Bases: object

Represents a channel shown in a guild’s widget.

Parameters:
name: str

The name of the channel.

position: int

The position of the channel.

guild_id: int

The guild_id of the widget.

property channel: PartialChannel

The channel shown in the widget.

channel_id
class discord_http.guild.GuildWidgetMember(id, username, status, avatar_url)

Bases: NamedTuple

Represents an anonymized member shown in a guild’s widget. This does not correspond to a real user.

Parameters:
id: int

Alias for field number 0

username: str

Alias for field number 1

status: str

Alias for field number 2

avatar_url: str

Alias for field number 3

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class discord_http.guild.GuildWidgetSettings(*, state, guild_id, data)

Bases: object

Represents a guild’s widget settings.

Parameters:
channel_id: int | None

The ID of the channel the widget invite points to, if any.

enabled: bool

Whether the widget is enabled.

guild_id: int

The ID of the guild this widget belongs to.

property channel: PartialChannel | None

The channel the widget invite points to, if any.

class discord_http.guild.OnboardingPrompt(*, state, data)

Bases: PartialBase

Represents a prompt within a guild’s onboarding flow.

Parameters:
title: str

The title of the prompt.

options: list[OnboardingPromptOption]

The options available within the prompt.

type: OnboardingPromptType

The type of the prompt.

single_select: bool

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

required: bool

Whether the prompt is required before a user completes onboarding.

in_onboarding: bool

Whether the prompt is present in the onboarding flow, rather than only the Channels & Roles tab.

to_dict() → dict

Returns a dict representation of the prompt, for creating/editing.

Return type:

dict

property created_at: datetime

The datetime of the snowflake.

id: int

The ID of the snowflake.

class discord_http.guild.OnboardingPromptOption(*, state, data)

Bases: PartialBase

Represents an option within a guild onboarding prompt.

Parameters:
title: str

The title of the option.

description: str | None

The description of the option, if any.

channel_ids: list[int]

The channel IDs a member is added to when this option is selected.

role_ids: list[int]

The role IDs assigned to a member when this option is selected.

emoji: EmojiParser | None

The emoji associated with the prompt option.

to_dict() → dict

Returns a dict representation of the option, for creating/editing.

Return type:

dict

property created_at: datetime

The datetime of the snowflake.

id: int

The ID of the snowflake.

class discord_http.guild.PartialGuild(*, state, id)

Bases: PartialBase

Represents a partial guild object.

Parameters:
unavailable: bool

Whether the guild is unavailable or not. This can be true during outages or when the bot is not a member of the guild.

member_count: int | None

The number of members in the guild, if available.

property large: bool

Whether the guild is considered large.

property chunked: bool

Whether the guild is chunked or not.

property me: Member | PartialMember | None

The bot’s member object.

Only useable if you are using gateway and caching

get_member(member_id) → Member | PartialMember | None

Returns the member from cache if it exists.

Parameters:

member_id (int) – The ID of the member to get.

Return type:

Member | PartialMember | None

Returns:

The member with the given ID, if it exists.

get_channel(channel_id) → BaseChannel | PartialChannel | None

Returns the channel from cache if it exists.

Parameters:

channel_id (int) – The ID of the channel to get.

Return type:

BaseChannel | PartialChannel | None

Returns:

The channel with the given ID, if it exists.

get_thread(thread_id) → BaseChannel | PartialChannel | None

Returns the thread from cache if it exists.

Parameters:

thread_id (int) – The ID of the thread to get.

Return type:

BaseChannel | PartialChannel | None

Returns:

The thread with the given ID, if it exists.

get_voice_states() → list[VoiceState | PartialVoiceState]

Returns the voice state of the guild.

Return type:

list[VoiceState | PartialVoiceState]

get_channel_voice_states(channel_id) → list[VoiceState | PartialVoiceState]

Returns the voice state of a channel.

Parameters:

channel_id (int) – The ID of the channel to get the voice state of.

Return type:

list[VoiceState | PartialVoiceState]

Returns:

The voice state of the channel

get_member_voice_state(member_id) → VoiceState | PartialVoiceState | None

Returns the voice state of a member from cache if it exists.

Parameters:

member_id (int) – The ID of the member to get the voice state of.

Return type:

VoiceState | PartialVoiceState | None

Returns:

The voice state of the member, if it exists.

get_role(role_id) → Role | PartialRole | None

Returns the role from cache if it exists.

Parameters:

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

Return type:

Role | PartialRole | None

Returns:

The role with the given ID, if it exists.

get_soundboard_sound(sound_id) → SoundboardSound | PartialSoundboardSound | None

Returns the soundboard sound from cache if it exists.

Parameters:

sound_id (int) – The ID of the soundboard sound to get.

Return type:

SoundboardSound | PartialSoundboardSound | None

Returns:

The soundboard sound with the given ID, if it exists.

property members: list[Member | PartialMember]

A list of all the members in the guild if they are cached.

property channels: list[BaseChannel | PartialChannel]

A list of all the channels in the guild if they are cached.

property threads: list[BaseChannel | PartialChannel]

A list of all the threads in the guild if they are cached.

property roles: list[Role | PartialRole]

A list of all the roles in the guild if they are cached or if the guild was fetched.

property emojis: list[Emoji | PartialEmoji]

A list of all the emojis in the guild if they are cached.

property soundboard_sounds: list[SoundboardSound | PartialSoundboardSound]

A list of all the soundboard sounds in the guild if they are cached.

property stickers: list[Sticker | PartialSticker]

A list of all the stickers in the guild if they are cached.

property text_channels: list[TextChannel]

A list of all the text channels in the guild if they are cached.

property voice_channels: list[VoiceChannel]

A list of all the voice channels in the guild if they are cached.

property categories: list[CategoryChannel]

A list of all the category channels in the guild if they are cached.

property default_role: PartialRole

The default role, but as a partial role object.

async leave() → None

Leave the guild.

Return type:

None

async fetch(*, with_counts=False) → Guild

Fetches more information about the guild.

Parameters:

with_counts (bool) – Whether to include approximate_member_count and approximate_presence_count or not

Return type:

Guild

Returns:

The guild object

async fetch_preview() → GuildPreview

Fetches a preview of the guild, including for guilds the bot may not be in if discoverable.

Return type:

GuildPreview

async edit_incident_actions(*, invites_disabled_until=<MISSING>, dms_disabled_until=<MISSING>) → GuildIncidentsData

Edits the guild’s security incident actions.

Requires the MANAGE_GUILD permission.

Parameters:

  • invites_disabled_until (datetime | timedelta | int | None) – When invites should be re-enabled, or None to re-enable them immediately. Can only be up to 24 hours in the future.

  • dms_disabled_until (datetime | timedelta | int | None) – When direct messages should be re-enabled, or None to re-enable them immediately. Can only be up to 24 hours in the future.

Return type:

GuildIncidentsData

Returns:

The updated security incident actions

async fetch_templates() → list[GuildTemplate]

Fetches the templates for the guild. Requires the MANAGE_GUILD permission.

Return type:

list[GuildTemplate]

async create_template(name, *, description=None) → GuildTemplate

Creates a template based on the guild’s current state.

Requires the MANAGE_GUILD permission.

Parameters:

  • name (str) – The name of the template (1-100 characters)

  • description (str | None) – The description of the template, if any (0-120 characters)

Return type:

GuildTemplate

Returns:

The created template

get_partial_template(code) → PartialGuildTemplate

Creates a partial template object under this guild, without fetching it.

Return type:

PartialGuildTemplate

Parameters:

code (str)

async fetch_welcome_screen() → WelcomeScreen

Fetches the guild’s welcome screen.

Return type:

WelcomeScreen

async edit_welcome_screen(*, enabled=<MISSING>, description=<MISSING>, welcome_channels=<MISSING>, reason=None) → WelcomeScreen

Edits the guild’s welcome screen.

Requires the MANAGE_GUILD permission.

Parameters:

  • enabled (bool | None) – Whether the welcome screen is enabled

  • description (str | None) – New description of the welcome screen

  • welcome_channels (list[WelcomeScreenChannel] | None) – New channels shown in the welcome screen (max 5)

  • reason (str | None) – The reason for editing the welcome screen

Return type:

WelcomeScreen

Returns:

The edited welcome screen

async fetch_widget_settings() → GuildWidgetSettings

Fetches the guild’s widget settings. Requires the MANAGE_GUILD permission.

Return type:

GuildWidgetSettings

async edit_widget(*, enabled=<MISSING>, channel=<MISSING>, reason=None) → GuildWidgetSettings

Edits the guild’s widget settings.

Requires the MANAGE_GUILD permission.

Parameters:
Return type:

GuildWidgetSettings

Returns:

The edited widget settings

async fetch_widget() → GuildWidget

Fetches the guild’s public widget. Requires no permissions or authentication.

Return type:

GuildWidget

widget_image_url(*, style='shield') → str

Returns the URL for the guild’s widget image (PNG).

Requires no permissions or authentication to access.

Parameters:

style (str) – The style of the widget image (shield, banner1, banner2, banner3, or banner4)

Return type:

str

Returns:

The URL for the widget image

async fetch_onboarding() → GuildOnboarding

Fetches the guild’s onboarding configuration.

Return type:

GuildOnboarding

async edit_onboarding(*, prompts=<MISSING>, default_channel_ids=<MISSING>, enabled=<MISSING>, mode=<MISSING>, reason=None) → GuildOnboarding

Edits the guild’s onboarding configuration.

Requires the MANAGE_GUILD and MANAGE_ROLES permissions.

Parameters:

  • prompts (list[OnboardingPrompt] | None) – New prompts shown during onboarding and in the Channels & Roles tab

  • default_channel_ids (list[Snowflake | int] | None) – New channel IDs that members get opted into automatically

  • enabled (bool | None) – Whether onboarding should be enabled

  • mode (OnboardingMode | int | None) – New constraint mode used for onboarding

  • reason (str | None) – The reason for editing the onboarding configuration

Return type:

GuildOnboarding

Returns:

The edited onboarding configuration

get_partial_automod_rule(automod_id) → PartialAutoModRule

Returns a partial automod rule object.

Return type:

PartialAutoModRule

Parameters:

automod_id (int)

async search_messages(*, query=None, limit=25, offset=0, max_id=None, min_id=None, slop=None, channel_id=None, author_type=None, author_id=None, mentions=None, mentions_role_id=None, mention_everyone=None, replied_to_user_id=None, replied_to_message_id=None, pinned=None, has=None, embed_type=None, embed_provider=None, link_hostname=None, attachment_filename=None, attachment_extension=None, sort_by='timestamp', sort_order='desc', include_nsfw=None) → AsyncIterator[Message]

Search for messages within the guild.

Parameters:

  • query (str | None) – The content to search for (max 1024 characters).

  • limit (int | None) – The maximum amount of messages to yield.

  • offset (int) – Number of messages to skip (max 9975).

  • max_id (Snowflake | int | None) – Get messages before this message ID.

  • min_id (Snowflake | int | None) – Get messages after this message ID.

  • slop (int | None) – The max number of words to skip between matching tokens in the search (default 2, max 100).

  • channel_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages by these channels (max 500).

  • author_type (Union[list[Literal['user', 'bot', 'webhook', '-user', '-bot', '-webhook']], Literal['user', 'bot', 'webhook', '-user', '-bot', '-webhook'], None]) – Filter messages by author type (e.g. ‘user’, ‘bot’, ‘webhook’). Negate with ‘-‘.

  • author_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages by these authors (max 100).

  • mentions (list[Snowflake | int] | Snowflake | int | None) – Filter messages that mention these users (max 100).

  • mentions_role_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages that mention these roles (max 100).

  • mention_everyone (bool | None) – Filter messages that do or do not mention @everyone.

  • replied_to_user_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages that reply to these users (max 100).

  • replied_to_message_id (list[Snowflake | int] | Snowflake | int | None) – Filter messages that reply to these messages (max 100).

  • pinned (bool | None) – Filter messages by whether they are or are not pinned.

  • has (Union[list[Literal['image', 'sound', 'video', 'file', 'sticker', 'embed', 'link', 'poll', 'snapshot', '-image', '-sound', '-video', '-file', '-sticker', '-embed', '-link', '-poll', '-snapshot']], Literal['image', 'sound', 'video', 'file', 'sticker', 'embed', 'link', 'poll', 'snapshot', '-image', '-sound', '-video', '-file', '-sticker', '-embed', '-link', '-poll', '-snapshot'], None]) – Filter messages by whether or not they have specific things (e.g. ‘image’, ‘embed’).

  • embed_type (Union[list[Literal['image', 'video', 'gif', 'sound', 'article']], Literal['image', 'video', 'gif', 'sound', 'article'], None]) – Filter messages by embed type (e.g. ‘image’, ‘video’).

  • embed_provider (list[str] | str | None) – Filter messages by embed provider (case-sensitive, e.g. ‘Tenor’) (max 100).

  • link_hostname (list[str] | str | None) – Filter messages by link hostname (e.g. ‘discord.com’) (max 100).

  • attachment_filename (list[str] | str | None) – Filter messages by attachment filename (max 100).

  • attachment_extension (list[str] | str | None) – Filter messages by attachment extension (e.g. ‘txt’) (max 100).

  • sort_by (Literal['timestamp', 'relevance']) – The sorting algorithm to use (“timestamp” or “relevance”).

  • sort_order (Literal['asc', 'desc']) – The direction to sort (“asc” or “desc”).

  • include_nsfw (bool | None) – Whether to include results from age-restricted channels (default False).

Yields:

The message object matching the search.

Return type:

AsyncIterator[Message]

async fetch_automod_rule(automod_id) → AutoModRule

Fetches a automod rule from the guild.

Return type:

AutoModRule

Parameters:

automod_id (int)

async fetch_automod_rules() → list[AutoModRule]

Fetches all the automod rules in the guild.

Return type:

list[AutoModRule]

async create_automod_rule(name, *, event_type, trigger_type, keyword_filter=None, regex_patterns=None, presets=None, allow_list=None, mention_total_limit=None, mention_raid_protection_enabled=False, alert_channel=None, timeout_seconds=None, message=None, enabled=True, exempt_roles=None, exempt_channels=None, reason=None) → AutoModRule

Create an automod rule.

Parameters:

  • name (str) – Name of the automod

  • event_type (AutoModRuleEventType | int) – What type of event

  • trigger_type (AutoModRuleTriggerType | int) – What should make it get triggered

  • keyword_filter (list[str] | None) – Keywords to filter

  • regex_patterns (list[str] | None) – Keywords in regex pattern to filter

  • presets (list[AutoModRulePresetType] | None) – Automod presets to include

  • allow_list (list[str] | None) – List of keywords that are allowed

  • mention_total_limit (int | None) – How many unique mentions allowed before trigger

  • mention_raid_protection_enabled (bool) – If this should apply for raids

  • alert_channel (Snowflake | int | None) – Where the action should be logged

  • timeout_seconds (int | None) – How many seconds the user in question should be timed out

  • message (str | None) – What message the user gets when action is taken

  • enabled (bool) – If the automod should be enabled or not

  • exempt_roles (list[Snowflake | int] | None) – Which roles are allowed to bypass

  • exempt_channels (list[Snowflake | int] | None) – Which channels are allowed to bypass

  • reason (str | None) – Reason for creating the automod

Return type:

AutoModRule

Returns:

The automod that was just created

async fetch_roles() → list[Role]

Fetches all the roles in the guild.

Return type:

list[Role]

async fetch_stickers() → list[Sticker]

Fetches all the stickers in the guild.

Return type:

list[Sticker]

async fetch_scheduled_events_list() → list[ScheduledEvent]

Fetches all the scheduled events in the guild.

Return type:

list[ScheduledEvent]

async fetch_emojis() → list[Emoji]

Fetches all the emojis in the guild.

Return type:

list[Emoji]

async fetch_soundboard_sounds() → list[SoundboardSound]

Fetches all the soundboard sounds in the guild.

Return type:

list[SoundboardSound]

async fetch_ban(user) → BanEntry

Fetches a user’s ban of the guild.

Parameters:

user (Snowflake | int) – The user to fetch the ban of

Return type:

BanEntry

Returns:

Ban entry that was found

async fetch_bans(*, before=None, after=None, limit=1000) → AsyncIterator[BanEntry]

Fetch the bans of the guild.

Parameters:

  • before (Snowflake | int | None) – Consider only users before given user id

  • after (Snowflake | int | None) – Consider only users after given user id

  • limit (int | None) – The maximum amount of messages to fetch. None will fetch all users.

Yields:

The message object

Return type:

AsyncIterator[BanEntry]

async create_role(name, *, permissions=None, color=None, colour=None, unicode_emoji=None, icon=None, hoist=False, mentionable=False, reason=None) → Role

Create a role.

Parameters:

  • name (str) – The name of the role

  • permissions (Permissions | None) – The permissions of the role

  • color (tuple[Colour | int, ...] | Colour | Color | int | None) – Alias for colour

  • colour (tuple[Colour | int, ...] | Colour | Color | int | None) – The colour of the role. If tuple is provided, it switches to the new gradient role colours. The third value must be one of the following: - 16761760 - 11127295 - 16759788

  • hoist (bool) – Whether the role should be hoisted

  • mentionable (bool) – Whether the role should be mentionable

  • unicode_emoji (str | None) – The unicode emoji of the role

  • icon (File | bytes | None) – The icon of the role

  • reason (str | None) – The reason for creating the role

Return type:

Role

Returns:

The created role

async create_scheduled_event(name, *, start_time, end_time=None, channel=None, description=None, privacy_level=None, entity_type=None, external_location=None, image=None, recurrence_rule=None, reason=None) → ScheduledEvent

Create a scheduled event.

Parameters:
Return type:

ScheduledEvent

Returns:

The created event

async create_category(name, *, overwrites=None, position=None, reason=None) → CategoryChannel

Create a category channel.

Parameters:

  • name (str) – The name of the category

  • overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category

  • position (int | None) – The position of the category

  • reason (str | None) – The reason for creating the category

Return type:

CategoryChannel

Returns:

The created category

async create_text_channel(name, *, topic=None, position=None, rate_limit_per_user=None, overwrites=None, parent_id=None, nsfw=None, reason=None) → TextChannel

Create a text channel.

Parameters:

  • name (str) – The name of the channel

  • topic (str | None) – The topic of the channel

  • position (int | None) – The position of the channel

  • rate_limit_per_user (int | None) – The rate limit per user of the channel

  • overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category

  • parent_id (Snowflake | int | None) – The Category ID where the channel will be placed

  • nsfw (bool | None) – Whether the channel is NSFW or not

  • reason (str | None) – The reason for creating the text channel

Return type:

TextChannel

Returns:

The created channel

async create_voice_channel(name, *, bitrate=None, user_limit=None, rate_limit_per_user=None, overwrites=None, position=None, video_quality_mode=None, parent_id=None, nsfw=None, reason=None) → VoiceChannel

Create a voice channel.

Parameters:

  • name (str) – The name of the channel

  • bitrate (int | None) – The bitrate of the channel

  • user_limit (int | None) – The user limit of the channel

  • rate_limit_per_user (int | None) – The rate limit per user of the channel

  • overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category

  • position (int | None) – The position of the channel

  • video_quality_mode (VideoQualityType | int | None) – The video quality mode of the channel

  • parent_id (Snowflake | int | None) – The Category ID where the channel will be placed

  • nsfw (bool | None) – Whether the channel is NSFW or not

  • reason (str | None) – The reason for creating the voice channel

Return type:

VoiceChannel

Returns:

The created channel

async create_stage_channel(name, *, bitrate=None, user_limit=None, overwrites=None, position=None, parent_id=None, video_quality_mode=None, reason=None) → StageChannel

Create a stage channel.

Parameters:

  • name (str) – The name of the channel

  • bitrate (int | None) – The bitrate of the channel

  • user_limit (int | None) – The user limit of the channel

  • overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category

  • position (int | None) – The position of the channel

  • video_quality_mode (VideoQualityType | int | None) – The video quality mode of the channel

  • parent_id (Snowflake | int | None) – The Category ID where the channel will be placed

  • reason (str | None) – The reason for creating the stage channel

Return type:

StageChannel

Returns:

The created channel

async create_emoji(name, *, image, reason=None) → Emoji

Create an emoji.

Parameters:

  • name (str) – Name of the emoji

  • image (File | bytes) – File object to create an emoji from

  • reason (str | None) – The reason for creating the emoji

Return type:

Emoji

Returns:

The created emoji

async create_soundboard_sound(name, *, sound, volume=None, emoji_id=None, emoji_name=None, reason=None) → SoundboardSound

Create a soundboard sound.

Parameters:

  • name (str) – Name of the soundboard sound

  • sound (File | bytes) – File object to create a soundboard sound from

  • volume (int | None) – The volume of the soundboard sound

  • emoji_name (str | None) – The unicode emoji of the soundboard sound

  • emoji_id (str | None) – The ID of the custom emoji of the soundboard sound

  • reason (str | None) – The reason for creating the soundboard sound

Return type:

SoundboardSound

Returns:

The created soundboard sound

Raises:

ValueError – If both emoji_name and emoji_id are set

async create_sticker(name, *, description, emoji, file, reason=None) → Sticker

Create a sticker.

Parameters:

  • name (str) – Name of the sticker

  • description (str) – Description of the sticker

  • emoji (str) – Emoji that represents the sticker

  • file (File) – File object to create a sticker from

  • reason (str | None) – The reason for creating the sticker

Return type:

Sticker

Returns:

The created sticker

async fetch_guild_prune_count(*, days=7, include_roles=None) → int

Fetch the amount of members that would be pruned.

Parameters:
Return type:

int

Returns:

The amount of members that would be pruned

async begin_guild_prune(*, days=7, compute_prune_count=True, include_roles=None, reason=None) → int | None

Begin a guild prune.

Parameters:

  • days (int | None) – How many days of inactivity to prune for

  • compute_prune_count (bool) – Whether to return the amount of members that would be pruned

  • include_roles (list[Role | PartialRole | int] | None) – Which roles to include in the prune

  • reason (str | None) – The reason for beginning the prune

Return type:

int | None

Returns:

The amount of members that were pruned

get_partial_scheduled_event(id) → PartialScheduledEvent

Creates a partial scheduled event object.

Parameters:

id (int) – The ID of the scheduled event.

Return type:

PartialScheduledEvent

Returns:

The partial scheduled event object.

async fetch_scheduled_event(id) → ScheduledEvent

Fetches a scheduled event object.

Parameters:

id (int) – The ID of the scheduled event.

Return type:

ScheduledEvent

Returns:

The scheduled event object.

get_partial_role(role_id) → PartialRole

Get a partial role object.

Parameters:

role_id (int) – The ID of the role

Return type:

PartialRole

Returns:

The partial role object

get_partial_channel(channel_id) → PartialChannel

Get a partial channel object.

Parameters:

channel_id (int) – The ID of the channel

Return type:

PartialChannel

Returns:

The partial channel object

async fetch_channel(channel_id) → BaseChannel

Fetch a channel from the guild.

Parameters:

channel_id (int) – The ID of the channel

Return type:

BaseChannel

Returns:

The channel object

get_partial_emoji(emoji_id) → PartialEmoji

Get a partial emoji object.

Parameters:

emoji_id (int) – The ID of the emoji

Return type:

PartialEmoji

Returns:

The partial emoji object

get_partial_soundboard_sound(sound_id) → PartialSoundboardSound

Get a partial soundboard sound object.

Parameters:

sound_id (int) – The ID of the sound

Return type:

PartialSoundboardSound

Returns:

The partial soundboard sound object

async fetch_soundboard_sound(sound_id) → SoundboardSound

Fetches a soundboard sound from the guild.

Return type:

SoundboardSound

Parameters:

sound_id (int)

async fetch_emoji(emoji_id) → Emoji

Fetches an emoji from the guild.

Return type:

Emoji

Parameters:

emoji_id (int)

get_partial_sticker(sticker_id) → PartialSticker

Get a partial sticker object.

Parameters:

sticker_id (int) – The ID of the sticker

Return type:

PartialSticker

Returns:

The partial sticker object

async fetch_sticker(sticker_id) → Sticker

Fetch a sticker from the guild.

Parameters:

sticker_id (int) – The ID of the sticker

Return type:

Sticker

Returns:

The sticker object

get_partial_member(member_id) → PartialMember

Get a partial member object.

Parameters:

member_id (int) – The ID of the member

Return type:

PartialMember

Returns:

The partial member object

async fetch_member(member_id) → Member

Fetch a member from the guild.

Parameters:

member_id (int) – The ID of the member

Return type:

Member

Returns:

The member object

async fetch_public_threads() → list[PublicThread]

Fetches all the public threads in the guild.

Return type:

list[PublicThread]

Returns:

The public threads in the guild

async fetch_members(*, limit=1000, after=None) → AsyncIterator[Member]

Fetches all the members in the guild.

Parameters:

  • limit (int | None) – The maximum amount of members to return

  • after (Snowflake | int | None) – The member to start after

Yields:

The members in the guild

Return type:

AsyncIterator[Member]

async fetch_regions() → list[VoiceRegion]

Fetches all the voice regions for the guild.

Return type:

list[VoiceRegion]

async fetch_invites() → list[Invite]

Fetches all the invites for the guild.

Return type:

list[Invite]

async bulk_ban(*members, delete_message_days=0, delete_message_seconds=0, reason=None) → list[PartialMember]

Ban multiple members from the server.

Parameters:

  • *members (Member | PartialMember | int) – The members to ban

  • delete_message_days (int | None) – How many days of messages to delete

  • delete_message_seconds (int | None) – How many seconds of messages to delete

  • reason (str | None) – The reason for banning the members

Return type:

list[PartialMember]

Returns:

The banned members

async ban(member, *, delete_message_days=0, delete_message_seconds=0, reason=None) → None

Ban a member from the server.

Parameters:

  • member (Member | PartialMember | int) – The member to ban

  • reason (str | None) – The reason for banning the member

  • delete_message_days (int | None) – How many days of messages to delete

  • delete_message_seconds (int | None) – How many seconds of messages to delete

Return type:

None

async unban(member, *, reason=None) → None

Unban a member from the server.

Parameters:
Return type:

None

async kick(member, *, reason=None) → None

Kick a member from the server.

Parameters:
Return type:

None

async fetch_channels() → list[type[BaseChannel]]

Fetches all the channels in the guild.

Return type:

list[type[BaseChannel]]

async fetch_audit_logs(*, before=None, after=None, user=None, action=None, limit=100) → AsyncIterator[AuditLogEntry]

Fetches the audit logs for the guild.

Parameters:
Return type:

AsyncIterator[AuditLogEntry]

Returns:

The audit logs for the guild

async search_members(query, *, limit=100) → list[Member]

Search for members in the guild.

Parameters:

  • query (str) – The query to search for

  • limit (int | None) – The maximum amount of members to return

Return type:

list[Member]

Returns:

The members that matched the query

Raises:

ValueError – If the limit is not between 1 and 1000

property created_at: datetime

The datetime of the snowflake.

async fetch_integrations() → list[Integration]

Fetches the integrations for the guild.

This requires the MANAGE_GUILD permission.

Return type:

list[Integration]

Returns:

The integrations in the guild.

id: int

The ID of the snowflake.

async delete() → None

Delete the guild (the bot must own the server).

Return type:

None

async edit(*, name=<MISSING>, verification_level=<MISSING>, default_message_notifications=<MISSING>, explicit_content_filter=<MISSING>, afk_channel_id=<MISSING>, afk_timeout=<MISSING>, icon=<MISSING>, owner_id=<MISSING>, splash=<MISSING>, discovery_splash=<MISSING>, banner=<MISSING>, system_channel_id=<MISSING>, system_channel_flags=<MISSING>, rules_channel_id=<MISSING>, public_updates_channel_id=<MISSING>, preferred_locale=<MISSING>, description=<MISSING>, features=<MISSING>, premium_progress_bar_enabled=<MISSING>, safety_alerts_channel_id=<MISSING>, reason=None) → PartialGuild

Edit the guild.

Parameters:
Return type:

PartialGuild

Returns:

The edited guild

class discord_http.guild.PartialGuildTemplate(*, state, code, guild_id=None)

Bases: object

Represents a partial guild template object.

Parameters:
code: str

The code of the template.

guild_id: int | None

The ID of the guild the template belongs to, if known.

async fetch() → GuildTemplate

Fetches the guild template.

Return type:

GuildTemplate

async sync() → GuildTemplate

Syncs the template to the guild’s current state.

Return type:

GuildTemplate

async edit(*, name=<MISSING>, description=<MISSING>) → GuildTemplate

Edits the template’s metadata.

Parameters:

  • name (str | None) – New name of the template

  • description (str | None) – New description of the template

Return type:

GuildTemplate

Returns:

The edited template

async delete() → None

Deletes the template.

Return type:

None

class discord_http.guild.PartialScheduledEvent(*, state, id, guild_id)

Bases: PartialBase

Represents a partial scheduled event in a guild.

Parameters:
guild_id: int

The ID of the guild the scheduled event belongs to.

property guild: Guild | PartialGuild

The guild object this event is in.

property url: str

The URL of the event.

async fetch() → ScheduledEvent

Fetches more information about the event.

Return type:

ScheduledEvent

async delete(*, reason=None) → None

Delete the event (the bot must own the event).

Return type:

None

Parameters:

reason (str | None)

async edit(*, name=<MISSING>, description=<MISSING>, channel=<MISSING>, external_location=<MISSING>, privacy_level=<MISSING>, entity_type=<MISSING>, status=<MISSING>, start_time=<MISSING>, end_time=<MISSING>, image=<MISSING>, recurrence_rule=<MISSING>, reason=None) → ScheduledEvent

Edit the event.

Parameters:
Return type:

ScheduledEvent

Returns:

The edited event

Raises:

ValueError – If the start_time is None

async fetch_users(*, limit=100, with_member=False, before=None, after=None) → list[User | Member]

Fetches the users interested in the event.

Parameters:

  • limit (int) – The maximum amount of users to fetch (1-100)

  • with_member (bool) – Whether to include guild member data for each user, if available

  • before (datetime | Snowflake | int | None) – Consider only users before given user ID

  • after (datetime | Snowflake | int | None) – Consider only users after given user ID

Return type:

list[User | Member]

Returns:

The users interested in the event

property created_at: datetime

The datetime of the snowflake.

id: int

The ID of the snowflake.

class discord_http.guild.ScheduledEvent(*, state, data)

Bases: PartialScheduledEvent

Represents a scheduled event in a guild.

Parameters:
name: str

The name of the scheduled event.

description: str | None

The description of the scheduled event.

user_count: int | None

The number of users interested in the event (only for guild events).

privacy_level: PrivacyLevelType

The privacy level of the event.

status: ScheduledEventStatusType

The status of the event.

entity_type: ScheduledEventEntityType

The entity type of the event.

channel_id: int | None

The ID of the channel the event is in, if applicable.

creator: User | None

The creator of the event, if applicable.

start_time: datetime

The time the event starts at.

end_time: datetime | None

The time the event ends at, if applicable.

recurrence_rule: ScheduledEventRecurrenceRule | None

The recurrence rule of the event, if any.

image: Asset | None

The cover image of the event, if any.

property channel: PartialChannel | None

The channel the event is in, if applicable.

property created_at: datetime

The datetime of the snowflake.

async delete(*, reason=None) → None

Delete the event (the bot must own the event).

Return type:

None

Parameters:

reason (str | None)

async edit(*, name=<MISSING>, description=<MISSING>, channel=<MISSING>, external_location=<MISSING>, privacy_level=<MISSING>, entity_type=<MISSING>, status=<MISSING>, start_time=<MISSING>, end_time=<MISSING>, image=<MISSING>, recurrence_rule=<MISSING>, reason=None) → ScheduledEvent

Edit the event.

Parameters:
Return type:

ScheduledEvent

Returns:

The edited event

Raises:

ValueError – If the start_time is None

async fetch() → ScheduledEvent

Fetches more information about the event.

Return type:

ScheduledEvent

async fetch_users(*, limit=100, with_member=False, before=None, after=None) → list[User | Member]

Fetches the users interested in the event.

Parameters:

  • limit (int) – The maximum amount of users to fetch (1-100)

  • with_member (bool) – Whether to include guild member data for each user, if available

  • before (datetime | Snowflake | int | None) – Consider only users before given user ID

  • after (datetime | Snowflake | int | None) – Consider only users after given user ID

Return type:

list[User | Member]

Returns:

The users interested in the event

property guild: Guild | PartialGuild

The guild object this event is in.

guild_id: int

The ID of the guild the scheduled event belongs to.

id: int

The ID of the snowflake.

property url: str

The URL of the event.

class discord_http.guild.ScheduledEventRecurrenceRule(start, frequency, interval, end=None, by_weekday=None, by_n_weekday=None, by_month=None, by_month_day=None, by_year_day=None, count=None)

Bases: NamedTuple

Represents the recurrence rule of a scheduled event.

Parameters:
start: datetime

Alias for field number 0

frequency: ScheduledEventRecurrenceFrequency

Alias for field number 1

interval: int

Alias for field number 2

end: datetime | None

Alias for field number 3

by_weekday: list[ScheduledEventRecurrenceWeekday] | None

Alias for field number 4

by_n_weekday: list[ScheduledEventRecurrenceRuleNWeekday] | None

Alias for field number 5

by_month: list[ScheduledEventRecurrenceMonth] | None

Alias for field number 6

by_month_day: list[int] | None

Alias for field number 7

by_year_day: list[int] | None

Alias for field number 8

count: int | None

Alias for field number 9

to_dict() → dict

Turns the recurrence rule into a payload for the API.

Only the fields that can be set externally are included, as the rest are only ever provided by Discord.

Return type:

dict

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class discord_http.guild.ScheduledEventRecurrenceRuleNWeekday(n, day)

Bases: NamedTuple

Represents a specific weekday within a specific week for a scheduled event recurrence rule.

Parameters:
n: int

Alias for field number 0

day: ScheduledEventRecurrenceWeekday

Alias for field number 1

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class discord_http.guild.WelcomeScreen(*, state, guild_id, data)

Bases: object

Represents a guild’s welcome screen.

Parameters:
description: str | None

The description of the welcome screen, if any.

welcome_channels: list[WelcomeScreenChannel]

The channels shown in the welcome screen.

class discord_http.guild.WelcomeScreenChannel(*, state, guild_id, data)

Bases: object

Represents a channel shown in a guild’s welcome screen.

Parameters:
description: str

The description shown next to the channel.

emoji_id: int | None

The ID of the custom emoji shown next to the channel, if any.

emoji_name: str | None

The unicode emoji shown next to the channel, if any.

guild_id: int

The guild_id that the welcome screen belongs to.

property emoji: PartialEmoji | None

The partial custom emoji shown next to the channel, if any.

property channel: PartialChannel

The channel shown in the welcome screen.

to_dict() → dict

Returns a dict representation of the welcome screen channel.

Return type:

dict

channel_id