REST API Reference

Every Discord REST endpoint cordless wraps, grouped by resource. Each call is shown in both styles: bot.<verb>_<resource>(...) when you only have an id, and the <object>.<action>(...) sugar when you already hold the model. Both run the same request path, so retries, rate limiting, and error handling apply identically. See REST API for how the layers relate and Rate Limiting for retry behaviour. Generated straight from the installed package.

Application

bot.fetch_application

await bot.fetch_application(*, token: str | None = None)

The bot’s own Application, the object behind its developer-portal listing.

bot.fetch_application_role_connection_metadata

await bot.fetch_application_role_connection_metadata(application_id: str, *,
                                                     token: str | None = None)

The Linked Roles metadata records, or [] if none are registered.

bot.edit_application_role_connection_metadata

await bot.edit_application_role_connection_metadata(application_id: str, records: Any, *,
                                                    token: str | None = None)

records is the full list of up to 5 metadata records - this replaces the whole set, same as bulk_overwrite_global_commands does for commands.

bot.edit_application

await bot.edit_application(*, custom_install_url: Any = UNSET, description: Any = UNSET,
                           role_connections_verification_url: Any = UNSET,
                           install_params: Any = UNSET, integration_types_config: Any = UNSET,
                           flags: Any = UNSET, icon: Any = UNSET, cover_image: Any = UNSET,
                           interactions_endpoint_url: Any = UNSET, tags: Any = UNSET,
                           event_webhooks_url: Any = UNSET, event_webhooks_status: Any = UNSET,
                           event_webhooks_types: Any = UNSET, token: str | None = None)

Only a handful of application flags can actually be set this way (the GATEWAY_*_LIMITED intents and EMBEDDED) - Discord silently ignores the rest.

Application Commands

bot.fetch_global_commands

await bot.fetch_global_commands(application_id: str, *, with_localizations: bool = False,
                                token: str | None = None)

Every global command. with_localizations adds the per-locale name/description dicts.

bot.create_global_command

await bot.create_global_command(application_id: str, name: str, *, description: Any = UNSET,
                                options: Any = UNSET, default_member_permissions: Any = UNSET,
                                integration_types: Any = UNSET, contexts: Any = UNSET,
                                type: Any = UNSET, nsfw: Any = UNSET, handler: Any = UNSET,
                                token: str | None = None)

Registers a new global command. Global command changes can take up to an hour to propagate to every guild, register a guild command instead while testing to see changes straight away.

bot.fetch_global_command

await bot.fetch_global_command(application_id: str, command_id: str, *, token: str | None = None)

A single global ApplicationCommand by id.

bot.edit_global_command

await bot.edit_global_command(application_id: str, command_id: str, *, name: Any = UNSET,
                              description: Any = UNSET, options: Any = UNSET,
                              default_member_permissions: Any = UNSET,
                              integration_types: Any = UNSET, contexts: Any = UNSET,
                              nsfw: Any = UNSET, handler: Any = UNSET, token: str | None = None)

Partial update: pass only the fields to change. Global changes take up to an hour to propagate.

bot.delete_global_command

await bot.delete_global_command(application_id: str, command_id: str, *, token: str | None = None)

Removes a global command; up to an hour to clear from every guild.

bot.bulk_overwrite_global_commands

await bot.bulk_overwrite_global_commands(application_id: str, commands: Any, *,
                                         token: str | None = None)

Replaces every global command with the given list in one call. Commands left out of the list are deleted; ones that match an existing command by name and type keep their id, so any per-command state such as guild permission overrides survives the overwrite.

bot.fetch_guild_commands

await bot.fetch_guild_commands(application_id: str, guild_id: str, *,
                               with_localizations: bool = False, token: str | None = None)

Every command registered to one guild.

bot.create_guild_command

await bot.create_guild_command(application_id: str, guild_id: str, name: str, *,
                               description: Any = UNSET, options: Any = UNSET,
                               default_member_permissions: Any = UNSET, type: Any = UNSET,
                               nsfw: Any = UNSET, handler: Any = UNSET, token: str | None = None)

Registers a new command scoped to a single guild. Unlike a global command, it appears in that guild immediately, which makes guild commands the better choice while iterating on a command’s shape.

bot.fetch_guild_command

await bot.fetch_guild_command(application_id: str, guild_id: str, command_id: str, *,
                              token: str | None = None)

A single guild ApplicationCommand by id.

bot.edit_guild_command

await bot.edit_guild_command(application_id: str, guild_id: str, command_id: str, *,
                             name: Any = UNSET, description: Any = UNSET, options: Any = UNSET,
                             default_member_permissions: Any = UNSET, nsfw: Any = UNSET,
                             handler: Any = UNSET, token: str | None = None)

Partial update: pass only the fields to change.

bot.delete_guild_command

await bot.delete_guild_command(application_id: str, guild_id: str, command_id: str, *,
                               token: str | None = None)

Removes a guild command; effective immediately, unlike global commands.

bot.bulk_overwrite_guild_commands

await bot.bulk_overwrite_guild_commands(application_id: str, guild_id: str, commands: Any, *,
                                        token: str | None = None)

Replaces every command in the guild with the given list in one call, the same as bulk_overwrite_global_commands but scoped to a single guild.

bot.fetch_guild_command_permissions

await bot.fetch_guild_command_permissions(application_id: str, guild_id: str, *,
                                          token: str | None = None)

The permission overrides for every command in the guild that has any set.

bot.fetch_command_permissions

await bot.fetch_command_permissions(application_id: str, guild_id: str, command_id: str, *,
                                    token: str | None = None)

The permission overrides for one command. NotFound if none are set.

Audit Log

bot.fetch_audit_log

await bot.fetch_audit_log(guild_id: str, *, user_id: str | None = None,
                          action_type: int | None = None, before: str | None = None,
                          after: str | None = None, limit: int | None = None,
                          token: str | None = None)

Requires VIEW_AUDIT_LOG. before/after paginate by audit log entry id, not by any resource id.

Auto Moderation

bot.fetch_auto_moderation_rules

await bot.fetch_auto_moderation_rules(guild_id: str, *, token: str | None = None)

Every rule in the guild, as AutoModerationRule objects.

bot.fetch_auto_moderation_rule

await bot.fetch_auto_moderation_rule(guild_id: str, rule_id: str, *, token: str | None = None)

One AutoModerationRule by id; NotFound if it was deleted.

bot.create_auto_moderation_rule

await bot.create_auto_moderation_rule(guild_id: str, name: str, event_type: int,
                                      trigger_type: int, actions: Any, *,
                                      trigger_metadata: Any = UNSET, enabled: Any = UNSET,
                                      exempt_roles: Any = UNSET, exempt_channels: Any = UNSET,
                                      token: str | None = None)

trigger_metadata’s shape follows trigger_type: a keyword filter wants keyword_filter, a mention-spam rule wants mention_total_limit, etc.

bot.edit_auto_moderation_rule

await bot.edit_auto_moderation_rule(guild_id: str, rule_id: str, *, name: Any = UNSET,
                                    event_type: Any = UNSET, trigger_metadata: Any = UNSET,
                                    actions: Any = UNSET, enabled: Any = UNSET,
                                    exempt_roles: Any = UNSET, exempt_channels: Any = UNSET,
                                    token: str | None = None)

Pass only the fields to change.

bot.delete_auto_moderation_rule

await bot.delete_auto_moderation_rule(guild_id: str, rule_id: str, *, token: str | None = None)

Permanent. To pause a rule without losing it, edit(enabled=False) instead.

Channel

A partial Discord channel, e.g. ctx.channel. .id, .name, .type, and any other field Discord sends are available as attributes.

bot.fetch_channel

await bot.fetch_channel(channel_id: str, *, token: str | None = None)

Fetches a channel by id. Works for a guild channel, a thread, or a DM, whatever channel_id happens to point at.

bot.edit_channel

await bot.edit_channel(channel_id: str, *, name: Any = UNSET, icon: Any = UNSET,
                       type: Any = UNSET, position: Any = UNSET, topic: Any = UNSET,
                       nsfw: Any = UNSET, rate_limit_per_user: Any = UNSET, bitrate: Any = UNSET,
                       user_limit: Any = UNSET, permission_overwrites: Any = UNSET,
                       parent_id: Any = UNSET, rtc_region: Any = UNSET,
                       video_quality_mode: Any = UNSET,
                       default_auto_archive_duration: Any = UNSET, flags: Any = UNSET,
                       available_tags: Any = UNSET, default_reaction_emoji: Any = UNSET,
                       default_thread_rate_limit_per_user: Any = UNSET,
                       default_sort_order: Any = UNSET, default_forum_layout: Any = UNSET,
                       archived: Any = UNSET, auto_archive_duration: Any = UNSET,
                       locked: Any = UNSET, invitable: Any = UNSET, applied_tags: Any = UNSET,
                       reason: str | None = None, token: str | None = None)

One endpoint covers group DMs, guild channels and threads alike - Discord just looks at which fields you actually send. Pass only the ones that apply to what channel_id happens to be. Most nullable fields (parent_id, icon, rtc_region, …) can be cleared by passing None.

bot.delete_channel

await bot.delete_channel(channel_id: str, *, reason: str | None = None, token: str | None = None)

Deletes a guild channel, closes a DM, or deletes a thread - returns the now-deleted channel object.

bot.edit_channel_permissions

await bot.edit_channel_permissions(channel_id: str, overwrite_id: str, *, type: int,
                                   allow: Any = UNSET, deny: Any = UNSET,
                                   reason: str | None = None, token: str | None = None)

type is 0 for a role overwrite, 1 for a member overwrite. allow/deny are permission bitfields as strings (see Permissions).

bot.delete_channel_permission

await bot.delete_channel_permission(channel_id: str, overwrite_id: str, *,
                                    reason: str | None = None, token: str | None = None)

Requires MANAGE_ROLES.

bot.fetch_channel_invites

await bot.fetch_channel_invites(channel_id: str, *, token: str | None = None)

Fetches every invite pointing at this channel, each with its own use count.

bot.create_channel_invite

await bot.create_channel_invite(channel_id: str, *, max_age: Any = UNSET, max_uses: Any = UNSET,
                                temporary: Any = UNSET, unique: Any = UNSET,
                                target_type: Any = UNSET, target_user_id: Any = UNSET,
                                target_application_id: Any = UNSET, token: str | None = None)

Creates an invite to this channel. Leaving max_age and max_uses unset gives an invite that never expires and has no use limit.

bot.follow_announcement_channel

await bot.follow_announcement_channel(channel_id: str, webhook_channel_id: str, *,
                                      token: str | None = None)

Mirrors this announcement channel’s future posts into webhook_channel_id. Returns the created webhook as a FollowedChannel.

bot.trigger_typing

await bot.trigger_typing(channel_id: str, *, token: str | None = None)

Shows the typing indicator for ~10 seconds, or until a message is sent.

bot.set_voice_channel_status

await bot.set_voice_channel_status(channel_id: str, status: str | None = None, *,
                                   token: str | None = None)

status=None clears it. Requires SET_VOICE_CHANNEL_STATUS, or SEND_MESSAGES plus CONNECT if you’re the one currently connected.

bot.add_group_dm_recipient

await bot.add_group_dm_recipient(channel_id: str, user_id: str, access_token: str, *,
                                 nick: Any = UNSET, token: str | None = None)

Adds a user to a group DM. access_token is an OAuth2 token for that user with the gdm.join scope, obtained separately, a bot can’t add someone to a group DM on its own authority.

bot.remove_group_dm_recipient

await bot.remove_group_dm_recipient(channel_id: str, user_id: str, *, token: str | None = None)

Group DMs only.

bot.fetch_channel_pins

await bot.fetch_channel_pins(channel_id: str, *, before: str | None = None,
                             limit: int | None = None, token: str | None = None)

Fetches the channel’s pinned messages, newest first.

bot.pin_message

await bot.pin_message(channel_id: str, message_id: str, *, token: str | None = None)

Pins a message. A channel can only hold 50 pinned messages at once.

bot.unpin_message

await bot.unpin_message(channel_id: str, message_id: str, *, token: str | None = None)

Unpins a message without deleting it.

bot.fetch_guild_channels

await bot.fetch_guild_channels(guild_id: str, *, token: str | None = None)

Fetches every top-level channel in the guild. Threads aren’t included, use the thread listing endpoints for those.

bot.create_guild_channel

await bot.create_guild_channel(guild_id: str, name: str, *, type: Any = UNSET,
                               topic: Any = UNSET, bitrate: Any = UNSET, user_limit: Any = UNSET,
                               rate_limit_per_user: Any = UNSET, position: Any = UNSET,
                               permission_overwrites: Any = UNSET, parent_id: Any = UNSET,
                               nsfw: Any = UNSET, rtc_region: Any = UNSET,
                               video_quality_mode: Any = UNSET,
                               default_auto_archive_duration: Any = UNSET,
                               default_reaction_emoji: Any = UNSET, available_tags: Any = UNSET,
                               default_sort_order: Any = UNSET,
                               default_forum_layout: Any = UNSET,
                               default_thread_rate_limit_per_user: Any = UNSET,
                               flags: Any = UNSET, reason: str | None = None,
                               token: str | None = None)

Creates a new channel in the guild. type picks the channel kind (text, voice, category, forum, …); leave it unset for an ordinary text channel.

bot.edit_guild_channel_positions

await bot.edit_guild_channel_positions(guild_id: str, positions: Any, *, token: str | None = None)

positions is a list of {“id”: channel_id, “position”: int, …} dicts, per Discord’s Modify Guild Channel Positions body. Not audit-logged by Discord, unlike every other mutating endpoint in this module.

channel.start_thread_from_message

await channel.start_thread_from_message(message_id: str, name: str, **kwargs: Any)

Start a thread off an existing message in this channel. Returns a Thread.

channel.start_thread_without_message

await channel.start_thread_without_message(name: str, **kwargs: Any)

Start a thread not attached to any message in this channel. Returns a Thread.

channel.start_thread_from_forum

await channel.start_thread_from_forum(name: str, *, message: str, **kwargs: Any)

Start a forum post (a thread with its first message) in this forum channel. Returns a Thread.

channel.fetch_public_archived_threads

await channel.fetch_public_archived_threads(**kwargs: Any)

List this channel’s public archived threads, as a list of Thread.

channel.fetch_private_archived_threads

await channel.fetch_private_archived_threads(**kwargs: Any)

List this channel’s private archived threads, as a list of Thread. Requires MANAGE_THREADS.

channel.fetch_joined_private_archived_threads

await channel.fetch_joined_private_archived_threads(**kwargs: Any)

List this channel’s private archived threads the bot has joined, as a list of Thread.

channel.fetch

await channel.fetch(**kwargs: Any)

Re-fetch this channel’s full object from Discord - ctx.channel only carries a partial payload.

channel.edit

await channel.edit(**kwargs: Any)

Update this channel’s settings. See _rest.channels.edit_channel for the full field list. Returns the updated Channel.

channel.delete

await channel.delete(**kwargs: Any)

Delete this channel, close this DM, or delete this thread. Returns the now-deleted Channel.

channel.set_permissions

await channel.set_permissions(overwrite_id: str, *, type: int, **kwargs: Any)

Add or edit a permission overwrite for a role or member. type is 0 for a role, 1 for a member.

channel.delete_permission

await channel.delete_permission(overwrite_id: str, **kwargs: Any)

Requires MANAGE_ROLES.

channel.fetch_invites

await channel.fetch_invites(**kwargs: Any)

List this channel’s invites, as a list of Invite.

channel.create_invite

await channel.create_invite(**kwargs: Any)

Create an invite to this channel. Returns an Invite.

channel.follow_announcement

await channel.follow_announcement(webhook_channel_id: str, **kwargs: Any)

Mirror this announcement channel’s posts into webhook_channel_id. Returns a FollowedChannel.

channel.trigger_typing

await channel.trigger_typing(**kwargs: Any)

Show the typing indicator in this channel for ~10 seconds, or until a message is sent.

channel.set_voice_status

await channel.set_voice_status(status: str | None = None, **kwargs: Any)

Set (or, with status=None, clear) this voice channel’s status.

channel.add_recipient

await channel.add_recipient(user_id: str, access_token: str, **kwargs: Any)

Add a user to this group DM, given an OAuth2 token with the gdm.join scope.

channel.remove_recipient

await channel.remove_recipient(user_id: str, **kwargs: Any)

Group DMs only.

channel.fetch_pins

await channel.fetch_pins(**kwargs: Any)

List this channel’s pinned messages, as a list of MessagePin.

channel.pin_message

await channel.pin_message(message_id: str, **kwargs: Any)

Pin a message in this channel. Requires PIN_MESSAGES.

channel.unpin_message

await channel.unpin_message(message_id: str, **kwargs: Any)

Unpin a message in this channel. Requires PIN_MESSAGES.

channel.fetch_messages

await channel.fetch_messages(**kwargs: Any)

List recent messages in this channel, newest first, as a list of Message.

channel.fetch_message

await channel.fetch_message(message_id: str, **kwargs: Any)

Fetch a single Message by id.

channel.send

await channel.send(**kwargs: Any)

Send a message with the full Create Message field set (replies via message_reference, poll, sticker_ids, tts, nonce, …), unlike the simpler bot.send_message(). Returns the sent Message.

channel.bulk_delete_messages

await channel.bulk_delete_messages(message_ids: Any, **kwargs: Any)

Delete 2-100 messages at once, none older than two weeks. Guild channels only. Requires MANAGE_MESSAGES.

channel.fetch_webhooks

await channel.fetch_webhooks(**kwargs: Any)

List this channel’s webhooks, as a list of Webhook. Requires MANAGE_WEBHOOKS.

channel.create_stage_instance

await channel.create_stage_instance(topic: str, **kwargs: Any)

Start a live Stage on this Stage channel. Returns the new StageInstance. Requires Stage moderator permissions.

channel.fetch_stage_instance

await channel.fetch_stage_instance(**kwargs: Any)

Fetch this Stage channel’s live StageInstance, if it has one.

channel.send_soundboard_sound

await channel.send_soundboard_sound(sound_id: str, **kwargs: Any)

Play a soundboard sound in this channel’s voice channel. Bot must already be connected to it. Requires SPEAK and USE_SOUNDBOARD.

Emoji

bot.fetch_guild_emojis

await bot.fetch_guild_emojis(guild_id: str, *, token: str | None = None)

Every custom Emoji in the guild.

bot.fetch_guild_emoji

await bot.fetch_guild_emoji(guild_id: str, emoji_id: str, *, token: str | None = None)

One guild Emoji by id.

bot.create_guild_emoji

await bot.create_guild_emoji(guild_id: str, name: str, image: str, *, roles: Any = UNSET,
                             token: str | None = None)

Uploads a new custom emoji. image is a data URI. roles, if given, restricts the emoji to members with at least one of those roles.

bot.edit_guild_emoji

await bot.edit_guild_emoji(guild_id: str, emoji_id: str, *, name: Any = UNSET,
                           roles: Any = UNSET, token: str | None = None)

Renames an emoji or changes which roles can use it. The image itself can’t be changed after upload, delete and recreate instead.

bot.delete_guild_emoji

await bot.delete_guild_emoji(guild_id: str, emoji_id: str, *, token: str | None = None)

Requires MANAGE_GUILD_EXPRESSIONS, or being the emoji’s creator.

bot.fetch_application_emojis

await bot.fetch_application_emojis(application_id: str, *, token: str | None = None)

Fetches every emoji owned by the application, usable in messages from any guild the bot can see.

bot.fetch_application_emoji

await bot.fetch_application_emoji(application_id: str, emoji_id: str, *, token: str | None = None)

One application Emoji by id.

bot.create_application_emoji

await bot.create_application_emoji(application_id: str, name: str, image: str, *,
                                   token: str | None = None)

Uploads a new application emoji. image is a data URI. Unlike a guild emoji it isn’t tied to any one server and doesn’t count against a guild’s emoji slots.

bot.edit_application_emoji

await bot.edit_application_emoji(application_id: str, emoji_id: str, *, name: Any = UNSET,
                                 token: str | None = None)

Application emojis carry no role restriction, so the name is all that can change.

bot.delete_application_emoji

await bot.delete_application_emoji(application_id: str, emoji_id: str, *,
                                   token: str | None = None)

Frees the emoji’s name for reuse by the app.

Entitlement

bot.fetch_entitlements

await bot.fetch_entitlements(application_id: str, *, user_id: str | None = None,
                             sku_ids: list[str] | None = None, before: str | None = None,
                             after: str | None = None, limit: int | None = None,
                             guild_id: str | None = None, exclude_ended: bool | None = None,
                             exclude_deleted: bool | None = None, token: str | None = None)

Fetches the application’s entitlements, its record of who owns which SKU, optionally filtered to a user, a guild, or a set of SKU ids.

bot.fetch_entitlement

await bot.fetch_entitlement(application_id: str, entitlement_id: str, *, token: str | None = None)

One Entitlement by id.

bot.consume_entitlement

await bot.consume_entitlement(application_id: str, entitlement_id: str, *,
                              token: str | None = None)

Marks a one-time-purchase consumable entitlement as used. Only valid for consumable SKUs, subscriptions don’t need this.

bot.create_test_entitlement

await bot.create_test_entitlement(application_id: str, sku_id: str, owner_id: str,
                                  owner_type: int, *, token: str | None = None)

Grants a fake entitlement for testing, without it ever going through Discord’s payment flow. owner_type is 1 for a guild subscription or 2 for a user subscription.

bot.delete_test_entitlement

await bot.delete_test_entitlement(application_id: str, entitlement_id: str, *,
                                  token: str | None = None)

Test entitlements only; a real purchase can’t be deleted this way.

Guild

A Discord guild, e.g. ctx.guild. Built from the partial guild object Discord includes on the interaction, so most fields beyond .id, .locale, and .features are not present here.

bot.fetch_guild

await bot.fetch_guild(guild_id: str, *, with_counts: bool = False, token: str | None = None)

Fetches a guild by id. with_counts adds approximate_member_count and approximate_presence_count to the result.

bot.fetch_guild_preview

await bot.fetch_guild_preview(guild_id: str, *, token: str | None = None)

Fetches a guild’s public preview. Works even for guilds the bot isn’t in, as long as the guild is discoverable or has its widget enabled.

bot.edit_guild

await bot.edit_guild(guild_id: str, *, name: Any = UNSET, region: Any = UNSET,
                     verification_level: Any = UNSET, default_message_notifications: Any = UNSET,
                     explicit_content_filter: Any = UNSET, afk_channel_id: Any = UNSET,
                     afk_timeout: Any = UNSET, icon: Any = UNSET, splash: Any = UNSET,
                     discovery_splash: Any = UNSET, banner: Any = UNSET,
                     system_channel_id: Any = UNSET, system_channel_flags: Any = UNSET,
                     rules_channel_id: Any = UNSET, public_updates_channel_id: Any = UNSET,
                     preferred_locale: Any = UNSET, features: Any = UNSET,
                     description: Any = UNSET, premium_progress_bar_enabled: Any = UNSET,
                     safety_alerts_channel_id: Any = UNSET, reason: str | None = None,
                     token: str | None = None)

Most nullable fields (afk_channel_id, icon, splash, …) can be cleared by passing None.

bot.fetch_guild_bans

await bot.fetch_guild_bans(guild_id: str, *, limit: int | None = None, before: str | None = None,
                           after: str | None = None, token: str | None = None)

A page of Ban objects. Requires BAN_MEMBERS.

bot.fetch_guild_ban

await bot.fetch_guild_ban(guild_id: str, user_id: str, *, token: str | None = None)

Fetches a single ban by user id, or raises NotFound if the user isn’t banned.

bot.create_guild_ban

await bot.create_guild_ban(guild_id: str, user_id: str, *, delete_message_seconds: Any = UNSET,
                           delete_message_days: Any = UNSET, reason: str | None = None,
                           token: str | None = None)

Bans a user, whether or not they’re currently a member of the guild. delete_message_seconds (0 to 604800) also deletes that user’s recent messages; delete_message_days is the older, day-granularity equivalent, kept for callers that still use it.

bot.remove_guild_ban

await bot.remove_guild_ban(guild_id: str, user_id: str, *, reason: str | None = None,
                           token: str | None = None)

Requires BAN_MEMBERS.

bot.bulk_guild_ban

await bot.bulk_guild_ban(guild_id: str, user_ids: Any, *, delete_message_seconds: Any = UNSET,
                         reason: str | None = None, token: str | None = None)

Bans up to 200 users in one call. The result lists which ids were banned successfully and which failed, a partial failure doesn’t raise on its own.

bot.fetch_guild_prune_count

await bot.fetch_guild_prune_count(guild_id: str, *, days: int | None = None,
                                  include_roles: list[str] | None = None,
                                  token: str | None = None)

Counts how many members would be removed by a prune, without actually removing them. Members with a role in include_roles are counted even though they’d normally be exempt.

bot.begin_guild_prune

await bot.begin_guild_prune(guild_id: str, *, days: Any = UNSET,
                            compute_prune_count: Any = UNSET, include_roles: Any = UNSET,
                            reason: str | None = None, token: str | None = None)

Kicks every member who hasn’t been seen for days and holds none of the guild’s roles, unless their role is listed in include_roles. Set compute_prune_count=False on a large guild to skip counting the removed members and speed up the request.

bot.fetch_guild_voice_regions

await bot.fetch_guild_voice_regions(guild_id: str, *, token: str | None = None)

Fetches the voice regions available to this guild, ordered by how close they are to it (VIP regions first if the guild has them).

bot.fetch_guild_invites

await bot.fetch_guild_invites(guild_id: str, *, token: str | None = None)

Fetches every invite for the guild, across all its channels, each with its own use count.

bot.fetch_guild_integrations

await bot.fetch_guild_integrations(guild_id: str, *, token: str | None = None)

Fetches the guild’s third-party integrations, Twitch, YouTube and the like.

bot.delete_guild_integration

await bot.delete_guild_integration(guild_id: str, integration_id: str, *,
                                   token: str | None = None)

Removes an integration and deletes any webhooks or roles it created.

bot.fetch_guild_widget_settings

await bot.fetch_guild_widget_settings(guild_id: str, *, token: str | None = None)

Fetches whether the guild’s server widget is enabled and which channel its invite points at.

bot.edit_guild_widget

await bot.edit_guild_widget(guild_id: str, *, enabled: Any = UNSET, channel_id: Any = UNSET,
                            token: str | None = None)

Turns the server widget on or off, or changes which channel its invite points at.

bot.fetch_guild_widget

await bot.fetch_guild_widget(guild_id: str, *, token: str | None = None)

Fetches the guild’s public widget, an embeddable member list and invite link. Works with no authentication needed on Discord’s side, but raises NotFound if the widget isn’t enabled.

bot.fetch_guild_vanity_url

await bot.fetch_guild_vanity_url(guild_id: str, *, token: str | None = None)

code is null on the returned partial invite if the guild has no vanity url set.

bot.fetch_guild_welcome_screen

await bot.fetch_guild_welcome_screen(guild_id: str, *, token: str | None = None)

Fetches the guild’s welcome screen, the recommended-channels prompt shown to new members.

bot.edit_guild_welcome_screen

await bot.edit_guild_welcome_screen(guild_id: str, *, enabled: Any = UNSET,
                                    welcome_channels: Any = UNSET, description: Any = UNSET,
                                    token: str | None = None)

Edits the guild’s welcome screen. welcome_channels replaces the whole list of recommended channels, up to 5.

bot.fetch_guild_onboarding

await bot.fetch_guild_onboarding(guild_id: str, *, token: str | None = None)

Fetches the guild’s onboarding configuration, the prompts shown to new members to pick roles and channels.

bot.edit_guild_onboarding

await bot.edit_guild_onboarding(guild_id: str, *, prompts: Any = UNSET,
                                default_channel_ids: Any = UNSET, enabled: Any = UNSET,
                                mode: Any = UNSET, token: str | None = None)

Edits the guild’s onboarding configuration. prompts replaces the whole set; enabling onboarding requires the guild to already meet Discord’s rules channel and community setup requirements.

bot.edit_guild_incident_actions

await bot.edit_guild_incident_actions(guild_id: str, *, invites_disabled_until: Any = UNSET,
                                      dms_disabled_until: Any = UNSET, token: str | None = None)

Sets or clears the guild’s raid protection measures, temporarily pausing invites or DMs between members until the given timestamps. Pass None to clear a measure immediately.

guild.widget_image_url

guild.widget_image_url(style: str = "shield")

Full URL for this guild’s widget image (a live PNG showing member count). Public and unauthenticated, so this just builds the URL, it doesn’t call Discord. style is one of “shield”, “banner1”, “banner2”, “banner3”, “banner4”.

guild.fetch_active_threads

await guild.fetch_active_threads(**kwargs: Any)

List every active thread in this guild (public and private), as a list of Thread.

guild.create_channel

await guild.create_channel(name: str, **kwargs: Any)

Create a channel in this guild. type picks the kind (0 text, 2 voice, 4 category, 5 announcement, 13 stage, 15 forum, 16 media, …); see _rest.channels.create_guild_channel for the full field list. Returns the new Channel.

guild.fetch_channels

await guild.fetch_channels(**kwargs: Any)

List this guild’s channels, as a list of Channel.

guild.edit_channel_positions

await guild.edit_channel_positions(positions: Any, **kwargs: Any)

Reorder this guild’s channels. positions is a list of {"id": channel_id, "position": int, ...} dicts.

guild.fetch

await guild.fetch(**kwargs: Any)

Re-fetch this guild’s full object from Discord - ctx.guild only carries .id, .locale, .features. Pass with_counts=True for approximate member/presence counts.

guild.fetch_preview

await guild.fetch_preview(**kwargs: Any)

Fetch this guild’s preview object. Requires DISCORD_BOT_TOKEN unless the guild is discoverable.

guild.edit

await guild.edit(**kwargs: Any)

Update this guild’s settings. See _rest.guilds.edit_guild for the full field list. Returns the updated Guild. Requires MANAGE_GUILD.

guild.fetch_bans

await guild.fetch_bans(**kwargs: Any)

List this guild’s bans, as a list of Ban. Requires BAN_MEMBERS.

guild.fetch_ban

await guild.fetch_ban(user_id: str, **kwargs: Any)

Fetch a single Ban by user id. Requires BAN_MEMBERS.

guild.ban

await guild.ban(user_id: str, **kwargs: Any)

Ban a user, optionally deleting their recent messages via delete_message_seconds. Requires BAN_MEMBERS.

guild.unban

await guild.unban(user_id: str, **kwargs: Any)

Remove a ban. Requires BAN_MEMBERS.

guild.bulk_ban

await guild.bulk_ban(user_ids: Any, **kwargs: Any)

Ban up to 200 users at once. Returns a BulkBanResult. Requires BAN_MEMBERS and MANAGE_GUILD.

guild.fetch_prune_count

await guild.fetch_prune_count(**kwargs: Any)

Preview how many inactive members a prune would remove, without removing them. Requires MANAGE_GUILD and KICK_MEMBERS.

guild.prune

await guild.prune(**kwargs: Any)

Kick inactive members. Returns the number removed, or None if compute_prune_count=False. Requires MANAGE_GUILD and KICK_MEMBERS.

guild.fetch_voice_regions

await guild.fetch_voice_regions(**kwargs: Any)

List this guild’s available voice regions, as a list of VoiceRegion.

guild.fetch_voice_state

await guild.fetch_voice_state(**kwargs: Any)

Fetch the bot’s own voice state in this guild, as a VoiceState.

guild.fetch_member_voice_state

await guild.fetch_member_voice_state(user_id: str, **kwargs: Any)

Fetch a member’s voice state in this guild, as a VoiceState.

guild.edit_voice_state

await guild.edit_voice_state(**kwargs: Any)

Update the bot’s own voice state - move it with channel_id, or request/cancel a Stage speaker request with request_to_speak_timestamp.

guild.edit_member_voice_state

await guild.edit_member_voice_state(user_id: str, **kwargs: Any)

Move a member on a Stage channel - suppress=False invites them to speak, suppress=True moves them back to the audience. Requires MUTE_MEMBERS.

guild.fetch_invites

await guild.fetch_invites(**kwargs: Any)

List every invite across this guild, as a list of Invite. Requires MANAGE_GUILD or VIEW_AUDIT_LOG.

guild.fetch_integrations

await guild.fetch_integrations(**kwargs: Any)

List this guild’s integrations, as a list of Integration. Requires MANAGE_GUILD.

guild.delete_integration

await guild.delete_integration(integration_id: str, **kwargs: Any)

Delete an integration, its webhooks, and kick its bot if it has one. Requires MANAGE_GUILD.

guild.fetch_widget_settings

await guild.fetch_widget_settings(**kwargs: Any)

Fetch this guild’s widget settings. Requires MANAGE_GUILD.

guild.edit_widget

await guild.edit_widget(**kwargs: Any)

Update this guild’s widget settings (enabled, channel_id). Requires MANAGE_GUILD.

guild.fetch_widget

await guild.fetch_widget(**kwargs: Any)

Fetch this guild’s public widget object. No token required if the widget is enabled.

guild.fetch_vanity_url

await guild.fetch_vanity_url(**kwargs: Any)

Fetch this guild’s vanity invite, as a partial Invite (.code is None if unset). Requires MANAGE_GUILD.

guild.fetch_welcome_screen

await guild.fetch_welcome_screen(**kwargs: Any)

Fetch this guild’s welcome screen. Requires MANAGE_GUILD unless the welcome screen is enabled.

guild.edit_welcome_screen

await guild.edit_welcome_screen(**kwargs: Any)

Update this guild’s welcome screen. Requires MANAGE_GUILD.

guild.fetch_onboarding

await guild.fetch_onboarding(**kwargs: Any)

The prompts new members see to pick roles and channels.

guild.edit_onboarding

await guild.edit_onboarding(**kwargs: Any)

Update this guild’s onboarding configuration. Requires MANAGE_GUILD and MANAGE_ROLES.

guild.edit_incident_actions

await guild.edit_incident_actions(**kwargs: Any)

Pause invites and/or DMs for up to 24 hours (raid protection). Requires MANAGE_GUILD.

guild.fetch_member

await guild.fetch_member(user_id: str, **kwargs: Any)

Fetch a single guild Member by user id.

guild.fetch_members

await guild.fetch_members(**kwargs: Any)

List this guild’s members, as a list of Member. Requires the GUILD_MEMBERS privileged intent.

guild.search_members

await guild.search_members(query: str, **kwargs: Any)

Find members whose username or nickname starts with query, as a list of Member.

guild.add_member

await guild.add_member(user_id: str, access_token: str, **kwargs: Any)

Add a user to this guild via an OAuth2 token with the guilds.join scope. Returns the new Member, or None if they were already a member.

guild.edit_member

await guild.edit_member(user_id: str, **kwargs: Any)

Update a member’s nick, roles, mute/deaf, voice channel or timeout. Returns the updated Member.

guild.edit_current_member

await guild.edit_current_member(**kwargs: Any)

Update the bot’s own nick, banner, avatar or bio in this guild.

guild.add_member_role

await guild.add_member_role(user_id: str, role_id: str, **kwargs: Any)

Grant a role to a member. Requires MANAGE_ROLES.

guild.remove_member_role

await guild.remove_member_role(user_id: str, role_id: str, **kwargs: Any)

Remove a role from a member. Requires MANAGE_ROLES.

guild.kick

await guild.kick(user_id: str, **kwargs: Any)

Remove a member from this guild. Requires KICK_MEMBERS.

guild.fetch_roles

await guild.fetch_roles(**kwargs: Any)

List this guild’s roles, as a list of Role.

guild.fetch_role

await guild.fetch_role(role_id: str, **kwargs: Any)

Fetch a single Role by id.

guild.fetch_role_member_counts

await guild.fetch_role_member_counts(**kwargs: Any)

Map of role id to member count, excluding @everyone.

guild.create_role

await guild.create_role(**kwargs: Any)

Create a role in this guild. Returns the new Role. Requires MANAGE_ROLES.

guild.edit_role_positions

await guild.edit_role_positions(positions: Any, **kwargs: Any)

Reorder this guild’s roles. positions is a list of {"id": role_id, "position": int} dicts. Returns every Role in the guild. Requires MANAGE_ROLES.

guild.search_messages

await guild.search_messages(**kwargs: Any)

Full text search across this guild’s messages. Returns a MessageSearchResult. Requires READ_MESSAGE_HISTORY, and possibly the MESSAGE_CONTENT privileged intent.

guild.fetch_webhooks

await guild.fetch_webhooks(**kwargs: Any)

List this guild’s webhooks, as a list of Webhook. Requires MANAGE_WEBHOOKS.

guild.fetch_emojis

await guild.fetch_emojis(**kwargs: Any)

List this guild’s custom emojis, as a list of Emoji.

guild.fetch_emoji

await guild.fetch_emoji(emoji_id: str, **kwargs: Any)

Fetch a single custom emoji by id.

guild.create_emoji

await guild.create_emoji(name: str, image: str, **kwargs: Any)

Upload a new custom emoji (128x128, up to 256 KiB). image is base64 image data. Returns the new Emoji. Requires CREATE_GUILD_EXPRESSIONS.

guild.fetch_stickers

await guild.fetch_stickers(**kwargs: Any)

List this guild’s stickers, as a list of Sticker.

guild.fetch_sticker

await guild.fetch_sticker(sticker_id: str, **kwargs: Any)

Fetch a single guild sticker by id.

guild.create_sticker

await guild.create_sticker(name: str, description: str, tags: str, filename: str,
                           file_bytes: bytes, **kwargs: Any)

Upload a new sticker (PNG, APNG, GIF, or Lottie JSON, up to 512 KiB, 320x320, animated ones under 5 seconds). Returns the new Sticker. Requires CREATE_GUILD_EXPRESSIONS.

guild.fetch_soundboard_sounds

await guild.fetch_soundboard_sounds(**kwargs: Any)

List this guild’s soundboard sounds, as a list of SoundboardSound.

guild.fetch_soundboard_sound

await guild.fetch_soundboard_sound(sound_id: str, **kwargs: Any)

Fetch a single soundboard sound from this guild.

guild.create_soundboard_sound

await guild.create_soundboard_sound(name: str, sound: str, **kwargs: Any)

Add a soundboard sound to this guild. sound is a base64 data URI, same convention as create_emoji’s image. Returns the new SoundboardSound. Requires CREATE_GUILD_EXPRESSIONS/MANAGE_GUILD_EXPRESSIONS.

guild.fetch_scheduled_events

await guild.fetch_scheduled_events(**kwargs: Any)

List this guild’s scheduled events, as a list of GuildScheduledEvent.

guild.create_scheduled_event

await guild.create_scheduled_event(name: str, privacy_level: int, scheduled_start_time: str,
                                   entity_type: int, **kwargs: Any)

Create a scheduled event. entity_type picks the kind (1 stage, 2 voice, 3 external); external events also need channel_id=None, entity_metadata={"location": ...} and scheduled_end_time. Returns the new GuildScheduledEvent.

guild.fetch_scheduled_event

await guild.fetch_scheduled_event(event_id: str, **kwargs: Any)

Fetch a single scheduled event by id.

guild.fetch_auto_moderation_rules

await guild.fetch_auto_moderation_rules(**kwargs: Any)

List this guild’s auto moderation rules, as a list of AutoModerationRule. Requires MANAGE_GUILD.

guild.fetch_auto_moderation_rule

await guild.fetch_auto_moderation_rule(rule_id: str, **kwargs: Any)

Fetch a single auto moderation rule by id. Requires MANAGE_GUILD.

guild.create_auto_moderation_rule

await guild.create_auto_moderation_rule(name: str, event_type: int, trigger_type: int,
                                        actions: Any, **kwargs: Any)

Create an auto moderation rule. Returns the new AutoModerationRule. Requires MANAGE_GUILD.

guild.fetch_templates

await guild.fetch_templates(**kwargs: Any)

List this guild’s templates, as a list of GuildTemplate. Requires MANAGE_GUILD.

guild.create_template

await guild.create_template(name: str, **kwargs: Any)

Create a template from this guild’s current state. Returns the new GuildTemplate. Requires MANAGE_GUILD.

guild.fetch_audit_log

await guild.fetch_audit_log(**kwargs: Any)

Fetch this guild’s audit log, as an AuditLog. Requires VIEW_AUDIT_LOG.

guild.leave

await guild.leave(**kwargs: Any)

Irreversible without a fresh invite.

Guild Template

bot.fetch_template

await bot.fetch_template(code: str, *, token: str | None = None)

A GuildTemplate by its share code. No permission or guild membership needed.

bot.fetch_guild_templates

await bot.fetch_guild_templates(guild_id: str, *, token: str | None = None)

Every template created from this guild. Requires MANAGE_GUILD.

bot.create_guild_template

await bot.create_guild_template(guild_id: str, name: str, *, description: Any = UNSET,
                                token: str | None = None)

A one-off snapshot of the guild, not a live mirror. Requires MANAGE_GUILD.

bot.sync_guild_template

await bot.sync_guild_template(guild_id: str, code: str, *, token: str | None = None)

A template is a one-off snapshot; call this to re-snapshot it against the guild’s current state.

bot.edit_guild_template

await bot.edit_guild_template(guild_id: str, code: str, *, name: Any = UNSET,
                              description: Any = UNSET, token: str | None = None)

Changes the name/description only. Use sync_guild_template to refresh the snapshot.

bot.delete_guild_template

await bot.delete_guild_template(guild_id: str, code: str, *, token: str | None = None)

Returns the deleted GuildTemplate.

Invite

bot.fetch_invite

await bot.fetch_invite(code: str, *, with_counts: bool | None = None,
                       guild_scheduled_event_id: str | None = None, token: str | None = None)

Fetches an invite by its code. with_counts adds approximate member and presence counts; guild_scheduled_event_id attaches a scheduled event to the returned invite so a client can offer to add it to the joiner’s calendar.

bot.delete_invite

await bot.delete_invite(code: str, *, token: str | None = None)

Requires MANAGE_CHANNELS on the channel, or MANAGE_GUILD. Returns the deleted Invite.

bot.fetch_invite_target_users

await bot.fetch_invite_target_users(code: str, *, token: str | None = None)

Returns the raw CSV body Discord sends back, not a parsed list - there’s no documented column schema to parse it against.

bot.edit_invite_target_users

await bot.edit_invite_target_users(code: str, filename: str, file_bytes: bytes, *,
                                   token: str | None = None)

Replaces the invite’s whole target user allowlist with the users listed in the given CSV file.

bot.fetch_invite_target_users_job_status

await bot.fetch_invite_target_users_job_status(code: str, *, token: str | None = None)

Fetches the processing status of the CSV uploaded through edit_invite_target_users.

Member

A guild member, e.g. ctx.member (None in DMs). .nick, .roles, .permissions, and any other field Discord sends are available as attributes.

bot.fetch_guild_member

await bot.fetch_guild_member(guild_id: str, user_id: str, *, token: str | None = None)

One Member; NotFound if the user isn’t in the guild.

bot.fetch_guild_members

await bot.fetch_guild_members(guild_id: str, *, limit: int | None = None,
                              after: str | None = None, token: str | None = None)

Fetches a page of the guild’s members, ordered by user id. Requires the Server Members intent.

bot.search_guild_members

await bot.search_guild_members(guild_id: str, query: str, *, limit: int | None = None,
                               token: str | None = None)

Fetches guild members whose username or nickname starts with query. Unlike fetch_guild_members, this doesn’t need the Server Members intent.

bot.add_guild_member

await bot.add_guild_member(guild_id: str, user_id: str, access_token: str, *, nick: Any = UNSET,
                           roles: Any = UNSET, mute: Any = UNSET, deaf: Any = UNSET,
                           token: str | None = None)

Returns the added Member, or None if the user was already a member (Discord returns 204 with no body in that case).

bot.edit_guild_member

await bot.edit_guild_member(guild_id: str, user_id: str, *, nick: Any = UNSET,
                            roles: Any = UNSET, mute: Any = UNSET, deaf: Any = UNSET,
                            channel_id: Any = UNSET, communication_disabled_until: Any = UNSET,
                            flags: Any = UNSET, reason: str | None = None,
                            token: str | None = None)

nick, channel_id and communication_disabled_until can all be cleared by passing None explicitly.

bot.edit_current_member

await bot.edit_current_member(guild_id: str, *, nick: Any = UNSET, banner: Any = UNSET,
                              avatar: Any = UNSET, bio: Any = UNSET, token: str | None = None)

Edits the bot’s own guild profile: nickname, per-guild banner and avatar, and bio.

bot.remove_guild_member

await bot.remove_guild_member(guild_id: str, user_id: str, *, reason: str | None = None,
                              token: str | None = None)

Requires KICK_MEMBERS. The member can rejoin with a new invite.

bot.add_role

await bot.add_role(guild_id: str, user_id: str, role_id: str, *, reason: str | None = None)

Grant a role to a guild member. Requires DISCORD_BOT_TOKEN. Same as add_guild_member_role, kept under its older name.

bot.remove_role

await bot.remove_role(guild_id: str, user_id: str, role_id: str, *, reason: str | None = None)

Remove a role from a guild member. Requires DISCORD_BOT_TOKEN. Same as remove_guild_member_role, kept under its older name.

member.edit

await member.edit(**kwargs: Any)

Update this member’s nick, roles, mute/deaf, voice channel or timeout. Returns the updated Member.

member.add_role

await member.add_role(role_id: str, **kwargs: Any)

Grant this member a role. Requires MANAGE_ROLES.

member.remove_role

await member.remove_role(role_id: str, **kwargs: Any)

Remove a role from this member. Requires MANAGE_ROLES.

member.kick

await member.kick(**kwargs: Any)

Remove this member from the guild. Requires KICK_MEMBERS.

member.timeout

await member.timeout(until: Any, **kwargs: Any)

Time this member out until an ISO 8601 timestamp (up to 28 days out), or pass None to clear an existing timeout. Requires MODERATE_MEMBERS.

Role

A Discord role, e.g. ctx.resolved_roles[role_id] from a RoleSelect or MentionableSelect pick. .id, .name, .color, .permissions, and any other field Discord sends are available as attributes.

bot.add_guild_member_role

await bot.add_guild_member_role(guild_id: str, user_id: str, role_id: str, *,
                                reason: str | None = None, token: str | None = None)

Requires MANAGE_ROLES and a higher role than the one being granted.

bot.remove_guild_member_role

await bot.remove_guild_member_role(guild_id: str, user_id: str, role_id: str, *,
                                   reason: str | None = None, token: str | None = None)

Requires MANAGE_ROLES.

bot.fetch_guild_roles

await bot.fetch_guild_roles(guild_id: str, *, token: str | None = None)

Every Role in the guild, including @everyone.

bot.fetch_guild_role

await bot.fetch_guild_role(guild_id: str, role_id: str, *, token: str | None = None)

One Role by id.

bot.fetch_guild_role_member_counts

await bot.fetch_guild_role_member_counts(guild_id: str, *, token: str | None = None)

Maps role id to member count. Doesn’t include @everyone.

bot.create_guild_role

await bot.create_guild_role(guild_id: str, *, name: Any = UNSET, permissions: Any = UNSET,
                            color: Any = UNSET, colors: Any = UNSET, hoist: Any = UNSET,
                            icon: Any = UNSET, unicode_emoji: Any = UNSET,
                            mentionable: Any = UNSET, reason: str | None = None,
                            token: str | None = None)

Creates a new role. Its position starts at the bottom of the hierarchy, below the bot’s own highest role, use edit_guild_role_positions to move it.

bot.edit_guild_role_positions

await bot.edit_guild_role_positions(guild_id: str, positions: Any, *, reason: str | None = None,
                                    token: str | None = None)

Reorders roles in the guild. positions is a list of {“id”: role_id, “position”: int} dicts; roles left out keep their current position.

bot.edit_guild_role

await bot.edit_guild_role(guild_id: str, role_id: str, *, name: Any = UNSET,
                          permissions: Any = UNSET, color: Any = UNSET, colors: Any = UNSET,
                          hoist: Any = UNSET, icon: Any = UNSET, unicode_emoji: Any = UNSET,
                          mentionable: Any = UNSET, reason: str | None = None,
                          token: str | None = None)

Partial update: pass only the fields to change.

bot.delete_guild_role

await bot.delete_guild_role(guild_id: str, role_id: str, *, reason: str | None = None,
                            token: str | None = None)

Requires MANAGE_ROLES. Every member loses the role.

role.edit

await role.edit(**kwargs: Any)

Update this role. Returns the updated Role. Requires MANAGE_ROLES.

role.delete

await role.delete(**kwargs: Any)

Delete this role. Requires MANAGE_ROLES.

Message

A Discord message, e.g. ctx.message (the message a component sits on). .id, .content, .embeds, and any other field Discord sends are available as attributes.

bot.fetch_channel_messages

await bot.fetch_channel_messages(channel_id: str, *, around: str | None = None,
                                 before: str | None = None, after: str | None = None,
                                 limit: int | None = None, token: str | None = None)

around/before/after are mutually exclusive; each anchors the page on a different message id.

bot.fetch_message

await bot.fetch_message(channel_id: str, message_id: str, *, token: str | None = None)

The full Message. For a page of recent messages use fetch_channel_messages.

bot.crosspost_message

await bot.crosspost_message(channel_id: str, message_id: str, *, token: str | None = None)

Announcement channels only. Returns the crossposted Message.

bot.bulk_delete_messages

await bot.bulk_delete_messages(channel_id: str, message_ids: Any, *, token: str | None = None)

Guild channels only, and nothing older than two weeks. Requires MANAGE_MESSAGES.

bot.create_reaction

await bot.create_reaction(channel_id: str, message_id: str, emoji: str, *,
                          token: str | None = None)

Needs ADD_REACTIONS unless someone has already reacted with this emoji.

bot.delete_own_reaction

await bot.delete_own_reaction(channel_id: str, message_id: str, emoji: str, *,
                              token: str | None = None)

Removes just the bot’s own reaction; needs no permission.

bot.delete_user_reaction

await bot.delete_user_reaction(channel_id: str, message_id: str, emoji: str, user_id: str, *,
                               token: str | None = None)

Requires MANAGE_MESSAGES.

bot.fetch_reactions

await bot.fetch_reactions(channel_id: str, message_id: str, emoji: str, *,
                          type: int | None = None, after: str | None = None,
                          limit: int | None = None, token: str | None = None)

type=1 selects super (burst) reactions instead of normal ones.

bot.delete_all_reactions

await bot.delete_all_reactions(channel_id: str, message_id: str, *, token: str | None = None)

Requires MANAGE_MESSAGES.

bot.delete_all_reactions_for_emoji

await bot.delete_all_reactions_for_emoji(channel_id: str, message_id: str, emoji: str, *,
                                         token: str | None = None)

Requires MANAGE_MESSAGES. Leaves other emoji’s reactions in place.

bot.fetch_poll_answer_voters

await bot.fetch_poll_answer_voters(channel_id: str, message_id: str, answer_id: str, *,
                                   after: str | None = None, limit: int | None = None,
                                   token: str | None = None)

The User list that voted for one poll answer, paginated by user id.

bot.expire_poll

await bot.expire_poll(channel_id: str, message_id: str, *, token: str | None = None)

Ends the poll now rather than at its scheduled time. Returns the updated Message.

bot.search_guild_messages

await bot.search_guild_messages(guild_id: str, *, limit: Any = None, offset: Any = None,
                                max_id: Any = None, min_id: Any = None, slop: Any = None,
                                content: Any = None, channel_id: Any = None,
                                author_type: Any = None, author_id: Any = None,
                                mentions: Any = None, mentions_role_id: Any = None,
                                mention_everyone: Any = None, replied_to_user_id: Any = None,
                                replied_to_message_id: Any = None, pinned: Any = None,
                                has: Any = None, embed_type: Any = None,
                                embed_provider: Any = None, link_hostname: Any = None,
                                attachment_filename: Any = None,
                                attachment_extension: Any = None, sort_by: Any = None,
                                sort_order: Any = None, include_nsfw: Any = None,
                                token: str | None = None)

Preview endpoint. Requires READ_MESSAGE_HISTORY and, per your app’s config, the MESSAGE_CONTENT intent. Results may come back empty while Discord is still indexing the guild. Any array field accepts a list.

bot.send_message

await bot.send_message(channel_id: str, content: Any = None, *, embeds: Any = None,
                       components: Any = None, files: Any = None)

Send a message as the bot. Requires DISCORD_BOT_TOKEN, callable from anywhere with no interaction to respond to, typically cron handlers. files is a list of (filename, bytes) tuples, same as ctx.send/ctx.edit. Returns the sent Message. For replies, polls, stickers or other fields Create Message supports, use channel.send() instead.

bot.edit_message

await bot.edit_message(channel_id: str, message_id: str, content: Any = None, *,
                       embeds: Any = None, components: Any = None, files: Any = None)

Edit a message the bot previously sent. Requires DISCORD_BOT_TOKEN. files is a list of (filename, bytes) tuples, same as ctx.send/ctx.edit. Returns the edited Message. content/embeds/components left at their default here just leave that field untouched, they can’t be cleared through this method, use message.edit(field=None) for that.

bot.delete_message

await bot.delete_message(channel_id: str, message_id: str)

Delete a message. Requires DISCORD_BOT_TOKEN.

message.pin

await message.pin(**kwargs: Any)

Pin this message in its channel. Requires PIN_MESSAGES.

message.unpin

await message.unpin(**kwargs: Any)

Unpin this message. Requires PIN_MESSAGES.

message.fetch

await message.fetch(**kwargs: Any)

ctx.message is partial; this returns the complete Message.

message.edit

await message.edit(**kwargs: Any)

Edit this message (only the original author can change content/embeds/components; anyone with MANAGE_MESSAGES can change flags). Nullable fields can be cleared by passing None. Returns the updated Message.

message.delete

await message.delete(**kwargs: Any)

Anyone else’s message needs MANAGE_MESSAGES.

message.crosspost

await message.crosspost(**kwargs: Any)

Publish this message from an announcement channel to its following channels. Returns the updated Message.

message.reply

await message.reply(**kwargs: Any)

Send a new message that replies to this one. Same fields as channel.send(). Returns the sent Message.

message.add_reaction

await message.add_reaction(emoji: str, **kwargs: Any)

React to this message as the bot. emoji is a unicode emoji, or name:id for a custom one. Requires (unless someone already reacted with it) ADD_REACTIONS.

message.remove_reaction

await message.remove_reaction(emoji: str, user_id: str | None = None, **kwargs: Any)

Remove a reaction. Removes the bot’s own by default; pass user_id to remove someone else’s, which needs MANAGE_MESSAGES.

message.fetch_reactions

await message.fetch_reactions(emoji: str, **kwargs: Any)

List the users who reacted with a given emoji, as a list of User.

message.clear_reactions

await message.clear_reactions(emoji: str | None = None, **kwargs: Any)

Remove every reaction from this message, or every reaction for one emoji if emoji is given. Requires MANAGE_MESSAGES.

message.fetch_poll_answer_voters

await message.fetch_poll_answer_voters(answer_id: str, **kwargs: Any)

List the users who voted for one answer on this message’s poll, as a list of User.

message.expire_poll

await message.expire_poll(**kwargs: Any)

End this message’s poll now, instead of waiting for its normal expiry. Returns the updated Message.

Scheduled Event

bot.fetch_guild_scheduled_events

await bot.fetch_guild_scheduled_events(guild_id: str, *, with_user_count: bool = False,
                                       token: str | None = None)

Fetches every scheduled event in the guild, including ones that have already ended.

bot.create_guild_scheduled_event

await bot.create_guild_scheduled_event(guild_id: str, name: str, privacy_level: int,
                                       scheduled_start_time: str, entity_type: int, *,
                                       channel_id: Any = UNSET, entity_metadata: Any = UNSET,
                                       scheduled_end_time: Any = UNSET, description: Any = UNSET,
                                       image: Any = UNSET, recurrence_rule: Any = UNSET,
                                       token: str | None = None)

channel_id and entity_metadata are optional for entity_type EXTERNAL, scheduled_end_time is required for it.

bot.fetch_guild_scheduled_event

await bot.fetch_guild_scheduled_event(guild_id: str, event_id: str, *,
                                      with_user_count: bool = False, token: str | None = None)

One GuildScheduledEvent by id.

bot.edit_guild_scheduled_event

await bot.edit_guild_scheduled_event(guild_id: str, event_id: str, *, channel_id: Any = UNSET,
                                     entity_metadata: Any = UNSET, name: Any = UNSET,
                                     privacy_level: Any = UNSET,
                                     scheduled_start_time: Any = UNSET,
                                     scheduled_end_time: Any = UNSET, description: Any = UNSET,
                                     entity_type: Any = UNSET, status: Any = UNSET,
                                     image: Any = UNSET, recurrence_rule: Any = UNSET,
                                     token: str | None = None)

Set status to start/end the event. Switching entity_type to EXTERNAL requires channel_id=None, entity_metadata with a location, and scheduled_end_time all in the same call.

bot.delete_guild_scheduled_event

await bot.delete_guild_scheduled_event(guild_id: str, event_id: str, *, token: str | None = None)

Requires MANAGE_EVENTS.

bot.fetch_guild_scheduled_event_users

await bot.fetch_guild_scheduled_event_users(guild_id: str, event_id: str, *,
                                            limit: int | None = None, with_member: bool = False,
                                            before: str | None = None, after: str | None = None,
                                            token: str | None = None)

The GuildScheduledEventUser list, paginated by user id.

SKU & Subscription

bot.fetch_skus

await bot.fetch_skus(application_id: str, *, token: str | None = None)

Every SKU (subscription tier or one-time purchase) the app sells.

bot.fetch_sku_subscriptions

await bot.fetch_sku_subscriptions(sku_id: str, *, before: str | None = None,
                                  after: str | None = None, limit: int | None = None,
                                  user_id: str | None = None, token: str | None = None)

user_id is required unless the request carries an OAuth2 token for that user (a bot token never does), so in practice always pass it.

bot.fetch_sku_subscription

await bot.fetch_sku_subscription(sku_id: str, subscription_id: str, *,
                                 user_id: str | None = None, token: str | None = None)

One Subscription by id. Pass user_id, same as fetch_sku_subscriptions.

Soundboard

bot.send_soundboard_sound

await bot.send_soundboard_sound(channel_id: str, sound_id: str, *, source_guild_id: Any = UNSET,
                                token: str | None = None)

Bot must be connected to the voice channel. Requires SPEAK and USE_SOUNDBOARD, plus USE_EXTERNAL_SOUNDS to play a sound owned by another guild via source_guild_id.

bot.fetch_default_soundboard_sounds

await bot.fetch_default_soundboard_sounds(*, token: str | None = None)

Fetches the soundboard sounds Discord provides for free, available to every guild.

bot.fetch_guild_soundboard_sounds

await bot.fetch_guild_soundboard_sounds(guild_id: str, *, token: str | None = None)

Fetches every custom soundboard sound uploaded to the guild.

bot.fetch_guild_soundboard_sound

await bot.fetch_guild_soundboard_sound(guild_id: str, sound_id: str, *, token: str | None = None)

One guild SoundboardSound by id.

bot.create_guild_soundboard_sound

await bot.create_guild_soundboard_sound(guild_id: str, name: str, sound: str, *,
                                        volume: Any = UNSET, emoji_id: Any = UNSET,
                                        emoji_name: Any = UNSET, reason: str | None = None,
                                        token: str | None = None)

sound is a base64 data URI, same convention as create_guild_emoji’s image.

bot.edit_guild_soundboard_sound

await bot.edit_guild_soundboard_sound(guild_id: str, sound_id: str, *, name: Any = UNSET,
                                      volume: Any = UNSET, emoji_id: Any = UNSET,
                                      emoji_name: Any = UNSET, reason: str | None = None,
                                      token: str | None = None)

Edits an existing guild soundboard sound. The sound itself can’t be changed after upload, delete and recreate instead.

bot.delete_guild_soundboard_sound

await bot.delete_guild_soundboard_sound(guild_id: str, sound_id: str, *,
                                        reason: str | None = None, token: str | None = None)

Requires MANAGE_GUILD_EXPRESSIONS, or being the sound’s creator.

Stage Instance

bot.create_stage_instance

await bot.create_stage_instance(channel_id: str, topic: str, *, privacy_level: Any = UNSET,
                                send_start_notification: Any = UNSET,
                                guild_scheduled_event_id: Any = UNSET, token: str | None = None)

Takes a stage channel live. The bot must be a speaker or moderator on it.

bot.fetch_stage_instance

await bot.fetch_stage_instance(channel_id: str, *, token: str | None = None)

Raises NotFound if the stage isn’t live.

bot.edit_stage_instance

await bot.edit_stage_instance(channel_id: str, *, topic: Any = UNSET, privacy_level: Any = UNSET,
                              token: str | None = None)

Change a live stage’s topic or privacy level. Requires stage moderator permissions.

bot.delete_stage_instance

await bot.delete_stage_instance(channel_id: str, *, token: str | None = None)

Ends the live stage.

Sticker

bot.fetch_sticker

await bot.fetch_sticker(sticker_id: str, *, token: str | None = None)

One Sticker by id, guild or Nitro-pack alike.

bot.fetch_sticker_packs

await bot.fetch_sticker_packs(*, token: str | None = None)

Discord’s built-in Nitro sticker packs.

bot.fetch_sticker_pack

await bot.fetch_sticker_pack(pack_id: str, *, token: str | None = None)

One StickerPack by id.

bot.fetch_guild_stickers

await bot.fetch_guild_stickers(guild_id: str, *, token: str | None = None)

Every custom Sticker in the guild.

bot.fetch_guild_sticker

await bot.fetch_guild_sticker(guild_id: str, sticker_id: str, *, token: str | None = None)

One guild Sticker by id.

bot.create_guild_sticker

await bot.create_guild_sticker(guild_id: str, name: str, description: str, tags: str,
                               filename: str, file_bytes: bytes, *, token: str | None = None)

Unlike every other create/edit call in this package, Discord wants a plain multipart form here (name/description/tags as ordinary fields, the file as file), not the payload_json + files[n] attachment convention - see _multipart.build_form_multipart_body.

bot.edit_guild_sticker

await bot.edit_guild_sticker(guild_id: str, sticker_id: str, *, name: Any = UNSET,
                             description: Any = UNSET, tags: Any = UNSET,
                             token: str | None = None)

Edits an existing guild sticker’s name, description or tags. The image itself can’t be changed after upload, delete and recreate instead.

bot.delete_guild_sticker

await bot.delete_guild_sticker(guild_id: str, sticker_id: str, *, token: str | None = None)

Requires MANAGE_GUILD_EXPRESSIONS, or being the sticker’s creator.

Thread

bot.start_thread_from_message

await bot.start_thread_from_message(channel_id: str, message_id: str, name: str, *,
                                    auto_archive_duration: int | None = None,
                                    token: str | None = None)

Starts a public thread from an existing message. The thread shares the message’s id, and the message’s author is added to it automatically.

bot.start_thread_without_message

await bot.start_thread_without_message(channel_id: str, name: str, *, thread_type: int = 11,
                                       invitable: bool | None = None, token: str | None = None)

Starts a thread with no starter message. thread_type defaults to 11 (a public thread); pass 12 for a private one. invitable only applies to private threads, and controls whether non-moderators can add other members.

bot.start_thread_from_forum

await bot.start_thread_from_forum(channel_id: str, name: str, *, message: str,
                                  applied_tags: list[str] | None = None,
                                  auto_archive_duration: int | None = None,
                                  rate_limit_per_user: int | None = None,
                                  token: str | None = None,
                                  files: list[tuple[str, bytes]] | None = None)

Starts a new post in a forum or media channel. The post itself is both the thread and its first message, built from the message argument the same way create_message builds one.

bot.join_thread

await bot.join_thread(channel_id: str, *, token: str | None = None)

No-op if the bot is already in the thread.

bot.leave_thread

await bot.leave_thread(channel_id: str, *, token: str | None = None)

The bot stops receiving the thread’s messages.

bot.add_thread_member

await bot.add_thread_member(channel_id: str, user_id: str, *, token: str | None = None)

Needs the bot to be in the thread, and SEND_MESSAGES_IN_THREADS for a private one.

bot.remove_thread_member

await bot.remove_thread_member(channel_id: str, user_id: str, *, token: str | None = None)

Requires MANAGE_THREADS, or thread ownership for a private thread.

bot.fetch_thread_member

await bot.fetch_thread_member(channel_id: str, user_id: str, *, with_member: bool = False,
                              token: str | None = None)

Fetches a single thread member. with_member also attaches that user’s guild member object.

bot.fetch_thread_members

await bot.fetch_thread_members(channel_id: str, *, with_member: bool = False,
                               after: str | None = None, limit: int | None = None,
                               token: str | None = None)

after/limit only take effect when with_member=True - Discord ignores them otherwise and always returns every member in one page.

bot.fetch_public_archived_threads

await bot.fetch_public_archived_threads(channel_id: str, *, before: str | None = None,
                                        limit: int | None = None, token: str | None = None)

Fetches a page of the channel’s archived public threads, newest archived first.

bot.fetch_private_archived_threads

await bot.fetch_private_archived_threads(channel_id: str, *, before: str | None = None,
                                         limit: int | None = None, token: str | None = None)

Fetches a page of the channel’s archived private threads. Requires MANAGE_THREADS, unless fetching only threads the bot has joined via fetch_joined_private_archived_threads instead.

bot.fetch_joined_private_archived_threads

await bot.fetch_joined_private_archived_threads(channel_id: str, *, before: str | None = None,
                                                limit: int | None = None,
                                                token: str | None = None)

Fetches a page of the channel’s archived private threads the bot has joined. Unlike fetch_private_archived_threads, this doesn’t need MANAGE_THREADS.

bot.fetch_active_guild_threads

await bot.fetch_active_guild_threads(guild_id: str, *, token: str | None = None)

Fetches every active (non-archived) thread in the guild, across every channel.

User

A Discord user, e.g. ctx.user. .id, .username, .global_name, .bot, and any other field Discord sends are available as attributes - not modeled explicitly here, since they’re resolved dynamically off the raw payload by DiscordObject.__getattr__.

bot.fetch_current_user

await bot.fetch_current_user(*, token: str | None = None)

The bot’s own User.

bot.fetch_user

await bot.fetch_user(user_id: str, *, token: str | None = None)

Any User by id; works without sharing a guild.

bot.edit_current_user

await bot.edit_current_user(*, username: Any = UNSET, avatar: Any = UNSET, banner: Any = UNSET,
                            token: str | None = None)

Heavily rate limited (roughly twice an hour).

bot.fetch_current_user_guilds

await bot.fetch_current_user_guilds(*, before: str | None = None, after: str | None = None,
                                    limit: int | None = None, with_counts: bool = False,
                                    token: str | None = None)

A page of partial Guild objects. with_counts adds approximate member/presence counts.

bot.leave_guild

await bot.leave_guild(guild_id: str, *, token: str | None = None)

Irreversible without a fresh invite.

bot.create_dm

await bot.create_dm(recipient_id: str, *, token: str | None = None)

Opens a DM channel with a user, or returns the existing one if there already is one. Sending a message doesn’t need this to be called first, only useful when the channel id itself is needed ahead of time.

user.fetch

await user.fetch(**kwargs: Any)

Re-fetch this user by id. Returns a fresh User.

user.create_dm

await user.create_dm(**kwargs: Any)

Open (or fetch the existing) DM channel with this user. Returns the DM Channel.

Voice

bot.fetch_voice_regions

await bot.fetch_voice_regions(*, token: str | None = None)

Every voice region Discord offers globally. For a guild’s own list use guild.fetch_voice_regions().

bot.fetch_guild_current_voice_state

await bot.fetch_guild_current_voice_state(guild_id: str, *, token: str | None = None)

The bot’s VoiceState in this guild; NotFound if it isn’t connected.

bot.fetch_guild_member_voice_state

await bot.fetch_guild_member_voice_state(guild_id: str, user_id: str, *, token: str | None = None)

A member’s VoiceState in this guild; NotFound if they aren’t connected.

bot.edit_guild_current_voice_state

await bot.edit_guild_current_voice_state(guild_id: str, *, channel_id: Any = UNSET,
                                         suppress: Any = UNSET,
                                         request_to_speak_timestamp: Any = UNSET,
                                         token: str | None = None)

The bot must already be connected to a stage channel before suppress or request_to_speak_timestamp will take.

bot.edit_guild_member_voice_state

await bot.edit_guild_member_voice_state(guild_id: str, user_id: str, *, channel_id: Any = UNSET,
                                        suppress: Any = UNSET, token: str | None = None)

Stage channels only. suppress=False moves the user to speaker, suppress=True back to the audience. Requires MUTE_MEMBERS.

Webhook

bot.fetch_channel_webhooks

await bot.fetch_channel_webhooks(channel_id: str, *, token: str | None = None)

Every Webhook on the channel. Requires MANAGE_WEBHOOKS.

bot.fetch_guild_webhooks

await bot.fetch_guild_webhooks(guild_id: str, *, token: str | None = None)

Every Webhook in the guild. Requires MANAGE_WEBHOOKS.

bot.fetch_webhook

await bot.fetch_webhook(webhook_id: str, *, token: str | None = None)

One Webhook by id, token included.

bot.edit_webhook

await bot.edit_webhook(webhook_id: str, *, name: Any = UNSET, avatar: Any = UNSET,
                       channel_id: Any = UNSET, reason: str | None = None,
                       token: str | None = None)

Requires MANAGE_WEBHOOKS; moving channels needs it on both.

bot.execute_webhook

await bot.execute_webhook(webhook_id: str, webhook_token: str | None = None, content: Any = None,
                          *, embeds: Any = None, components: Any = None, files: Any = None,
                          username: str | None = None, avatar_url: str | None = None,
                          tts: bool = False, allowed_mentions: Any = None, wait: bool = False,
                          thread_id: str | None = None)

Send a message through a Discord webhook. No bot token required.

Pass a full webhook URL as webhook_id (leave webhook_token unset), or the id and token separately.

bot.edit_webhook_message

await bot.edit_webhook_message(webhook_id: str, webhook_token: str | None = None,
                               message_id: str = "@original", content: Any = None, *,
                               embeds: Any = None, components: Any = None, files: Any = None,
                               allowed_mentions: Any = None)

Edit a message previously sent through a webhook. No bot token required.

bot.delete_webhook_message

await bot.delete_webhook_message(webhook_id: str, webhook_token: str | None = None,
                                 message_id: str = "@original")

Delete a message previously sent through a webhook. No bot token required.

bot.fetch_webhook_message

await bot.fetch_webhook_message(webhook_id: str, webhook_token: str | None = None,
                                message_id: str = "@original")

Fetch a message previously sent through a webhook. No bot token required.

bot.fetch_webhook_with_token

await bot.fetch_webhook_with_token(webhook_id: str, webhook_token: str | None = None)

Fetch a webhook using its own token rather than DISCORD_BOT_TOKEN. The returned object omits the owning user, unlike fetch_webhook.

bot.edit_webhook_with_token

await bot.edit_webhook_with_token(webhook_id: str, webhook_token: str | None = None, *,
                                  name: str | ellipsis = Ellipsis,
                                  avatar: str | None | ellipsis = Ellipsis)

Rename a webhook or change its avatar using its own token rather than DISCORD_BOT_TOKEN. Unlike edit_webhook, this can’t move it to a different channel. avatar can be cleared by passing None.

bot.execute_slack_webhook

await bot.execute_slack_webhook(webhook_id: str, webhook_token: str | None = None,
                                payload: Any = None, *, wait: bool = False,
                                thread_id: str | None = None)

Post a Slack-formatted payload through a webhook. No bot token required. Discord’s Slack-compatible endpoint replies with the plain text “ok” rather than a message body, so unlike execute_webhook this returns that raw text with wait=True, not a parsed message.

bot.execute_github_webhook

await bot.execute_github_webhook(webhook_id: str, webhook_token: str | None = None,
                                 payload: Any = None, *, wait: bool = False,
                                 thread_id: str | None = None)

Post a GitHub-formatted payload through a webhook. No bot token required.

bot.create_webhook

await bot.create_webhook(channel_id: str, name: str, avatar: Any = None, *,
                         reason: str | None = None)

Create a webhook in a channel. Requires DISCORD_BOT_TOKEN. Returns the webhook object, including the id/token pair execute_webhook needs.

bot.get_channel_webhooks

await bot.get_channel_webhooks(channel_id: str)

List a channel’s webhooks. Requires DISCORD_BOT_TOKEN.

bot.delete_webhook

await bot.delete_webhook(webhook_id: str, webhook_token: str | None = None, *,
                         reason: str | None = None)

Delete a webhook. With webhook_token, authenticates with the webhook’s own token (no bot token needed); otherwise uses DISCORD_BOT_TOKEN. reason only takes effect on the bot-token path - webhook.py’s token-authenticated request helper doesn’t send that header at all.