# Table of Contents - [Welcome to discord.py-self](#welcome-to-discord-py-self) - [Welcome to discord.py-self](#welcome-to-discord-py-self) - [Welcome to discord.py-self](#welcome-to-discord-py-self) - [Welcome to discord.py-self](#welcome-to-discord-py-self) - [Frequently Asked Questions](#frequently-asked-questions) - [Migrating to This Library](#migrating-to-this-library) - [Introduction](#introduction) - [Quickstart](#quickstart) - [Authenticating](#authenticating) - [Setting Up Logging](#setting-up-logging) - [Guild Subscriptions](#guild-subscriptions) - [Search](#search) - [discord.ext.commands – Bot commands framework](#discord-ext-commands-bot-commands-framework) - [discord.ext.tasks – asyncio.Task helpers](#discord-ext-tasks-asyncio-task-helpers) - [Changelog](#changelog) - [Version Guarantees](#version-guarantees) - [Frequently Asked Questions](#frequently-asked-questions) - [Introduction](#introduction) - [Migrating to This Library](#migrating-to-this-library) - [Guild Subscriptions](#guild-subscriptions) - [Quickstart](#quickstart) - [Setting Up Logging](#setting-up-logging) - [Authenticating](#authenticating) - [discord.ext.commands – Bot commands framework](#discord-ext-commands-bot-commands-framework) - [discord.ext.tasks – asyncio.Task helpers](#discord-ext-tasks-asyncio-task-helpers) - [Search](#search) - [Migrating to This Library](#migrating-to-this-library) - [Changelog](#changelog) - [Version Guarantees](#version-guarantees) - [Frequently Asked Questions](#frequently-asked-questions) - [Migrating to This Library](#migrating-to-this-library) - [Frequently Asked Questions](#frequently-asked-questions) - [Introduction](#introduction) - [Quickstart](#quickstart) - [Guild Subscriptions](#guild-subscriptions) - [Setting Up Logging](#setting-up-logging) - [Authenticating](#authenticating) - [Search](#search) - [discord.ext.commands – Bot commands framework](#discord-ext-commands-bot-commands-framework) - [discord.ext.tasks – asyncio.Task helpers](#discord-ext-tasks-asyncio-task-helpers) - [Version Guarantees](#version-guarantees) - [Changelog](#changelog) - [Setting Up Logging](#setting-up-logging) - [Quickstart](#quickstart) - [Introduction](#introduction) - [Tokens](#tokens) - [discord.ext.tasks – asyncio.Task helpers](#discord-ext-tasks-asyncio-task-helpers) - [discord.ext.commands – Bot commands framework](#discord-ext-commands-bot-commands-framework) - [Search](#search) - [Changelog](#changelog) - [API Reference](#api-reference) - [Migrating to v2.0](#migrating-to-v2-0) - [Index](#index) - [Migrating to v2.0](#migrating-to-v2-0) - [Version Guarantees](#version-guarantees) - [Migrating to v2.0](#migrating-to-v2-0) - [Index](#index) --- # Welcome to discord.py-self View Documentation For discord discord.ext.commands discord.ext.tasks search settings Welcome to discord.py-self[¶](https://discordpy-self.readthedocs.io/en/latest/index.html#welcome-to-discord-py-self "Permalink to this headline") ================================================================================================================================================== ![_images/snake.svg](https://discordpy-self.readthedocs.io/en/latest/_images/snake.svg)![_images/snake_dark.svg](https://discordpy-self.readthedocs.io/en/latest/_images/snake_dark.svg) discord.py-self is a modern, easy to use, feature-rich, and async ready API wrapper for the Discord user APIs. **Features:** * Modern Pythonic API using `async`/`await` syntax * Sane rate limit handling that prevents 429s * Command extension to aid with bot creation * Easy to use with an object oriented design * Optimised for both speed and memory * Prevents detection of user account automation Getting started[¶](https://discordpy-self.readthedocs.io/en/latest/index.html#getting-started "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------------- Is this your first time using the library? This is the place to get started! * **Migrating from discord.py:** [Migrating to This Library](https://discordpy-self.readthedocs.io/en/latest/migrating_from_dpy.html) * **First steps:** [Introduction](https://discordpy-self.readthedocs.io/en/latest/intro.html) | [Quickstart](https://discordpy-self.readthedocs.io/en/latest/quickstart.html) | [Setting Up Logging](https://discordpy-self.readthedocs.io/en/latest/logging.html) * **Working with Discord:** [Authenticating](https://discordpy-self.readthedocs.io/en/latest/authenticating.html) | [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/latest/guild_subscriptions.html) * **Examples:** Many examples are available in the [repository](https://github.com/dolfies/discord.py-self/tree/master/examples) **Obligatory note:** Automating user accounts is against the Discord ToS. If what you are trying to do is accomplishable with a bot account, please use one. Getting help[¶](https://discordpy-self.readthedocs.io/en/latest/index.html#getting-help "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------- If you’re having trouble with something, these resources might help. * Try the [Frequently Asked Questions](https://discordpy-self.readthedocs.io/en/latest/faq.html) first, it’s got answers to all common questions. * If you’re looking for something specific, try the [index](https://discordpy-self.readthedocs.io/en/latest/genindex.html) or [searching](https://discordpy-self.readthedocs.io/en/latest/search.html) . * Report bugs in the [issue tracker](https://github.com/dolfies/discord.py-self/issues) . * Ask in our [GitHub discussions page](https://github.com/dolfies/discord.py-self/discussions) . Extensions[¶](https://discordpy-self.readthedocs.io/en/latest/index.html#extensions "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------ These extensions help you during development when it comes to common tasks. * [`discord.ext.commands` – Bot commands framework](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html) * [`discord.ext.tasks` – asyncio.Task helpers](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html) Manuals[¶](https://discordpy-self.readthedocs.io/en/latest/index.html#manuals "Permalink to this headline") ------------------------------------------------------------------------------------------------------------ These pages go into great detail about everything the API can do. * [API Reference](https://discordpy-self.readthedocs.io/en/latest/api.html) * [discord.ext.commands API Reference](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html) * [discord.ext.tasks API Reference](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html) Meta[¶](https://discordpy-self.readthedocs.io/en/latest/index.html#meta "Permalink to this headline") ------------------------------------------------------------------------------------------------------ If you’re looking for something related to the project itself, it’s here. * [Changelog](https://discordpy-self.readthedocs.io/en/latest/whats_new.html) * [Version Guarantees](https://discordpy-self.readthedocs.io/en/latest/version_guarantees.html) * [Migrating to This Library](https://discordpy-self.readthedocs.io/en/latest/migrating_from_dpy.html) * [Migrating to v2.0](https://discordpy-self.readthedocs.io/en/latest/migrating.html) [AI without context? That’s just another chatbot. **Get the tools you need to create smart agents**](https://server.ethicalads.io/proxy/click/10003/019bf148-4369-7ea3-93db-20924cd4a1a5/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) arrow\_upward to top --- # Welcome to discord.py-self View Documentation For discord discord.ext.commands discord.ext.tasks search settings Welcome to discord.py-self[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/#welcome-to-discord-py-self "Permalink to this headline") ======================================================================================================================================== ![_images/snake.svg](https://discordpy-self.readthedocs.io/en/v2.0.1/_images/snake.svg)![_images/snake_dark.svg](https://discordpy-self.readthedocs.io/en/v2.0.1/_images/snake_dark.svg) discord.py-self is a modern, easy to use, feature-rich, and async ready API wrapper for the Discord user APIs. **Features:** * Modern Pythonic API using `async`/`await` syntax * Sane rate limit handling that prevents 429s * Command extension to aid with bot creation * Easy to use with an object oriented design * Optimised for both speed and memory * Prevents detection of user account automation Getting started[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/#getting-started "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------ Is this your first time using the library? This is the place to get started! * **Migrating from discord.py:** [Migrating to This Library](https://discordpy-self.readthedocs.io/en/v2.0.1/migrating_from_dpy.html) * **First steps:** [Introduction](https://discordpy-self.readthedocs.io/en/v2.0.1/intro.html) | [Quickstart](https://discordpy-self.readthedocs.io/en/v2.0.1/quickstart.html) | [Setting Up Logging](https://discordpy-self.readthedocs.io/en/v2.0.1/logging.html) * **Working with Discord:** [Authenticating](https://discordpy-self.readthedocs.io/en/v2.0.1/authenticating.html) | [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/v2.0.1/guild_subscriptions.html) * **Examples:** Many examples are available in the [repository](https://github.com/dolfies/discord.py-self/tree/master/examples) **Obligatory note:** Automating user accounts is against the Discord ToS. If what you are trying to do is accomplishable with a bot account, please use one. Getting help[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/#getting-help "Permalink to this headline") ------------------------------------------------------------------------------------------------------------ If you’re having trouble with something, these resources might help. * Try the [Frequently Asked Questions](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html) first, it’s got answers to all common questions. * If you’re looking for something specific, try the [index](https://discordpy-self.readthedocs.io/en/v2.0.1/genindex.html) or [searching](https://discordpy-self.readthedocs.io/en/v2.0.1/search.html) . * Report bugs in the [issue tracker](https://github.com/dolfies/discord.py-self/issues) . * Ask in our [GitHub discussions page](https://github.com/dolfies/discord.py-self/discussions) . Extensions[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/#extensions "Permalink to this headline") -------------------------------------------------------------------------------------------------------- These extensions help you during development when it comes to common tasks. * [`discord.ext.commands` – Bot commands framework](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/index.html) * [`discord.ext.tasks` – asyncio.Task helpers](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html) Manuals[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/#manuals "Permalink to this headline") -------------------------------------------------------------------------------------------------- These pages go into great detail about everything the API can do. * [API Reference](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html) * [discord.ext.commands API Reference](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html) * [discord.ext.tasks API Reference](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html) Meta[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/#meta "Permalink to this headline") -------------------------------------------------------------------------------------------- If you’re looking for something related to the project itself, it’s here. * [Changelog](https://discordpy-self.readthedocs.io/en/v2.0.1/whats_new.html) * [Version Guarantees](https://discordpy-self.readthedocs.io/en/v2.0.1/version_guarantees.html) * [Migrating to This Library](https://discordpy-self.readthedocs.io/en/v2.0.1/migrating_from_dpy.html) * [Migrating to v2.0](https://discordpy-self.readthedocs.io/en/v2.0.1/migrating.html) [AI without context? That’s just another chatbot. **Get the tools you need to create smart agents**](https://server.ethicalads.io/proxy/click/10003/019bf148-4369-7ea3-93db-20924cd4a1a5/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) arrow\_upward to top --- # Welcome to discord.py-self View Documentation For discord discord.ext.commands discord.ext.tasks search settings Welcome to discord.py-self[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/#welcome-to-discord-py-self "Permalink to this headline") ======================================================================================================================================== ![_images/snake.svg](https://discordpy-self.readthedocs.io/en/v2.1.0/_images/snake.svg)![_images/snake_dark.svg](https://discordpy-self.readthedocs.io/en/v2.1.0/_images/snake_dark.svg) discord.py-self is a modern, easy to use, feature-rich, and async ready API wrapper for the Discord user APIs. **Features:** * Modern Pythonic API using `async`/`await` syntax * Sane rate limit handling that prevents 429s * Command extension to aid with bot creation * Easy to use with an object oriented design * Optimised for both speed and memory * Prevents detection of user account automation Getting started[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/#getting-started "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------ Is this your first time using the library? This is the place to get started! * **Migrating from discord.py:** [Migrating to This Library](https://discordpy-self.readthedocs.io/en/v2.1.0/migrating_from_dpy.html) * **First steps:** [Introduction](https://discordpy-self.readthedocs.io/en/v2.1.0/intro.html) | [Quickstart](https://discordpy-self.readthedocs.io/en/v2.1.0/quickstart.html) | [Setting Up Logging](https://discordpy-self.readthedocs.io/en/v2.1.0/logging.html) * **Working with Discord:** [Authenticating](https://discordpy-self.readthedocs.io/en/v2.1.0/authenticating.html) | [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/v2.1.0/guild_subscriptions.html) * **Examples:** Many examples are available in the [repository](https://github.com/dolfies/discord.py-self/tree/v2.1.0/examples) **Obligatory note:** Automating user accounts is against the Discord ToS. If what you are trying to do is accomplishable with a bot account, please use one. Getting help[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/#getting-help "Permalink to this headline") ------------------------------------------------------------------------------------------------------------ If you’re having trouble with something, these resources might help. * Try the [Frequently Asked Questions](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html) first, it’s got answers to all common questions. * If you’re looking for something specific, try the [index](https://discordpy-self.readthedocs.io/en/v2.1.0/genindex.html) or [searching](https://discordpy-self.readthedocs.io/en/v2.1.0/search.html) . * Report bugs in the [issue tracker](https://github.com/dolfies/discord.py-self/issues) . * Ask in our [GitHub discussions page](https://github.com/dolfies/discord.py-self/discussions) . Extensions[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/#extensions "Permalink to this headline") -------------------------------------------------------------------------------------------------------- These extensions help you during development when it comes to common tasks. * [`discord.ext.commands` – Bot commands framework](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html) * [`discord.ext.tasks` – asyncio.Task helpers](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html) Manuals[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/#manuals "Permalink to this headline") -------------------------------------------------------------------------------------------------- These pages go into great detail about everything the API can do. * [API Reference](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html) * [discord.ext.commands API Reference](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html) * [discord.ext.tasks API Reference](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html) Meta[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/#meta "Permalink to this headline") -------------------------------------------------------------------------------------------- If you’re looking for something related to the project itself, it’s here. * [Changelog](https://discordpy-self.readthedocs.io/en/v2.1.0/whats_new.html) * [Version Guarantees](https://discordpy-self.readthedocs.io/en/v2.1.0/version_guarantees.html) * [Migrating to This Library](https://discordpy-self.readthedocs.io/en/v2.1.0/migrating_from_dpy.html) * [Migrating to v2.0](https://discordpy-self.readthedocs.io/en/v2.1.0/migrating.html) [AI without context? That’s just another chatbot. **Get the tools you need to create smart agents**](https://server.ethicalads.io/proxy/click/10003/019bf148-4369-7ea3-93db-20924cd4a1a5/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) arrow\_upward to top --- # Welcome to discord.py-self View Documentation For discord discord.ext.commands discord.ext.tasks search settings Welcome to discord.py-self[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/#welcome-to-discord-py-self "Permalink to this headline") ======================================================================================================================================== ![_images/snake.svg](https://discordpy-self.readthedocs.io/en/v2.0.0/_images/snake.svg)![_images/snake_dark.svg](https://discordpy-self.readthedocs.io/en/v2.0.0/_images/snake_dark.svg) discord.py-self is a modern, easy to use, feature-rich, and async ready API wrapper for the Discord user APIs. **Features:** * Modern Pythonic API using `async`/`await` syntax * Sane rate limit handling that prevents 429s * Command extension to aid with bot creation * Easy to use with an object oriented design * Optimised for both speed and memory * Prevents detection of user account automation Getting started[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/#getting-started "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------ Is this your first time using the library? This is the place to get started! * **Migrating from discord.py:** [Migrating to This Library](https://discordpy-self.readthedocs.io/en/v2.0.0/migrating_from_dpy.html) * **First steps:** [Introduction](https://discordpy-self.readthedocs.io/en/v2.0.0/intro.html) | [Quickstart](https://discordpy-self.readthedocs.io/en/v2.0.0/quickstart.html) | [Setting Up Logging](https://discordpy-self.readthedocs.io/en/v2.0.0/logging.html) * **Working with Discord:** [Tokens](https://discordpy-self.readthedocs.io/en/v2.0.0/token.html) * **Examples:** Many examples are available in the [repository](https://github.com/dolfies/discord.py-self/tree/v2.0.0/examples) **Obligatory note:** Automating user accounts is against the Discord ToS. If what you are trying to do is accomplishable with a bot account, please use one. Getting help[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/#getting-help "Permalink to this headline") ------------------------------------------------------------------------------------------------------------ If you’re having trouble with something, these resources might help. * Try the [Frequently Asked Questions](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html) first, it’s got answers to all common questions. * If you’re looking for something specific, try the [index](https://discordpy-self.readthedocs.io/en/v2.0.0/genindex.html) or [searching](https://discordpy-self.readthedocs.io/en/v2.0.0/search.html) . * Report bugs in the [issue tracker](https://github.com/dolfies/discord.py-self/issues) . * Ask in our [GitHub discussions page](https://github.com/dolfies/discord.py-self/discussions) . Extensions[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/#extensions "Permalink to this headline") -------------------------------------------------------------------------------------------------------- These extensions help you during development when it comes to common tasks. * [`discord.ext.commands` – Bot commands framework](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/index.html) * [`discord.ext.tasks` – asyncio.Task helpers](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html) Manuals[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/#manuals "Permalink to this headline") -------------------------------------------------------------------------------------------------- These pages go into great detail about everything the API can do. * [API Reference](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html) * [discord.ext.commands API Reference](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html) * [discord.ext.tasks API Reference](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html) Meta[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/#meta "Permalink to this headline") -------------------------------------------------------------------------------------------- If you’re looking for something related to the project itself, it’s here. * [Changelog](https://discordpy-self.readthedocs.io/en/v2.0.0/whats_new.html) * [Version Guarantees](https://discordpy-self.readthedocs.io/en/v2.0.0/version_guarantees.html) * [Migrating to This Library](https://discordpy-self.readthedocs.io/en/v2.0.0/migrating_from_dpy.html) * [Migrating to v2.0](https://discordpy-self.readthedocs.io/en/v2.0.0/migrating.html) [AI without context? That’s just another chatbot. **Get the tools you need to create smart agents**](https://server.ethicalads.io/proxy/click/10003/019bf148-4369-7ea3-93db-20924cd4a1a5/) [Ads by EthicalAds](https://www.ethicalads.io/advertisers/topics/backend-web/?ref=ea-text) arrow\_upward to top --- # Frequently Asked Questions View Documentation For discord discord.ext.commands discord.ext.tasks search settings Frequently Asked Questions[¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#frequently-asked-questions "Permalink to this headline") ================================================================================================================================================ This is a list of Frequently Asked Questions regarding using `discord.py-self` and its extension modules. Feel free to suggest a new question or submit one via pull requests. Questions * [Coroutines](https://discordpy-self.readthedocs.io/en/latest/faq.html#coroutines) * [What is a coroutine?](https://discordpy-self.readthedocs.io/en/latest/faq.html#what-is-a-coroutine) * [Where can I use `await`?](https://discordpy-self.readthedocs.io/en/latest/faq.html#where-can-i-use-await) * [What does “blocking” mean?](https://discordpy-self.readthedocs.io/en/latest/faq.html#what-does-blocking-mean) * [General](https://discordpy-self.readthedocs.io/en/latest/faq.html#general) * [Where can I find usage examples?](https://discordpy-self.readthedocs.io/en/latest/faq.html#where-can-i-find-usage-examples) * [How do I set the “Playing” status?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-set-the-playing-status) * [How do I send a message to a specific channel?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-send-a-message-to-a-specific-channel) * [How do I send a DM?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-send-a-dm) * [How do I get the ID of a sent message?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-get-the-id-of-a-sent-message) * [How do I upload an image?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-upload-an-image) * [How can I add a reaction to a message?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-can-i-add-a-reaction-to-a-message) * [How do I pass a coroutine to the player’s “after” function?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-pass-a-coroutine-to-the-player-s-after-function) * [How do I run something in the background?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-run-something-in-the-background) * [How do I get a specific model?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-get-a-specific-model) * [How do I make a web request?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-make-a-web-request) * [How do I use a local image file for an embed image?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-use-a-local-image-file-for-an-embed-image) * [Is there an event for audit log entries being created?](https://discordpy-self.readthedocs.io/en/latest/faq.html#is-there-an-event-for-audit-log-entries-being-created) * [Commands Extension](https://discordpy-self.readthedocs.io/en/latest/faq.html#commands-extension) * [Why does `on_message` make my commands stop working?](https://discordpy-self.readthedocs.io/en/latest/faq.html#why-does-on-message-make-my-commands-stop-working) * [Why do my arguments require quotes?](https://discordpy-self.readthedocs.io/en/latest/faq.html#why-do-my-arguments-require-quotes) * [How do I get the original `message`?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-get-the-original-message) * [How do I make a subcommand?](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-make-a-subcommand) [Coroutines](https://discordpy-self.readthedocs.io/en/latest/faq.html#id1) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#coroutines "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Questions regarding coroutines and asyncio belong here. ### [What is a coroutine?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id2) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#what-is-a-coroutine "Permalink to this headline") A [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) is a function that must be invoked with `await` or `yield from`. When Python encounters an `await` it stops the function’s execution at that point and works on other things until it comes back to that point and finishes off its work. This allows for your program to be doing multiple things at the same time without using threads or complicated multiprocessing. **If you forget to await a coroutine then the coroutine will not run. Never forget to await a coroutine.** ### [Where can I use `await`?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id3) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#where-can-i-use-await "Permalink to this headline") You can only use `await` inside `async def` functions and nowhere else. ### [What does “blocking” mean?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id4) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#what-does-blocking-mean "Permalink to this headline") In asynchronous programming a blocking call is essentially all the parts of the function that are not `await`. Do not despair however, because not all forms of blocking are bad! Using blocking calls is inevitable, but you must work to make sure that you don’t excessively block functions. Remember, if you block for too long then your bot will freeze since it has not stopped the function’s execution at that point to do other things. If logging is enabled, this library will attempt to warn you that blocking is occurring with the message: `Heartbeat blocked for more than N seconds.` See [Setting Up Logging](https://discordpy-self.readthedocs.io/en/latest/logging.html#logging-setup) for details on enabling logging. A common source of blocking for too long is something like [`time.sleep()`](https://docs.python.org/3/library/time.html#time.sleep "(in Python v3.14)") . Don’t do that. Use [`asyncio.sleep()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.sleep "(in Python v3.14)") instead. Similar to this example: content\_copy \# bad time.sleep(10) \# good await asyncio.sleep(10) Another common source of blocking for too long is using HTTP requests with the famous module [Requests: HTTP for Humans™](https://requests.readthedocs.io/en/latest/ "(in Requests v2.32.5)") . While [Requests: HTTP for Humans™](https://requests.readthedocs.io/en/latest/ "(in Requests v2.32.5)") is an amazing module for non-asynchronous programming, it is not a good choice for [`asyncio`](https://docs.python.org/3/library/asyncio.html#module-asyncio "(in Python v3.14)") because certain requests can block the event loop too long. Instead, use the [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.13)") library which is installed on the side with this library. Consider the following example: content\_copy \# bad r \= requests.get('http://aws.random.cat/meow') if r.status\_code \== 200: js \= r.json() await channel.send(js\['file'\]) \# good async with aiohttp.ClientSession() as session: async with session.get('http://aws.random.cat/meow') as r: if r.status \== 200: js \= await r.json() await channel.send(js\['file'\]) [General](https://discordpy-self.readthedocs.io/en/latest/faq.html#id5) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#general "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- General questions regarding library usage belong here. ### [Where can I find usage examples?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id6) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#where-can-i-find-usage-examples "Permalink to this headline") Example code can be found in the [examples folder](https://github.com/dolfies/discord.py-self/tree/master/examples) in the repository. ### [How do I set the “Playing” status?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id7) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-set-the-playing-status "Permalink to this headline") The `activity` keyword argument may be passed in the [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") constructor or [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.change_presence "discord.Client.change_presence") , given an [`Activity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Activity "discord.Activity") object. The constructor may be used for static activities, while [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.change_presence "discord.Client.change_presence") may be used to update the activity at runtime. Warning It is highly discouraged to use [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.change_presence "discord.Client.change_presence") or API calls in [`on_ready()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_ready "discord.on_ready") as this event may be called many times while running, not just once. The status type (playing, listening, streaming, watching) can be set using the [`ActivityType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ActivityType "discord.ActivityType") enum. For memory optimisation purposes, some activities are offered in slimmed-down versions: * [`Game`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Game "discord.Game") * [`Streaming`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Streaming "discord.Streaming") Putting both of these pieces of info together, you get the following: content\_copy client \= discord.Client(activity\=discord.Game(name\='my game')) \# or, for watching: activity \= discord.Activity(name\='my activity', type\=discord.ActivityType.watching) client \= discord.Client(activity\=activity) ### [How do I send a message to a specific channel?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id8) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-send-a-message-to-a-specific-channel "Permalink to this headline") You must fetch the channel directly and then call the appropriate method. Example: content\_copy channel \= client.get\_channel(12324234183172) await channel.send('hello') ### [How do I send a DM?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id9) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-send-a-dm "Permalink to this headline") Get the [`User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User") or [`Member`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Member "discord.Member") object and call [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") . For example: content\_copy user \= client.get\_user(381870129706958858) await user.send('👀') If you are responding to an event, such as [`on_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message "discord.on_message") , you already have the [`User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User") object via [`Message.author`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.author "discord.Message.author") : content\_copy await message.author.send('👋') ### [How do I get the ID of a sent message?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id10) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-get-the-id-of-a-sent-message "Permalink to this headline") [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") returns the [`Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") that was sent. The ID of a message can be accessed via [`Message.id`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.id "discord.Message.id") : content\_copy message \= await channel.send('hmm…') message\_id \= message.id ### [How do I upload an image?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id11) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-upload-an-image "Permalink to this headline") To upload something to Discord you have to use the [`File`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.File "discord.File") object. A [`File`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.File "discord.File") accepts two parameters, the file-like object (or file path) and the filename to pass to Discord when uploading. If you want to upload an image it’s as simple as: content\_copy await channel.send(file\=discord.File('my\_file.png')) If you have a file-like object you can do as follows: content\_copy with open('my\_file.png', 'rb') as fp: await channel.send(file\=discord.File(fp, 'new\_filename.png')) To upload multiple files, you can use the `files` keyword argument instead of `file`: content\_copy my\_files \= \[\ discord.File('result.zip'),\ discord.File('teaser\_graph.png'),\ \] await channel.send(files\=my\_files) If you want to upload something from a URL, you will have to use an HTTP request using [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.13)") and then pass an [`io.BytesIO`](https://docs.python.org/3/library/io.html#io.BytesIO "(in Python v3.14)") instance to [`File`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.File "discord.File") like so: content\_copy import io import aiohttp async with aiohttp.ClientSession() as session: async with session.get(my\_url) as resp: if resp.status != 200: return await channel.send('Could not download file...') data \= io.BytesIO(await resp.read()) await channel.send(file\=discord.File(data, 'cool\_image.png')) ### [How can I add a reaction to a message?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id12) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-can-i-add-a-reaction-to-a-message "Permalink to this headline") You use the [`Message.add_reaction()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.add_reaction "discord.Message.add_reaction") method. If you want to use unicode emoji, you must pass a valid unicode code point in a string. In your code, you can write this in a few different ways: * `'👍'` * `'\U0001F44D'` * `'\N{THUMBS UP SIGN}'` Quick example: content\_copy emoji \= '\\N{THUMBS UP SIGN}' \# or '\\U0001f44d' or '👍' await message.add\_reaction(emoji) In case you want to use emoji that come from a message, you already get their code points in the content without needing to do anything special. You **cannot** send `':thumbsup:'` style shorthands. For custom emoji, you should pass an instance of [`Emoji`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Emoji "discord.Emoji") . You can also pass a `'<:name:id>'` string, but if you can use said emoji, you should be able to use [`Client.get_emoji()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.get_emoji "discord.Client.get_emoji") to get an emoji via ID or use [`utils.find()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.utils.find "discord.utils.find") / [`utils.get()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.utils.get "discord.utils.get") on [`Client.emojis`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.emojis "discord.Client.emojis") or [`Guild.emojis`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.emojis "discord.Guild.emojis") collections. The name and ID of a custom emoji can be found with the client by prefixing `:custom_emoji:` with a backslash. For example, sending the message `\:python3:` with the client will result in `<:python3:232720527448342530>`. Quick example: content\_copy \# if you have the ID already emoji \= client.get\_emoji(310177266011340803) await message.add\_reaction(emoji) \# no ID, do a lookup emoji \= discord.utils.get(guild.emojis, name\='LUL') if emoji: await message.add\_reaction(emoji) \# if you have the name and ID of a custom emoji: emoji \= '<:python3:232720527448342530>' await message.add\_reaction(emoji) ### [How do I pass a coroutine to the player’s “after” function?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id13) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-pass-a-coroutine-to-the-player-s-after-function "Permalink to this headline") The library’s music player launches on a separate thread, ergo it does not execute inside a coroutine. This does not mean that it is not possible to call a coroutine in the `after` parameter. To do so you must pass a callable that wraps up a couple of aspects. The first gotcha that you must be aware of is that calling a coroutine is not a thread-safe operation. Since we are technically in another thread, we must take caution in calling thread-safe operations so things do not bug out. Luckily for us, [`asyncio`](https://docs.python.org/3/library/asyncio.html#module-asyncio "(in Python v3.14)") comes with a [`asyncio.run_coroutine_threadsafe()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.run_coroutine_threadsafe "(in Python v3.14)") function that allows us to call a coroutine from another thread. However, this function returns a [`Future`](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future "(in Python v3.14)") and to actually call it we have to fetch its result. Putting all of this together we can do the following: content\_copy def my\_after(error): coro \= some\_channel.send('Song is done!') fut \= asyncio.run\_coroutine\_threadsafe(coro, client.loop) try: fut.result() except: \# an error happened sending the message pass voice.play(discord.FFmpegPCMAudio(url), after\=my\_after) ### [How do I run something in the background?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id14) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-run-something-in-the-background "Permalink to this headline") [Check the background\_task.py example.](https://github.com/dolfies/discord.py-self/blob/master/examples/background_task.py) ### [How do I get a specific model?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id15) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-get-a-specific-model "Permalink to this headline") There are multiple ways of doing this. If you have a specific model’s ID then you can use one of the following functions: * [`Client.get_channel()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.get_channel "discord.Client.get_channel") * [`Client.get_guild()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.get_guild "discord.Client.get_guild") * [`Client.get_user()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.get_user "discord.Client.get_user") * [`Client.get_emoji()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.get_emoji "discord.Client.get_emoji") * [`Guild.get_member()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.get_member "discord.Guild.get_member") * [`Guild.get_channel()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.get_channel "discord.Guild.get_channel") * [`Guild.get_role()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.get_role "discord.Guild.get_role") The following use an HTTP request: * [`abc.Messageable.fetch_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.fetch_message "discord.abc.Messageable.fetch_message") * [`Client.fetch_user()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_user "discord.Client.fetch_user") * [`Client.fetch_guilds()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_guilds "discord.Client.fetch_guilds") * [`Client.fetch_guild()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_guild "discord.Client.fetch_guild") * [`Guild.fetch_emoji()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.fetch_emoji "discord.Guild.fetch_emoji") * [`Guild.fetch_emojis()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.fetch_emojis "discord.Guild.fetch_emojis") * [`Guild.fetch_member()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.fetch_member "discord.Guild.fetch_member") If the functions above do not help you, then use of [`utils.find()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.utils.find "discord.utils.find") or [`utils.get()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.utils.get "discord.utils.get") would serve some use in finding specific models. Quick example: content\_copy \# find a guild by name guild \= discord.utils.get(client.guilds, name\='My Server') \# make sure to check if it's found if guild is not None: \# find a channel by name channel \= discord.utils.get(guild.text\_channels, name\='cool-channel') ### [How do I make a web request?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id16) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-make-a-web-request "Permalink to this headline") To make a request, you should use a non-blocking library. This library already uses and requires a 3rd party library for making requests, [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.13)") . Quick example: content\_copy async with aiohttp.ClientSession() as session: async with session.get('http://aws.random.cat/meow') as r: if r.status \== 200: js \= await r.json() See [aiohttp’s full documentation](http://aiohttp.readthedocs.io/en/stable/) for more information. ### [How do I use a local image file for an embed image?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id17) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-use-a-local-image-file-for-an-embed-image "Permalink to this headline") Discord special-cases uploading an image attachment and using it within an embed so that it will not display separately, but instead in the embed’s thumbnail, image, footer or author icon. To do so, upload the image normally with [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") , and set the embed’s image URL to `attachment://image.png`, where `image.png` is the filename of the image you will send. Quick example: content\_copy file \= discord.File("path/to/my/image.png", filename\="image.png") embed \= discord.Embed() embed.set\_image(url\="attachment://image.png") await channel.send(file\=file, embed\=embed) ### [Is there an event for audit log entries being created?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id18) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#is-there-an-event-for-audit-log-entries-being-created "Permalink to this headline") This event is now available in the library and Discord as of version 2.0. It can be found under [`on_audit_log_entry_create()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_audit_log_entry_create "discord.on_audit_log_entry_create") . [Commands Extension](https://discordpy-self.readthedocs.io/en/latest/faq.html#id19) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#commands-extension "Permalink to this headline") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Questions regarding `discord.ext.commands` belong here. ### [Why does `on_message` make my commands stop working?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id20) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#why-does-on-message-make-my-commands-stop-working "Permalink to this headline") Overriding the default provided `on_message` forbids any extra commands from running. To fix this, add a `bot.process_commands(message)` line at the end of your `on_message`. For example: content\_copy @bot.event async def on\_message(message): \# do some extra stuff here await bot.process\_commands(message) Alternatively, you can place your `on_message` logic into a **listener**. In this setup, you should not manually call `bot.process_commands()`. This also allows you to do multiple things asynchronously in response to a message. Example: content\_copy @bot.listen('on\_message') async def whatever\_you\_want\_to\_call\_it(message): \# do stuff here \# do not process commands here ### [Why do my arguments require quotes?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id21) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#why-do-my-arguments-require-quotes "Permalink to this headline") In a simple command defined as: content\_copy @bot.command() async def echo(ctx, message: str): await ctx.send(message) Calling it via `?echo a b c` will only fetch the first argument and disregard the rest. To fix this you should either call it via `?echo "a b c"` or change the signature to have “consume rest” behaviour. Example: content\_copy @bot.command() async def echo(ctx, \*, message: str): await ctx.send(message) This will allow you to use `?echo a b c` without needing the quotes. ### [How do I get the original `message`?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id22) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-get-the-original-message "Permalink to this headline") The [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") contains an attribute, [`message`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context.message "discord.ext.commands.Context.message") to get the original message. Example: content\_copy @bot.command() async def length(ctx): await ctx.send(f'Your message is {len(ctx.message.content)} characters long.') ### [How do I make a subcommand?](https://discordpy-self.readthedocs.io/en/latest/faq.html#id23) [¶](https://discordpy-self.readthedocs.io/en/latest/faq.html#how-do-i-make-a-subcommand "Permalink to this headline") Use the [`group()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.group "discord.ext.commands.group") decorator. This will transform the callback into a [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") which will allow you to add commands into the group operating as “subcommands”. These groups can be arbitrarily nested as well. Example: content\_copy @bot.group() async def git(ctx): if ctx.invoked\_subcommand is None: await ctx.send('Invalid git command passed...') @git.command() async def push(ctx, remote: str, branch: str): await ctx.send(f'Pushing to {remote} {branch}') This could then be used as `?git push origin master`. arrow\_upward to top --- # Migrating to This Library View Documentation For discord discord.ext.commands discord.ext.tasks search settings Migrating to This Library[¶](https://discordpy-self.readthedocs.io/en/latest/migrating_from_dpy.html#migrating-to-this-library "Permalink to this headline") ============================================================================================================================================================= This library is designed to be compatible with discord.py. However, the user and bot APIs are _not_ the same. Most things bots can do, users can (in some capacity) as well. The biggest difference is the amount of added things: users can do a lot more things than bots can. However, a number of things have been removed. For example: * `Intents`: While the gateway technically accepts intents for user accounts, they are—for the most part—useless and can break things. * `Shards`: Just like intents, users can utilize sharding but it is not very useful. * `discord.ui`: Users cannot utilize the bot UI kit. * `discord.app_commands`: Users cannot register application commands. However, even in features that are shared between user and bot accounts, there may be variance in functionality or simply different design choices that better reflect a user account implementation. An effort is made to minimize these differences and avoid migration pain, but it is not always the first priority. Guild Subscriptions[¶](https://discordpy-self.readthedocs.io/en/latest/migrating_from_dpy.html#guild-subscriptions "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------- Guild subscriptions are a way for a client to limit the events it receives from a guild. For more information about guild subscriptions, see the [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/latest/guild_subscriptions.html) section. When compared to a bot account, the most noticeable differences they introduce are in relation to guild members and presence. ### Guild Members[¶](https://discordpy-self.readthedocs.io/en/latest/migrating_from_dpy.html#guild-members "Permalink to this headline") The concept of privileged intents does not exist for user accounts, so guild member access is limited in different ways. By default, the library will subscribe to member updates for all guilds, meaning that events such as [`discord.on_member_join()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_member_join "discord.on_member_join") and [`discord.on_raw_member_remove()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_raw_member_remove "discord.on_raw_member_remove") will be dispatched for all guilds the user is in. However, events that require the member cache to be populated (such as [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_member_update "discord.on_member_update") ) are only dispatched for guilds that are chunked. A guild can only be chunked (have the local member cache populated) if the user has the [`manage_roles`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Permissions.manage_roles "discord.Permissions.manage_roles") , [`kick_members`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Permissions.kick_members "discord.Permissions.kick_members") , or [`ban_members`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Permissions.ban_members "discord.Permissions.ban_members") permissions. Additionally, guilds with less than 1,000 members may be chunked if there exists at least one channel that everyone can view. By default, the library will attempt to chunk all guilds that are chunkable. This can be disabled by setting the `chunk_guilds_at_startup` parameter to `False` when creating a [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") . If a guild is not chunked, the only members that will be cached are members with an active voice state and, if the guild has less than 75,000 members, members that the user is friends, has an implicit relationship, or has an open DM with. The library offers two avenues to get the “entire” member list of a guild. * [`Guild.chunk()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.chunk "discord.Guild.chunk") : If chunking guilds at startup is disabled, you can use this method to chunk a guild manually. * [`Guild.fetch_members()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.fetch_members "discord.Guild.fetch_members") : If you have the permissions to request all guild members, you can use this method to fetch the entire member list. Else, this method scrapes the member sidebar (which can become very slow), only returning online members if the guild has more than 1,000 members. ### Presence[¶](https://discordpy-self.readthedocs.io/en/latest/migrating_from_dpy.html#presence "Permalink to this headline") User accounts are always synced the overall presence of friends and implicit relationships, tracked in the library via the [`Relationship`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Relationship "discord.Relationship") class. Overall user presence updates will dispatch a [`discord.on_presence_update()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_presence_update "discord.on_presence_update") event with [`Relationship`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Relationship "discord.Relationship") instances. Additionally, for guilds with less than 75,000 members, they’re synced the per-guild presence of members that the user is friends, has an implicit relationship, or has an open DM with. Outside of these cases, you will not receive presence updates for any other users. To obtain the presence of an arbitrary user, you can use the [`Guild.query_members()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.query_members "discord.Guild.query_members") method. To stay informed of presence updates for a specific user, you can subscribe to them using the [`Guild.subscribe_to()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.subscribe_to "discord.Guild.subscribe_to") method. See the [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/latest/guild_subscriptions.html) section for more information. Note User updates (i.e. [`discord.on_user_update()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_user_update "discord.on_user_update") ) require either member updates (for at least one guild) or presence updates to be dispatched for the user as outlined above. AutoMod[¶](https://discordpy-self.readthedocs.io/en/latest/migrating_from_dpy.html#automod "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------- The following Gateway events are not dispatched to user accounts: * `on_automod_rule_create` * `on_automod_rule_update` * `on_automod_rule_delete` * `on_automod_action` The first three can be replaced by listening to the [`discord.on_audit_log_entry_create()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_audit_log_entry_create "discord.on_audit_log_entry_create") event and checking the [`action`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AuditLogEntry.action "discord.AuditLogEntry.action") attribute. The last one is partially replaceable by listening to the [`discord.on_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message "discord.on_message") event and checking for AutoMod system messages, but this is not a perfect solution. arrow\_upward to top --- # Introduction View Documentation For discord discord.ext.commands discord.ext.tasks search settings Introduction[¶](https://discordpy-self.readthedocs.io/en/latest/intro.html#introduction "Permalink to this headline") ====================================================================================================================== This is the documentation for discord.py-self, a library for Python to aid in creating bots running on user accounts that utilise the Discord API. Prerequisites[¶](https://discordpy-self.readthedocs.io/en/latest/intro.html#prerequisites "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------ discord.py-self works with Python 3.10 or higher. Support for earlier versions of Python is not provided. Installing[¶](https://discordpy-self.readthedocs.io/en/latest/intro.html#installing "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------ You can get the library directly from PyPI: content\_copy python3 \-m pip install \-U discord.py\-self If you are using Windows, then the following should be used instead: content\_copy py \-3 \-m pip install \-U discord.py\-self To get voice support, you should use `discord.py-self[voice]` instead of `discord.py`, e.g. content\_copy python3 \-m pip install \-U discord.py\-self\[voice\] On Linux environments, installing voice requires getting the following dependencies: * [libffi](https://github.com/libffi/libffi) * [libnacl](https://github.com/saltstack/libnacl) * [python3-dev](https://packages.debian.org/python3-dev) For a Debian-based system, the following command will get these dependencies: content\_copy $ apt install libffi-dev libnacl-dev python3-dev Remember to check your permissions! ### Virtual Environments[¶](https://discordpy-self.readthedocs.io/en/latest/intro.html#virtual-environments "Permalink to this headline") Sometimes you want to keep libraries from polluting system installs or use a different version of libraries than the ones installed on the system. You might also not have permissions to install libraries system-wide. For this purpose, the standard library as of Python 3.3 comes with a concept called “Virtual Environment”s to help maintain these separate versions. A more in-depth tutorial is found on [Virtual Environments and Packages](https://docs.python.org/3/tutorial/venv.html "(in Python v3.14)") . However, for the quick and dirty: 1. Go to your project’s working directory: > content\_copy > > $ cd your-bot-source > $ python3 \-m venv bot-env 2. Activate the virtual environment: > content\_copy > > $ source bot-env/bin/activate > > On Windows you activate it with: > > content\_copy > > $ bot-env\\Scripts\\activate.bat 3. Use pip like usual: > content\_copy > > $ pip install \-U discord.py-self Congratulations. You now have a virtual environment all set up. Basic Concepts[¶](https://discordpy-self.readthedocs.io/en/latest/intro.html#basic-concepts "Permalink to this headline") -------------------------------------------------------------------------------------------------------------------------- discord.py revolves around the concept of [events](https://discordpy-self.readthedocs.io/en/latest/api.html#discord-api-events) . An event is something you listen to and then respond to. For example, when a message happens, you will receive an event about it that you can respond to. A quick example to showcase how events work: content\_copy import discord class MyClient(discord.Client): async def on\_ready(self): print(f'Logged on as {self.user}!') async def on\_message(self, message): print(f'Message from {message.author}: {message.content}') client \= MyClient() client.run('token') arrow\_upward to top --- # Quickstart View Documentation For discord discord.ext.commands discord.ext.tasks search settings Quickstart[¶](https://discordpy-self.readthedocs.io/en/latest/quickstart.html#quickstart "Permalink to this headline") ======================================================================================================================= This page gives a brief introduction to the library. It assumes you have the library installed, if you don’t check the [Installing](https://discordpy-self.readthedocs.io/en/latest/intro.html#installing) portion. A Minimal Bot[¶](https://discordpy-self.readthedocs.io/en/latest/quickstart.html#a-minimal-bot "Permalink to this headline") ----------------------------------------------------------------------------------------------------------------------------- Let’s make a bot that responds to a specific message and walk you through it. It looks something like this: content\_copy import discord client \= discord.Client() @client.event async def on\_ready(): print(f'We have logged in as {client.user}') @client.event async def on\_message(message): if message.author != client.user: return if message.content.startswith('$hello'): await message.channel.send('Hello!') client.run('your token here') Let’s name this file `example_bot.py`. Make sure not to name it `discord.py` as that’ll conflict with the library. There’s a lot going on here, so let’s walk you through it step by step. 1. The first line just imports the library, if this raises a [`ModuleNotFoundError`](https://docs.python.org/3/library/exceptions.html#ModuleNotFoundError "(in Python v3.14)") or [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError "(in Python v3.14)") then head on over to [Installing](https://discordpy-self.readthedocs.io/en/latest/intro.html#installing) section to properly install. 2. Next, we create an instance of a [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") . This client is our connection to Discord. 3. We then use the [`Client.event()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.event "discord.Client.event") decorator to register an event. This library has many events. Since this library is asynchronous, we do things in a “callback” style manner. A callback is essentially a function that is called when something happens. In our case, the [`on_ready()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_ready "discord.on_ready") event is called when the bot has finished logging in and setting things up and the [`on_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message "discord.on_message") event is called when the bot has received a message. 4. Since the [`on_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message "discord.on_message") event triggers for _every_ message received, we have to make sure that we ignore messages from ourselves. We do this by checking if the [`Message.author`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.author "discord.Message.author") is the same as the [`Client.user`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.user "discord.Client.user") . 5. Afterwards, we check if the [`Message.content`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.content "discord.Message.content") starts with `'$hello'`. If it does, then we send a message in the channel it was used in with `'Hello!'`. This is a basic way of handling commands, which can be later automated with the [discord.ext.commands – Bot commands framework](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html) framework. 6. Finally, we run the bot with our login token. If you need help getting your token, look in the [Authenticating](https://discordpy-self.readthedocs.io/en/latest/authenticating.html) section. Now that we’ve made a bot, we have to _run_ the bot. Luckily, this is simple since this is just a Python script, we can run it directly. On Windows: content\_copy $ py \-3 example\_bot.py On other systems: content\_copy $ python3 example\_bot.py Now you can try playing around with your basic bot. arrow\_upward to top --- # Authenticating View Documentation For discord discord.ext.commands discord.ext.tasks search settings Authenticating[¶](https://discordpy-self.readthedocs.io/en/latest/authenticating.html#authenticating "Permalink to this headline") =================================================================================================================================== Tokens[¶](https://discordpy-self.readthedocs.io/en/latest/authenticating.html#tokens "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------- Tokens are how we authenticate with Discord. User accounts use the same token system as bots, received after authenticating with the Discord API. How do I obtain mine?[¶](https://discordpy-self.readthedocs.io/en/latest/authenticating.html#how-do-i-obtain-mine "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------ The library does not yet support authenticating traditionally, so you will have to obtain your token manually. To obtain your token from the Discord client, the easiest way is pasting this into the developer console (CTRL+SHIFT+I): content\_copy (()=>{for(let e of Object.values(webpackChunkdiscord\_app.push(\[\[Symbol()\],{},e\=>e.c\])))try{if(!e.exports||e.exports\===window)continue;if(e.exports?.getToken)return e.exports.getToken();for(let t in e.exports)if(e.exports?.\[t\]?.getToken&&"IntlMessagesProxy"!==e.exports\[t\]\[Symbol.toStringTag\])return e.exports\[t\].getToken()}catch{}})(); Or, you can do it manually: 1. Open developer tools (CTRL+SHIFT+I). 2. Click the Network tab. 3. Click the XHR tab. 4. Select a request and click the Headers tab. 5. Copy-paste the value in the Authorization header. arrow\_upward to top --- # Setting Up Logging View Documentation For discord discord.ext.commands discord.ext.tasks search settings New in version 0.6.0. Setting Up Logging[¶](https://discordpy-self.readthedocs.io/en/latest/logging.html#setting-up-logging "Permalink to this headline") ==================================================================================================================================== _discord.py-self_ logs errors and debug information via the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.14)") python module. In order to streamline this process, the library provides default configuration for the `discord` logger when using [`Client.run()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.run "discord.Client.run") . It is strongly recommended that the logging module is configured, as no errors or warnings will be output if it is not set up. The default logging configuration provided by the library will print to [`sys.stderr`](https://docs.python.org/3/library/sys.html#sys.stderr "(in Python v3.14)") using coloured output. You can configure it to send to a file instead by using one of the built-in [`logging.handlers`](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers "(in Python v3.14)") , such as [`logging.FileHandler`](https://docs.python.org/3/library/logging.handlers.html#logging.FileHandler "(in Python v3.14)") . This can be done by passing it through [`Client.run()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.run "discord.Client.run") : content\_copy import logging handler \= logging.FileHandler(filename\='discord.log', encoding\='utf-8', mode\='w') \# Assume client refers to a discord.Client subclass... client.run(token, log\_handler\=handler) You can also disable the library’s logging configuration completely by passing `None`: content\_copy client.run(token, log\_handler\=None) Likewise, configuring the log level to `logging.DEBUG` is also possible: content\_copy import logging handler \= logging.FileHandler(filename\='discord.log', encoding\='utf-8', mode\='w') \# Assume client refers to a discord.Client subclass... client.run(token, log\_handler\=handler, log\_level\=logging.DEBUG) This is recommended, especially at verbose levels such as `DEBUG`, as there are a lot of events logged and it would clog the stderr of your program. If you want the logging configuration the library provides to affect all loggers rather than just the `discord` logger, you can pass `root_logger=True` inside [`Client.run()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.run "discord.Client.run") : content\_copy client.run(token, log\_handler\=handler, root\_logger\=True) If you want to setup logging using the library provided configuration without using [`Client.run()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.run "discord.Client.run") , you can use [`discord.utils.setup_logging()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.utils.setup_logging "discord.utils.setup_logging") : content\_copy import discord discord.utils.setup\_logging() \# or, for example discord.utils.setup\_logging(level\=logging.INFO, root\=False) More advanced setups are possible with the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.14)") module. The example below configures a rotating file handler that outputs DEBUG output for everything the library outputs, except for HTTP requests: content\_copy import discord import logging import logging.handlers logger \= logging.getLogger('discord') logger.setLevel(logging.DEBUG) logging.getLogger('discord.http').setLevel(logging.INFO) handler \= logging.handlers.RotatingFileHandler( filename\='discord.log', encoding\='utf-8', maxBytes\=32 \* 1024 \* 1024, \# 32 MiB backupCount\=5, \# Rotate through 5 files ) dt\_fmt \= '%Y-%m-%d %H:%M:%S' formatter \= logging.Formatter('\[{asctime}\] \[{levelname:<8}\] {name}: {message}', dt\_fmt, style\='{') handler.setFormatter(formatter) logger.addHandler(handler) \# Assume client refers to a discord.Client subclass... \# Suppress the default configuration since we have our own client.run(token, log\_handler\=None) For more information, check the documentation and tutorial of the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.14)") module. Changed in version 2.0: The library now provides a default logging configuration. arrow\_upward to top --- # Guild Subscriptions View Documentation For discord discord.ext.commands discord.ext.tasks search settings Guild Subscriptions[¶](https://discordpy-self.readthedocs.io/en/latest/guild_subscriptions.html#guild-subscriptions "Permalink to this headline") ================================================================================================================================================== Guild subscriptions are a way for a client to limit the events it receives from a guild. While this is useful for a traditional client, it may not be of much use for a bot, so the default library behavior is to subscribe to as much as possible at startup. The client is automatically subscribed to all guilds with less than 75,000 members on connect. For guilds the client is not subscribed to, you will not receive non-stateful events (e.g. [`discord.on_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message "discord.on_message") , [`discord.on_message_edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message_edit "discord.on_message_edit") , [`discord.on_message_delete()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message_delete "discord.on_message_delete") , etc.). Additionally, voice states and channel unreads are kept up to date passively, as the client does not receive events for these updates in real-time. For every guild, clients can opt to subscribe to additional features, such as typing events (i.e. [`discord.on_typing()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_typing "discord.on_typing") ), a full thread list cache, and member updates (i.e. [`discord.on_member_join()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_member_join "discord.on_member_join") , [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_member_update "discord.on_member_update") , and [`discord.on_member_remove()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_member_remove "discord.on_member_remove") ). Additionally, clients can subscribe to specific members and threads within a guild. When subscribed to specific members (or thread member lists), the client will receive member and presence updates for those members (i.e. [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_member_update "discord.on_member_update") and [`discord.on_presence_update()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_presence_update "discord.on_presence_update") ). Additionally, for guilds with less than 75,000 members, the client is automatically subscribed to all friends, implicit relationships, and members the user has open DMs with at startup. Irrespective of subscribed members, events for actions the client performs (e.g. changing a user’s nickname, kicking a user, banning a user, etc.) will always be received. While events like [`discord.on_raw_member_remove()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_raw_member_remove "discord.on_raw_member_remove") are always dispatched when received, events like [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_member_update "discord.on_member_update") are only dispatched if the member is present in the cache. Guild subscriptions are also used to subscribe to the member list of a specific channel in a guild, but this ability is not yet exposed in the library. Drawbacks[¶](https://discordpy-self.readthedocs.io/en/latest/guild_subscriptions.html#drawbacks "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------ For library users, the biggest drawback to guild subscriptions is that there is no way to reliably get the entire member list of a guild. An additional drawback is that there is no way to subscribe to presence updates for all members in a guild. At most, you can subscribe to presence updates for specific members and thread member lists. Note that clients always receive presence updates for friends, implicit relationships, and users they have an open DM (and mutual server) with. Implementation[¶](https://discordpy-self.readthedocs.io/en/latest/guild_subscriptions.html#implementation "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------------------------- If you would like to override the default behavior and manage guild subscriptions yourself, you can set the `guild_subscriptions` parameter to `False` when creating a [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") . If you do this, you cannot use the `chunk_guilds_at_startup` parameter, as it is dependent on guild subscriptions. To subscribe to a guild (and manage features), see the [`Guild.subscribe()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.subscribe "discord.Guild.subscribe") method. To manage subscriptions to a guild’s members or threads, see the [`Guild.subscribe_to()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.subscribe_to "discord.Guild.subscribe_to") and [`Guild.unsubscribe_from()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.unsubscribe_from "discord.Guild.unsubscribe_from") methods. Subscription requests are debounced before being sent to the Gateway, so changes may take up to half a second to take effect (this is an implementation detail that may be changed at any time). arrow\_upward to top --- # Search View Documentation For discord discord.ext.commands discord.ext.tasks search settings Search ====== Searching for multiple words only shows matches that contain all words. arrow\_upward to top --- # discord.ext.commands – Bot commands framework View Documentation For discord discord.ext.commands discord.ext.tasks search settings `discord.ext.commands` – Bot commands framework[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands-bot-commands-framework "Permalink to this headline") ===================================================================================================================================================================================================== `discord.py` offers a lower level aspect on interacting with Discord. Often times, the library is used for the creation of bots. However this task can be daunting and confusing to get correctly the first time. Many times there comes a repetition in creating a bot command framework that is extensible, flexible, and powerful. For this reason, `discord.py` comes with an extension library that handles this for you. * [Commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/commands.html) * [Parameters](https://discordpy-self.readthedocs.io/en/latest/ext/commands/commands.html#parameters) * [Invocation Context](https://discordpy-self.readthedocs.io/en/latest/ext/commands/commands.html#invocation-context) * [Converters](https://discordpy-self.readthedocs.io/en/latest/ext/commands/commands.html#converters) * [Parameter Metadata](https://discordpy-self.readthedocs.io/en/latest/ext/commands/commands.html#parameter-metadata) * [Error Handling](https://discordpy-self.readthedocs.io/en/latest/ext/commands/commands.html#error-handling) * [Checks](https://discordpy-self.readthedocs.io/en/latest/ext/commands/commands.html#checks) * [Cogs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/cogs.html) * [Quick Example](https://discordpy-self.readthedocs.io/en/latest/ext/commands/cogs.html#quick-example) * [Cog Registration](https://discordpy-self.readthedocs.io/en/latest/ext/commands/cogs.html#cog-registration) * [Using Cogs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/cogs.html#using-cogs) * [Special Methods](https://discordpy-self.readthedocs.io/en/latest/ext/commands/cogs.html#special-methods) * [Meta Options](https://discordpy-self.readthedocs.io/en/latest/ext/commands/cogs.html#meta-options) * [Inspection](https://discordpy-self.readthedocs.io/en/latest/ext/commands/cogs.html#inspection) * [Extensions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/extensions.html) * [Primer](https://discordpy-self.readthedocs.io/en/latest/ext/commands/extensions.html#primer) * [Reloading](https://discordpy-self.readthedocs.io/en/latest/ext/commands/extensions.html#reloading) * [Cleaning Up](https://discordpy-self.readthedocs.io/en/latest/ext/commands/extensions.html#cleaning-up) * [API Reference](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html) * [Bots](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#bots) * [Prefix Helpers](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#prefix-helpers) * [Event Reference](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#event-reference) * [Commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#commands) * [Cogs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#cogs) * [Help Commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#help-commands) * [Enums](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#enums) * [Checks](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#checks) * [Cooldown](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#cooldown) * [Context](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#context) * [Converters](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#converters) * [Defaults](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#defaults) * [Exceptions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#exceptions) arrow\_upward to top --- # discord.ext.tasks – asyncio.Task helpers View Documentation For discord discord.ext.commands discord.ext.tasks search settings `discord.ext.tasks` – asyncio.Task helpers[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord-ext-tasks-asyncio-task-helpers "Permalink to this headline") ======================================================================================================================================================================================== New in version 1.1.0. One of the most common operations when making a bot is having a loop run in the background at a specified interval. This pattern is very common but has a lot of things you need to look out for: * How do I handle [`asyncio.CancelledError`](https://docs.python.org/3/library/asyncio-exceptions.html#asyncio.CancelledError "(in Python v3.14)") ? * What do I do if the internet goes out? * What is the maximum number of seconds I can sleep anyway? The goal of this discord.py extension is to abstract all these worries away from you. Recipes[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#recipes "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------- A simple background task in a [`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") : content\_copy from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self): self.index \= 0 self.printer.start() def cog\_unload(self): self.printer.cancel() @tasks.loop(seconds\=5.0) async def printer(self): print(self.index) self.index += 1 Adding an exception to handle during reconnect: content\_copy import asyncpg from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.data \= \[\] self.batch\_update.add\_exception\_type(asyncpg.PostgresConnectionError) self.batch\_update.start() def cog\_unload(self): self.batch\_update.cancel() @tasks.loop(minutes\=5.0) async def batch\_update(self): async with self.bot.pool.acquire() as con: \# batch update here... pass Looping a certain amount of times before exiting: content\_copy from discord.ext import tasks import discord @tasks.loop(seconds\=5.0, count\=5) async def slow\_count(): print(slow\_count.current\_loop) @slow\_count.after\_loop async def after\_slow\_count(): print('done!') class MyClient(discord.Client): async def setup\_hook(self): slow\_count.start() Waiting until the bot is ready before the loop starts: content\_copy from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.index \= 0 self.bot \= bot self.printer.start() def cog\_unload(self): self.printer.cancel() @tasks.loop(seconds\=5.0) async def printer(self): print(self.index) self.index += 1 @printer.before\_loop async def before\_printer(self): print('waiting...') await self.bot.wait\_until\_ready() Doing something during cancellation: content\_copy from discord.ext import tasks, commands import asyncio class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.\_batch \= \[\] self.lock \= asyncio.Lock() self.bulker.start() async def cog\_unload(self): self.bulker.cancel() async def do\_bulk(self): \# bulk insert data here ... @tasks.loop(seconds\=10.0) async def bulker(self): async with self.lock: await self.do\_bulk() @bulker.after\_loop async def on\_bulker\_cancel(self): if self.bulker.is\_being\_cancelled() and len(self.\_batch) != 0: \# if we're cancelled and we have some data left... \# let's insert it to our database await self.do\_bulk() Doing something at a specific time each day: content\_copy import datetime from discord.ext import commands, tasks utc \= datetime.timezone.utc \# If no tzinfo is given then UTC is assumed. time \= datetime.time(hour\=8, minute\=30, tzinfo\=utc) class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.my\_task.start() def cog\_unload(self): self.my\_task.cancel() @tasks.loop(time\=time) async def my\_task(self): print("My task is running!") Doing something at multiple specific times each day: content\_copy import datetime from discord.ext import commands, tasks utc \= datetime.timezone.utc \# If no tzinfo is given then UTC is assumed. times \= \[\ datetime.time(hour\=8, tzinfo\=utc),\ datetime.time(hour\=12, minute\=30, tzinfo\=utc),\ datetime.time(hour\=16, minute\=40, second\=30, tzinfo\=utc)\ \] class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.my\_task.start() def cog\_unload(self): self.my\_task.cancel() @tasks.loop(time\=times) async def my\_task(self): print("My task is running!") API Reference[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#api-reference "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------------------- _class_ discord.ext.tasks.Loop[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop "Permalink to this definition") Attributes * [current\_loop](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.current_loop) * [hours](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.hours) * [minutes](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.minutes) * [next\_iteration](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.next_iteration) * [seconds](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.seconds) * [time](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.time) Methods * async[\_\_call\_\_](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.__call__) * def[add\_exception\_type](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.add_exception_type) * @[after\_loop](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.after_loop) * @[before\_loop](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop) * def[cancel](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.cancel) * def[change\_interval](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.change_interval) * def[clear\_exception\_types](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types) * @[error](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.error) * def[failed](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.failed) * def[get\_task](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.get_task) * def[is\_being\_cancelled](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled) * def[is\_running](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.is_running) * def[remove\_exception\_type](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.remove_exception_type) * def[restart](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.restart) * def[start](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.start) * def[stop](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.stop) A background task helper that abstracts the loop and reconnection logic for you. The main interface to create this is through [`loop()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.loop "discord.ext.tasks.loop") . @after\_loop[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.after_loop "Permalink to this definition") A decorator that registers a coroutine to be called after the loop finishes running. The coroutine must take no arguments (except `self` in a class context). Note This coroutine is called even during cancellation. If it is desirable to tell apart whether something was cancelled or not, check to see whether [`is_being_cancelled()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled "discord.ext.tasks.Loop.is_being_cancelled") is `True` or not. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register after the loop finishes. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function was not a coroutine. @before\_loop[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop "Permalink to this definition") A decorator that registers a coroutine to be called before the loop starts running. This is useful if you want to wait for some bot state before the loop starts, such as [`discord.Client.wait_until_ready()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.wait_until_ready "discord.Client.wait_until_ready") . The coroutine must take no arguments (except `self` in a class context). Changed in version 2.0: Calling [`stop()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.stop "discord.ext.tasks.Loop.stop") in this coroutine will stop the initial iteration from running. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register before the loop runs. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function was not a coroutine. @error[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.error "Permalink to this definition") A decorator that registers a coroutine to be called if the task encounters an unhandled exception. The coroutine must take only one argument the exception raised (except `self` in a class context). By default this logs to the library logger however it could be overridden to have a different implementation. New in version 1.4. Changed in version 2.0: Instead of writing to `sys.stderr`, the library’s logger is used. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register in the event of an unhandled exception. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function was not a coroutine. _property_ seconds[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.seconds "Permalink to this definition") Read-only value for the number of seconds between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)")\ \] _property_ minutes[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.minutes "Permalink to this definition") Read-only value for the number of minutes between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)")\ \] _property_ hours[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.hours "Permalink to this definition") Read-only value for the number of hours between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)")\ \] _property_ time[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.time "Permalink to this definition") Read-only list for the exact times this loop runs at. `None` if relative times were passed instead. New in version 2.0. Type Optional\[List\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ \]\] _property_ current\_loop[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.current_loop "Permalink to this definition") The current iteration of the loop. Type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") _property_ next\_iteration[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.next_iteration "Permalink to this definition") When the next iteration of the loop will occur. New in version 1.3. Type Optional\[[`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.14)")\ \] _await_ \_\_call\_\_(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.__call__ "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Calls the internal callback that the task holds. New in version 1.6. Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. start(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.start "Permalink to this definition") Starts the internal task in the event loop. Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. Raises [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.14)") – A task has already been launched and is running. Returns The task that has been created. Return type [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.14)") stop()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.stop "Permalink to this definition") Gracefully stops the task from running. Unlike [`cancel()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "discord.ext.tasks.Loop.cancel") , this allows the task to finish its current iteration before gracefully exiting. Note If the internal function raises an error that can be handled before finishing then it will retry until it succeeds. If this is undesirable, either remove the error handling before stopping via [`clear_exception_types()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types "discord.ext.tasks.Loop.clear_exception_types") or use [`cancel()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "discord.ext.tasks.Loop.cancel") instead. Changed in version 2.0: Calling this method in [`before_loop()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop "discord.ext.tasks.Loop.before_loop") will stop the first iteration from running. New in version 1.2. cancel()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "Permalink to this definition") Cancels the internal task, if it is running. restart(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.restart "Permalink to this definition") A convenience method to restart the internal task. Note Due to the way this function works, the task is not returned like [`start()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.start "discord.ext.tasks.Loop.start") . Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. add\_exception\_type(_\*exceptions_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.add_exception_type "Permalink to this definition") Adds exception types to be handled during the reconnect logic. By default the exception types handled are those handled by [`discord.Client.connect()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.connect "discord.Client.connect") , which includes a lot of internet disconnection errors. This function is useful if you’re interacting with a 3rd party library that raises its own set of exceptions. Parameters **\*exceptions** (Type\[[`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.14)")\ \]) – An argument list of exception classes to handle. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – An exception passed is either not a class or not inherited from [`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.14)") . clear\_exception\_types()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types "Permalink to this definition") Removes all exception types that are handled. Note This operation obviously cannot be undone! remove\_exception\_type(_\*exceptions_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.remove_exception_type "Permalink to this definition") Removes exception types from being handled during the reconnect logic. Parameters **\*exceptions** (Type\[[`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.14)")\ \]) – An argument list of exception classes to handle. Returns Whether all exceptions were successfully removed. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") get\_task()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.get_task "Permalink to this definition") Optional\[[`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.14)")\ \]: Fetches the internal task or `None` if there isn’t one running. is\_being\_cancelled()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled "Permalink to this definition") Whether the task is being cancelled. failed()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.failed "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Whether the internal task has failed. New in version 1.2. is\_running()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.is_running "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Check if the task is currently running. New in version 1.4. change\_interval(_\*_, _seconds\=0_, _minutes\=0_, _hours\=0_, _time\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop.change_interval "Permalink to this definition") Changes the interval for the sleep time. New in version 1.2. Parameters * **seconds** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of seconds between every iteration. * **minutes** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of minutes between every iteration. * **hours** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of hours between every iteration. * **time** (Union\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ , Sequence\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ \]\]) – The exact times to run this loop at. Either a non-empty list or a single value of [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)") should be passed. This cannot be used in conjunction with the relative time parameters. New in version 2.0. Note Duplicate times will be ignored, and only run once. Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – An invalid value was given. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – An invalid value for the `time` parameter was passed, or the `time` parameter was passed in conjunction with relative time parameters. @discord.ext.tasks.loop(_\*_, _seconds\=..._, _minutes\=..._, _hours\=..._, _time\=..._, _count\=None_, _reconnect\=True_, _name\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.loop "Permalink to this definition") A decorator that schedules a task in the background for you with optional reconnect logic. The decorator returns a [`Loop`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.Loop "discord.ext.tasks.Loop") . Parameters * **seconds** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of seconds between every iteration. * **minutes** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of minutes between every iteration. * **hours** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of hours between every iteration. * **time** (Union\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ , Sequence\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ \]\]) – The exact times to run this loop at. Either a non-empty list or a single value of [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)") should be passed. Timezones are supported. If no timezone is given for the times, it is assumed to represent UTC time. This cannot be used in conjunction with the relative time parameters. Note Duplicate times will be ignored, and only run once. New in version 2.0. * **count** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The number of loops to do, `None` if it should be an infinite loop. * **reconnect** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to handle errors and restart the task using an exponential back-off algorithm similar to the one used in [`discord.Client.connect()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.connect "discord.Client.connect") . * **name** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The name to assign to the internal task. By default it is assigned a name based off of the callable name such as `discord-ext-tasks: function_name`. New in version 2.1. Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – An invalid value was given. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function was not a coroutine, an invalid value for the `time` parameter was passed, or `time` parameter was passed in conjunction with relative time parameters. arrow\_upward to top --- # Changelog View Documentation For discord discord.ext.commands discord.ext.tasks search settings Changelog[¶](https://discordpy-self.readthedocs.io/en/latest/whats_new.html#changelog "Permalink to this headline") ==================================================================================================================== This page keeps a detailed human friendly rendering of what’s new and changed in specific versions. v2.1.0[¶](https://discordpy-self.readthedocs.io/en/latest/whats_new.html#v2-1-0 "Permalink to this headline") -------------------------------------------------------------------------------------------------------------- Due to the enormous amount of changes in this release, some minor changes may be omitted from this changelog. Please refer to the documentation for more details on specific features. ### New Features[¶](https://discordpy-self.readthedocs.io/en/latest/whats_new.html#new-features "Permalink to this headline") * Add new flags to [`ApplicationFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ApplicationFlags "discord.ApplicationFlags") , [`PublicUserFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PublicUserFlags "discord.PublicUserFlags") , [`MessageFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MessageFlags "discord.MessageFlags") , [`MemberFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MemberFlags "discord.MemberFlags") , [`ChannelFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ChannelFlags "discord.ChannelFlags") , and more * Support new [`MessageType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MessageType "discord.MessageType") values, update [`Message.system_content`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.system_content "discord.Message.system_content") accordingly * Support new [`ConnectionType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ConnectionType "discord.ConnectionType") values * Overhaul rich presence, adding support for viewing and sending all activity fields (including many new fields) * New activity type: [`ActivityType.hang`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ActivityType.hang "discord.ActivityType.hang") , supported via [`HangActivity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HangActivity "discord.HangActivity") * New classes: [`ActivityParty`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ActivityParty "discord.ActivityParty") , [`ActivityAssets`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ActivityAssets "discord.ActivityAssets") , [`ActivitySecrets`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ActivitySecrets "discord.ActivitySecrets") , and [`ActivityTimestamps`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ActivityTimestamps "discord.ActivityTimestamps") * Deprecated [`Game`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Game "discord.Game") and [`Streaming`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Streaming "discord.Streaming") in favour of [`Activity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Activity "discord.Activity") * Made [`Spotify`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Spotify "discord.Spotify") constructible and sendable via [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.change_presence "discord.Client.change_presence") * Add [`Client.proxy_external_application_assets()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.proxy_external_application_assets "discord.Client.proxy_external_application_assets") to proxy external assets for rich presence * Support read states * New low-level interface: [`ReadState`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ReadState "discord.ReadState") * Access all read states from [`Client.read_states`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.read_states "discord.Client.read_states") and access per-channel read states via the [`TextChannel.read_state`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel.read_state "discord.TextChannel.read_state") attribute * Add rich attributes: [`TextChannel.acked_message_id`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel.acked_message_id "discord.TextChannel.acked_message_id") , [`TextChannel.acked_message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel.acked_message "discord.TextChannel.acked_message") , [`TextChannel.acked_pin_timestamp`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel.acked_pin_timestamp "discord.TextChannel.acked_pin_timestamp") , [`TextChannel.mention_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel.mention_count "discord.TextChannel.mention_count") , and [`TextChannel.last_viewed_timestamp`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel.last_viewed_timestamp "discord.TextChannel.last_viewed_timestamp") * Add [`abc.Messageable.unack()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.unack "discord.abc.Messageable.unack") to unacknowledge all messages in a channel * Add [`Client.bulk_ack()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.bulk_ack "discord.Client.bulk_ack") to acknowledge multiple read states at once * Support experiments * Add [`UserExperiment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserExperiment "discord.UserExperiment") and [`GuildExperiment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildExperiment "discord.GuildExperiment") * Access user experiments via [`Client.experiments`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.experiments "discord.Client.experiments") and guild experiments via [`Client.guild_experiments`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.guild_experiments "discord.Client.guild_experiments") * Add [`Client.get_experiment()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.get_experiment "discord.Client.get_experiment") helper and [`Client.fetch_experiments()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_experiments "discord.Client.fetch_experiments") coroutine * Add message search functionality * Search guilds with [`Guild.search()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.search "discord.Guild.search") * Search channels with [`abc.Messageable.search()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.search "discord.abc.Messageable.search") * Add support for the new username system (also known as “pomelo”) * Add [`User.is_pomelo()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User.is_pomelo "discord.User.is_pomelo") to check if a user has been migrated * Add [`User.global_name`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User.global_name "discord.User.global_name") to get their global nickname or “display name” * Update [`User.display_name`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User.display_name "discord.User.display_name") and [`Member.display_name`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Member.display_name "discord.Member.display_name") to understand global nicknames * Update `__str__` for [`User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User") to drop discriminators if the user has been migrated * Update [`Guild.get_member_named()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.get_member_named "discord.Guild.get_member_named") to work with migrated users * Update [`User.default_avatar`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User.default_avatar "discord.User.default_avatar") to work with migrated users * Update [`ClientUser.edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientUser.edit "discord.ClientUser.edit") to allow migrating and changing global names * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Update user and member converters to understand migrated users * Add GCP uploads * Allows pre-uploading files to Google Cloud Storage for faster file sending * Supports uploading in parallel and allows reusing previously uploaded files * Allows sending files up to 500 MiB each (Nitro only) * Implemented via [`CloudFile`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.CloudFile "discord.CloudFile") and [`abc.Messageable.upload_files()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.upload_files "discord.abc.Messageable.upload_files") * The [`CloudFile`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.CloudFile "discord.CloudFile") instances can be used in place of [`File`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.File "discord.File") instances when sending messages * Support application command fetching V3 * Add [`abc.Messageable.application_commands()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.application_commands "discord.abc.Messageable.application_commands") and [`Guild.application_commands()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.application_commands "discord.Guild.application_commands") to get all application commands in a guild or private channel * Alias and deprecate all old application command fetching methods * It is highly recommended that the result of this method is cached to avoid rate limits * Support hubs * Add [`DirectoryChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.DirectoryChannel "discord.DirectoryChannel") , [`DirectoryEntry`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.DirectoryEntry "discord.DirectoryEntry") , and relevant methods for fetching and creating * Add [`Guild.hub_type`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.hub_type "discord.Guild.hub_type") * Add [`Client.join_hub_waitlist()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.join_hub_waitlist "discord.Client.join_hub_waitlist") , [`Client.lookup_hubs()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.lookup_hubs "discord.Client.lookup_hubs") , and [`Client.join_hub()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.join_hub "discord.Client.join_hub") * Support friend suggestions * Add [`FriendSuggestion`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.FriendSuggestion "discord.FriendSuggestion") and [`Client.friend_suggestion_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.friend_suggestion_count "discord.Client.friend_suggestion_count") * Add [`Client.friend_suggestions()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.friend_suggestions "discord.Client.friend_suggestions") * Add new events, [`on_friend_suggestion_add()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_friend_suggestion_add "discord.on_friend_suggestion_add") and [`on_friend_suggestion_remove()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_friend_suggestion_remove "discord.on_friend_suggestion_remove") * Support OAuth2 authorizations * Add [`Client.oauth2_tokens()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.oauth2_tokens "discord.Client.oauth2_tokens") , [`Client.fetch_authorization()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_authorization "discord.Client.fetch_authorization") , [`Client.create_authorization()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.create_authorization "discord.Client.create_authorization") * Heavily improve guild subscriptions * \[BREAKING\] Remove `Guild.request` method; use [`Guild.subscribe()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.subscribe "discord.Guild.subscribe") instead * Allow disabling auto guild subscription via `guild_subscriptions` parameter in [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") * Add [`Guild.is_subscribed()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.is_subscribed "discord.Guild.is_subscribed") and [`Guild.is_subscribed_to()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.is_subscribed_to "discord.Guild.is_subscribed_to") to check if the client is subscribed to a guild * Add [`Guild.subscribe()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.subscribe "discord.Guild.subscribe") and [`Guild.subscribe_to()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.subscribe_to "discord.Guild.subscribe_to") to allow manually managing guild subscriptions * \[BREAKING\] User notes handling is now entirely rewritten * The `UserNote` class is removed; notes are now represented as strings * `Client.notes` is renamed to [`Client.fetch_notes()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_notes "discord.Client.fetch_notes") for forward-compatibility * Update various payment and billing related models to add new fields * \[BREAKING\] Remove `Payment.refund` as it is no longer supported by the API * Add `BRAINTREE_KEY`, `STRIPE_KEY`, and `ADYEN_KEY` to package exports * Add `message_send_cooldown` and `thread_create_cooldown` attributes to the [`abc.Messageable.typing()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.typing "discord.abc.Messageable.typing") context manager. * Add [`Client.channel_affinities()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.channel_affinities "discord.Client.channel_affinities") to get channel affinities and [`Client.premium_affinities()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.premium_affinities "discord.Client.premium_affinities") to get premium user affinities * Add various new fields to [`Application`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Application "discord.Application") and [`PartialApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialApplication "discord.PartialApplication") , update implementations to match API * Allow passing `activities`, `afk`, and `idle_since` to [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") for initial presence setup * Add [`Client.is_afk()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.is_afk "discord.Client.is_afk") and [`Client.idle_since`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.idle_since "discord.Client.idle_since") helpers * Allow passing `preferred_rtc_regions` to [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") to override Discord’s suggested RTC regions * \[BREAKING\] Rename `Client.preferred_voice_regions` to [`Client.preferred_rtc_regions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.preferred_rtc_regions "discord.Client.preferred_rtc_regions") to match the API * \[BREAKING\] Rename `Client.fetch_preferred_voice_regions` to [`Client.fetch_preferred_rtc_regions()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_preferred_rtc_regions "discord.Client.fetch_preferred_rtc_regions") to match the API * \[BREAKING\] Remove `preferred_region` from [`Client.change_voice_state()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.change_voice_state "discord.Client.change_voice_state") and [`Guild.change_voice_state()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.change_voice_state "discord.Guild.change_voice_state") * Allow setting the [`Client.preferred_rtc_regions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.preferred_rtc_regions "discord.Client.preferred_rtc_regions") property after initialisation * Allow passing `canary` to [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") to use the canary API * Allow passing `timezone` to [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") to configure the timezone broadcasted to Discord * Add [`Tutorial`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Tutorial "discord.Tutorial") and [`Client.tutorial`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.tutorial "discord.Client.tutorial") to access new user tutorial information * Add `with_permissions` to [`Client.fetch_invite()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_invite "discord.Client.fetch_invite") * Add [`Client.create_invite()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.create_invite "discord.Client.create_invite") and [`Client.revoke_invites()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.revoke_invites "discord.Client.revoke_invites") to create and revoke friend invites * Allow [`Client.create_group()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.create_group "discord.Client.create_group") to create a group channel with only one other recipient * \[BREAKING\] Rename `Client.relationship_activity_statistics` to [`Client.global_activity_statistics()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.global_activity_statistics "discord.Client.global_activity_statistics") to better reflect its purpose * Add [`Client.user_offer()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.user_offer "discord.Client.user_offer") to replace deprecated [`Client.trial_offer()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.trial_offer "discord.Client.trial_offer") * Add [`Client.report_unverified_application()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.report_unverified_application "discord.Client.report_unverified_application") to report game detection issues * Add [`Client.recent_avatars()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.recent_avatars "discord.Client.recent_avatars") to get recently used avatars * Add [`Guild.query_recent_members()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.query_recent_members "discord.Guild.query_recent_members") to fetch members who recently joined * Add various new fields to [`UserProfile`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserProfile "discord.UserProfile") and [`MemberProfile`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MemberProfile "discord.MemberProfile") * Note that nearly all fields are unavailable if the user has blocked the client user. This can be determined with [`UserProfile.is_blocker()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserProfile.is_blocker "discord.UserProfile.is_blocker") * Add [`DefaultAvatar.pink`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.DefaultAvatar.pink "discord.DefaultAvatar.pink") for new pink default avatars * Add [`Colour.pink()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.pink "discord.Colour.pink") to get the pink default avatar colour * Add support for voice messages ([GH-9358](https://github.com/dolfies/discord.py-self/issues/9358) ) * Add [`Attachment.duration`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Attachment.duration "discord.Attachment.duration") and [`Attachment.waveform`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Attachment.waveform "discord.Attachment.waveform") * Add [`Attachment.is_voice_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Attachment.is_voice_message "discord.Attachment.is_voice_message") * This does not support _sending_ voice messages yet * Add support for [`TextChannel.default_thread_slowmode_delay`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel.default_thread_slowmode_delay "discord.TextChannel.default_thread_slowmode_delay") * Add support for [`ForumChannel.default_sort_order`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ForumChannel.default_sort_order "discord.ForumChannel.default_sort_order") * Add support for `default_reaction_emoji` and `default_forum_layout` in [`Guild.create_forum()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.create_forum "discord.Guild.create_forum") * Add support for `widget_channel`, `widget_enabled`, and `mfa_level` in [`Guild.edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.edit "discord.Guild.edit") * Add various new [`Permissions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Permissions "discord.Permissions") and changes * Add support for `with_counts` parameter to [`Client.fetch_guilds()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_guilds "discord.Client.fetch_guilds") * Add new [`Guild.get_emoji()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.get_emoji "discord.Guild.get_emoji") helper * Add [`Guild.max_stage_video_channel_users`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.max_stage_video_channel_users "discord.Guild.max_stage_video_channel_users") and [`Guild.safety_alerts_channel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.safety_alerts_channel "discord.Guild.safety_alerts_channel") * Add support for `raid_alerts_disabled` and `safety_alerts_channel` in [`Guild.edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.edit "discord.Guild.edit") . * Add support for Polls ([GH-9759](https://github.com/dolfies/discord.py-self/issues/9759) ). * Polls can be created using [`Poll`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Poll "discord.Poll") and the `poll` keyword-only parameter in various message sending methods * Add [`PollAnswer`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PollAnswer "discord.PollAnswer") and [`PollMedia`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PollMedia "discord.PollMedia") * Add [`Message.end_poll()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.end_poll "discord.Message.end_poll") method to end polls * Add new events, [`on_poll_vote_add()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_poll_vote_add "discord.on_poll_vote_add") , [`on_poll_vote_remove()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_poll_vote_remove "discord.on_poll_vote_remove") , [`on_raw_poll_vote_add()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_raw_poll_vote_add "discord.on_raw_poll_vote_add") , and [`on_raw_poll_vote_remove()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_raw_poll_vote_remove "discord.on_raw_poll_vote_remove") * Voice handling has been completely rewritten to fix many bugs * Add support for [`RawReactionActionEvent.message_author_id`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.RawReactionActionEvent.message_author_id "discord.RawReactionActionEvent.message_author_id") * Add support for [`AuditLogAction.creator_monetization_request_created`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AuditLogAction.creator_monetization_request_created "discord.AuditLogAction.creator_monetization_request_created") and [`AuditLogAction.creator_monetization_terms_accepted`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AuditLogAction.creator_monetization_terms_accepted "discord.AuditLogAction.creator_monetization_terms_accepted") * Add support for [`AttachmentFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AttachmentFlags "discord.AttachmentFlags") , accessed via [`Attachment.flags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Attachment.flags "discord.Attachment.flags") * Add support for [`RoleFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.RoleFlags "discord.RoleFlags") , accessed via [`Role.flags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Role.flags "discord.Role.flags") * Add support for [`ChannelType.media`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ChannelType.media "discord.ChannelType.media") , accessed via [`ForumChannel.is_media()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ForumChannel.is_media "discord.ForumChannel.is_media") * Add shortcut for [`CategoryChannel.forums`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.CategoryChannel.forums "discord.CategoryChannel.forums") . * Add encoder options to [`VoiceClient.play()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.VoiceClient.play "discord.VoiceClient.play") * Add optional attribute `integration_type` in [`AuditLogEntry.extra`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AuditLogEntry.extra "discord.AuditLogEntry.extra") for `kick` or `member_role_update` actions * Add support for reading burst reactions * Add [`Reaction.normal_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Reaction.normal_count "discord.Reaction.normal_count") * Add [`Reaction.burst_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Reaction.burst_count "discord.Reaction.burst_count") * Add [`Reaction.me_burst`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Reaction.me_burst "discord.Reaction.me_burst") * Add `scheduled_event` parameter for [`StageChannel.create_instance()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StageChannel.create_instance "discord.StageChannel.create_instance") * Add support for auto mod members * Add `type` keyword argument to [`AutoModRuleAction`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AutoModRuleAction "discord.AutoModRuleAction") * Add [`AutoModTrigger.mention_raid_protection`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AutoModTrigger.mention_raid_protection "discord.AutoModTrigger.mention_raid_protection") * Add [`AutoModRuleTriggerType.member_profile`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AutoModRuleTriggerType.member_profile "discord.AutoModRuleTriggerType.member_profile") * Add [`AutoModRuleEventType.member_update`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AutoModRuleEventType.member_update "discord.AutoModRuleEventType.member_update") * Add [`AutoModRuleActionType.block_member_interactions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AutoModRuleActionType.block_member_interactions "discord.AutoModRuleActionType.block_member_interactions") * Add support for getting/fetching threads from [`Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") * Add [`PartialMessage.thread`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialMessage.thread "discord.PartialMessage.thread") * Add [`Message.thread`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.thread "discord.Message.thread") * Add [`Message.fetch_thread()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.fetch_thread "discord.Message.fetch_thread") * Add support for adding forum thread tags via webhook * Add [`Locale.latin_american_spanish`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Locale.latin_american_spanish "discord.Locale.latin_american_spanish") * Add support for setting voice channel status * Add support for guild incidents * Updated [`Guild.edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.edit "discord.Guild.edit") with `invites_disabled_until` and `dms_disabled_until` parameters * Add [`Guild.invites_paused_until`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.invites_paused_until "discord.Guild.invites_paused_until") * Add [`Guild.dms_paused_until`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.dms_paused_until "discord.Guild.dms_paused_until") * Add [`Guild.invites_paused()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.invites_paused "discord.Guild.invites_paused") * Add [`Guild.dms_paused()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.dms_paused "discord.Guild.dms_paused") * Add support for [`abc.User.avatar_decoration`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.User.avatar_decoration "discord.abc.User.avatar_decoration") * Add support for GIF stickers * Add support for bulk banning members via [`Guild.bulk_ban()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.bulk_ban "discord.Guild.bulk_ban") * Add `reason` keyword argument to [`Thread.delete()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Thread.delete "discord.Thread.delete") * Add support for reaction types to raw and non-raw models * Add support for message forwarding * Adds [`MessageReferenceType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MessageReferenceType "discord.MessageReferenceType") * Adds [`MessageSnapshot`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MessageSnapshot "discord.MessageSnapshot") * Adds `type` parameter to [`MessageReference`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MessageReference "discord.MessageReference") , [`MessageReference.from_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MessageReference.from_message "discord.MessageReference.from_message") , and [`PartialMessage.to_reference()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialMessage.to_reference "discord.PartialMessage.to_reference") * Add ``PartialMessage.forward`ionCallbackResponse.resource()`` will be different * Add [`PartialWebhookChannel.mention`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialWebhookChannel.mention "discord.PartialWebhookChannel.mention") attribute * Add richer [`Role.move()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Role.move "discord.Role.move") interface * Add support for [`EmbedFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.EmbedFlags "discord.EmbedFlags") via [`Embed.flags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Embed.flags "discord.Embed.flags") * Add [`ForumChannel.members`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ForumChannel.members "discord.ForumChannel.members") property * Add [`PartialMessageable.mention`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialMessageable.mention "discord.PartialMessageable.mention") * Add support for purchase notification messages * Add new type [`MessageType.purchase_notification`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.MessageType.purchase_notification "discord.MessageType.purchase_notification") * Add new models [`GuildProductPurchase`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildProductPurchase "discord.GuildProductPurchase") and [`PurchaseNotification`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PurchaseNotification "discord.PurchaseNotification") * Add [`Message.purchase_notification`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message.purchase_notification "discord.Message.purchase_notification") * Add `category` parameter to [`abc.GuildChannel.clone()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel.clone "discord.abc.GuildChannel.clone") * Parse full message for message edit event * Adds [`RawMessageUpdateEvent.message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.RawMessageUpdateEvent.message "discord.RawMessageUpdateEvent.message") attribute * Potentially speeds up [`on_message_edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message_edit "discord.on_message_edit") by no longer copying data * Allow passing `None` for `scopes` parameter in [`utils.oauth_url()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.utils.oauth_url "discord.utils.oauth_url") * Add [`Guild.dm_spam_detected_at`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.dm_spam_detected_at "discord.Guild.dm_spam_detected_at") and [`Guild.is_dm_spam_detected()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.is_dm_spam_detected "discord.Guild.is_dm_spam_detected") * Add [`Guild.raid_detected_at`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.raid_detected_at "discord.Guild.raid_detected_at") and [`Guild.is_raid_detected()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.is_raid_detected "discord.Guild.is_raid_detected") * Add [`Client.fetch_sticker_pack()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_sticker_pack "discord.Client.fetch_sticker_pack") * Add [`Guild.fetch_role()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.fetch_role "discord.Guild.fetch_role") * Add new [`Attachment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Attachment "discord.Attachment") fields * Add [`Member.guild_banner`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Member.guild_banner "discord.Member.guild_banner") and [`Member.display_banner`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Member.display_banner "discord.Member.display_banner") * Add support for guild tags (also known as primary guilds) * This is through the [`PrimaryGuild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PrimaryGuild "discord.PrimaryGuild") class * You retrieve this via [`Member.primary_guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Member.primary_guild "discord.Member.primary_guild") * Add support for the new pins endpoint * This turns [`abc.Messageable.pins()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.pins "discord.abc.Messageable.pins") into an async iterator * The old eager behaviour of using `await` is still supported, but is now deprecated * Add support for guild onboarding * Completing onboarding is still not supported * Add support new gradient and holographic role colours * Add [`Locale.language_code`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Locale.language_code "discord.Locale.language_code") attribute * Add support for guest invites * Add `File.uri` to get the `attachment://` URI of a file * Add ability to create a media-only forum channel via `media` parameter in [`Guild.create_forum()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.create_forum "discord.Guild.create_forum") * Add new colours from the new Discord themes * This updates the old [`Colour.dark_theme()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.dark_theme "discord.Colour.dark_theme") , [`Colour.light_theme()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.light_theme "discord.Colour.light_theme") , [`Colour.light_embed()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.light_embed "discord.Colour.light_embed") and [`Colour.dark_embed()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.dark_embed "discord.Colour.dark_embed") * This adds [`Colour.ash_theme()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.ash_theme "discord.Colour.ash_theme") , [`Colour.ash_embed()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.ash_embed "discord.Colour.ash_embed") , [`Colour.onyx_theme()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.onyx_theme "discord.Colour.onyx_theme") , and [`Colour.onyx_embed()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.onyx_embed "discord.Colour.onyx_embed") * \[[ext.tasks](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord-ext-tasks)\ \] Add `name` parameter to [`loop()`](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord.ext.tasks.loop "discord.ext.tasks.loop") to name the internal [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.14)") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Add fallback behaviour to `CurrentGuild` * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Add logging for errors that occur during [`cog_unload()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_unload "discord.ext.commands.Cog.cog_unload") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Add support for [`typing.NewType`](https://docs.python.org/3/library/typing.html#typing.NewType "(in Python v3.14)") and `type` keyword type aliases * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Add support for positional-only flag parameters * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Add support for channel URLs in ChannelConverter related classes * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Add [`BadLiteralArgument.argument`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BadLiteralArgument.argument "discord.ext.commands.BadLiteralArgument.argument") to get the failed argument’s value * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Add [`Context.filesize_limit`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context.filesize_limit "discord.ext.commands.Context.filesize_limit") property * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Add support for [`Parameter.displayed_name`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter.displayed_name "discord.ext.commands.Parameter.displayed_name") ### Bug Fixes[¶](https://discordpy-self.readthedocs.io/en/latest/whats_new.html#bug-fixes "Permalink to this headline") * Fix TLS fingerprinting issues causing unnecessary CAPTCHA challenges and blocked requests * Fix the type of [`ClientUser.phone`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientUser.phone "discord.ClientUser.phone") to be a string * Fix various state issues when managing guild subscriptions * \[BREAKING\] Remove no longer functional `validate` parameter from [`abc.GuildChannel.create_invite()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel.create_invite "discord.abc.GuildChannel.create_invite") * Improve presence syncing to reduce unnecessary updates and lost presences * \[BREAKING\] Update return type of [`Client.detectable_applications()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.detectable_applications "discord.Client.detectable_applications") to fix a crash due to an API change * \[BREAKING\] Remove nonexistant `Gift.revoked` attribute * \[BREAKING\] Rename `Guild.owner_application_id` to `Guild.application_id` to match API and upstream * \[BREAKING\] Remove no longer functional `Guild.application_command_counts` attribute * Fix crash in [`Integration`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Integration "discord.Integration") with the Twitch integration ID being a string * Improve member and relationship presence support and handling * Fix `FileHandler` handlers being written ANSI characters when the bot is executed inside PyCharm * This has the side effect of removing coloured logs from the PyCharm terminal due an upstream bug involving TTY detection. This issue is tracked under [PY-43798](https://youtrack.jetbrains.com/issue/PY-43798) * Fix channel edits with [`Webhook.edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Webhook.edit "discord.Webhook.edit") sending two requests instead of one * Fix [`StageChannel.last_message_id`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StageChannel.last_message_id "discord.StageChannel.last_message_id") always being `None` * Fix piped audio input ending prematurely * Fix AutoMod audit log entry error due to empty `channel_id` * Fix handling of `around` parameter in [`abc.Messageable.history()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable.history "discord.abc.Messageable.history") * Fix [`utils.escape_markdown()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.utils.escape_markdown "discord.utils.escape_markdown") not escaping the new markdown * Fix webhook targets not being converted in audit logs * Fix error when not passing `enabled` in [`Guild.create_automod_rule()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.create_automod_rule "discord.Guild.create_automod_rule") * Fix how various parameters are handled in [`Guild.create_scheduled_event()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.create_scheduled_event "discord.Guild.create_scheduled_event") * Fix not sending the `ssrc` parameter when sending the `SPEAKING` voice payload * Fix username lookup in [`Guild.get_member_named()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.get_member_named "discord.Guild.get_member_named") * Fix false positives in [`PartialEmoji.from_str()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialEmoji.from_str "discord.PartialEmoji.from_str") inappropriately setting `animated` to `True` * Fix `NameError` when using [`abc.GuildChannel.create_invite()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel.create_invite "discord.abc.GuildChannel.create_invite") * Fix escape behaviour for lists and headers in [`escape_markdown()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.utils.escape_markdown "discord.utils.escape_markdown") * Fixes and improvements for [`FFmpegAudio`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.FFmpegAudio "discord.FFmpegAudio") and all related subclasses * Fix [`Template.source_guild()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Template.source_guild "discord.Template.source_guild") attempting to resolve from cache * Fix [`IndexError`](https://docs.python.org/3/library/exceptions.html#IndexError "(in Python v3.14)") being raised instead of [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") when calling [`Colour.from_str()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Colour.from_str "discord.Colour.from_str") with an empty string * Fix possible error in voice cleanup logic * Fix possible bad voice state where you move to a voice channel with missing permissions * Fix handling of [`AuditLogDiff`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AuditLogDiff "discord.AuditLogDiff") when relating to auto mod triggers * Fix race condition in voice logic relating to disconnect and connect * Fix restriction on auto moderation audit log ID range * Fix comparison between [`Object`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Object "discord.Object") classes with a `type` set * Fix handling of an enum in [`AutoModRule.edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AutoModRule.edit "discord.AutoModRule.edit") * Fix handling of [`Client.close()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.close "discord.Client.close") within `Client.__aexit__()` * Fix channel deletion not evicting related threads from cache * Fix bug with cache superfluously incrementing role positions * Fix `exempt_channels` not being passed along in [`Guild.create_automod_rule()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.create_automod_rule "discord.Guild.create_automod_rule") * Fix `abc.GuildChannel.purge()` failing if the message was deleted * Handle improper 1000 close code closures by Discord * Add support for AEAD XChaCha20 Poly1305 encryption model * This allows voice to continue working when the older encryption modes eventually get removed * Update all channel clone implementations to work as expected * Fix [`TextChannel.clone()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel.clone "discord.TextChannel.clone") always sending slowmode when not applicable to news channels * Fix [`Sticker.url`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Sticker.url "discord.Sticker.url") for GIF stickers * Fix [`User.default_avatar`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User.default_avatar "discord.User.default_avatar") for team users and webhooks * Fix [`AuditLogEntry.target`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AuditLogEntry.target "discord.AuditLogEntry.target") causing errors for [`AuditLogAction.message_pin`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AuditLogAction.message_pin "discord.AuditLogAction.message_pin") and [`AuditLogAction.message_unpin`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AuditLogAction.message_unpin "discord.AuditLogAction.message_unpin") actions * Fix path sanitisation for absolute Windows paths when using `__main__` * Create [`ScheduledEvent`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ScheduledEvent "discord.ScheduledEvent") on cache miss for [`on_scheduled_event_delete()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_scheduled_event_delete "discord.on_scheduled_event_delete") * Add defaults for [`Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") creation preventing some crashes * Fix voice connection issues and upgrade the voice version to 8 * Fix calculation of hashed rate limit keys * Fix [`Thread.applied_tags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Thread.applied_tags "discord.Thread.applied_tags") being empty for media channels * Fix potentially stuck ratelimit buckets in certain circumstances * Fix audit log `automod_rule_trigger_type` extra being missing * \[[ext.tasks](https://discordpy-self.readthedocs.io/en/latest/ext/tasks/index.html#discord-ext-tasks)\ \] Fix race condition when setting timer handle when using uvloop * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Fix issue with category cooldowns outside of guild channels * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Fix callable FlagConverter defaults on hybrid commands not being called * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Unwrap [`Parameter`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter "discord.ext.commands.Parameter") if given as default to [`parameter()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.parameter "discord.ext.commands.parameter") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Fix fallback behaviour not being respected when calling replace for [`Parameter`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter "discord.ext.commands.Parameter") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Fix [`HelpCommand`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand "discord.ext.commands.HelpCommand") defined checks not carrying over during copy * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Fix the wrong [`on_help_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.on_help_command_error "discord.ext.commands.HelpCommand.on_help_command_error") being called when ejected from a cog * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Fix `=None` being displayed in [`signature`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.signature "discord.ext.commands.Command.signature") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/index.html#discord-ext-commands)\ \] Change lookup order for [`MemberConverter`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MemberConverter "discord.ext.commands.MemberConverter") and [`UserConverter`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.UserConverter "discord.ext.commands.UserConverter") to prioritise usernames instead of nicknames ### Miscellaneous[¶](https://discordpy-self.readthedocs.io/en/latest/whats_new.html#miscellaneous "Permalink to this headline") * Minimum version is now Python 3.10 * New dependency: `curl_cffi` * Update filesize limit constants * Additional documentation added for logging capabilities * Performance increases of constructing [`Permissions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Permissions "discord.Permissions") using keyword arguments * Improve `__repr__` of [`SyncWebhook`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SyncWebhook "discord.SyncWebhook") and [`Webhook`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Webhook "discord.Webhook") * Change internal thread names to be consistent * Use a fallback package for `audioop` to allow the library to work in Python 3.13 or newer * Remove `aiodns` from being used on Windows * Add zstd gateway compression to `speed` extras * This can be installed using `discord.py-self[speed]` * Add proxy support fetching from the CDN * Remove `/` from being safe from URI encoding when constructing paths internally * Sanitize invite argument before calling the invite info endpoint * Avoid returning in finally in specific places to prevent exception swallowing * Deprecate the `with_expiration` parameter in [`Client.fetch_invite()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.fetch_invite "discord.Client.fetch_invite") * Allow creating NSFW voice/stage channels * The [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") is now returned when using [`Invite.delete()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite.delete "discord.Invite.delete") or [`Client.delete_invite()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.delete_invite "discord.Client.delete_invite") * Update PyNaCl minimum version dependency * `AppCommandType` is now `ApplicationCommandType` for consistency; the old name is still available as an alias * `AppCommandOptionType` is now `ApplicationCommandOptionType` for consistency; the old name is still available as an alias * \[BREAKING\] Remove all achievement support as the endpoints have been removed by Discord * \[BREAKING\] Updated CAPTCHA handler implementation * The old `CaptchaHandler` class has been removed * New interface is via the `captcha_handler` parameter in [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") , which accepts a [`CaptchaRequired`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.CaptchaRequired "discord.CaptchaRequired") class instance and the [`Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") itself as parameters * You can also override [`Client.handle_captcha()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client.handle_captcha "discord.Client.handle_captcha") in a subclass * \[BREAKING\] Swap all `exclude_*` parameters in fetch methods to `include_*` parameters for consistency v2.0.0[¶](https://discordpy-self.readthedocs.io/en/latest/whats_new.html#v2-0-0 "Permalink to this headline") -------------------------------------------------------------------------------------------------------------- This is considered the initial stable version. All previous versions were mostly a stepping stone to this one. The changes are too enormous to list here, so please check out the rest of the documentation. arrow\_upward to top --- # Version Guarantees View Documentation For discord discord.ext.commands discord.ext.tasks search settings Version Guarantees[¶](https://discordpy-self.readthedocs.io/en/latest/version_guarantees.html#version-guarantees "Permalink to this headline") =============================================================================================================================================== The library follows a [semantic versioning principle](https://semver.org/) which means that the major version is updated every time there is an incompatible API change. However due to the lack of guarantees on the Discord side when it comes to breaking changes along with the fairly dynamic nature of Python it can be hard to discern what can be considered a breaking change and what isn’t. The first thing to keep in mind is that breaking changes only apply to **publicly documented functions and classes**. If it’s not listed in the documentation here then it is not part of the public API and is thus bound to change. This includes attributes that start with an underscore or functions without an underscore that are not documented. However, the Discord user API is in constant flux, so sometimes breaking changes may creep in. The guarantee is that patch releases will not introduce breaking changes, but minor releases may introduce minor ones. Major breaking changes will continue to be reserved for major releases. Note The examples below are non-exhaustive. Examples of Breaking Changes[¶](https://discordpy-self.readthedocs.io/en/latest/version_guarantees.html#examples-of-breaking-changes "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Changing the default parameter value to something else. * Renaming a function without an alias to an old function. * Adding or removing parameters to an event. Examples of Non-Breaking Changes[¶](https://discordpy-self.readthedocs.io/en/latest/version_guarantees.html#examples-of-non-breaking-changes "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Adding or removing private underscored attributes. * Adding an element into the `__slots__` of a data class. * Changing the behaviour of a function to fix a bug. * Changes in the documentation. * Modifying the internal HTTP handling. * Upgrading the dependencies to a new version, major or otherwise. arrow\_upward to top --- # Frequently Asked Questions View Documentation For discord discord.ext.commands discord.ext.tasks search settings Frequently Asked Questions[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#frequently-asked-questions "Permalink to this headline") ================================================================================================================================================ This is a list of Frequently Asked Questions regarding using `discord.py-self` and its extension modules. Feel free to suggest a new question or submit one via pull requests. Questions * [Coroutines](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#coroutines) * [What is a coroutine?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#what-is-a-coroutine) * [Where can I use `await`?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#where-can-i-use-await) * [What does “blocking” mean?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#what-does-blocking-mean) * [General](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#general) * [Where can I find usage examples?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#where-can-i-find-usage-examples) * [How do I set the “Playing” status?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-set-the-playing-status) * [How do I send a message to a specific channel?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-send-a-message-to-a-specific-channel) * [How do I send a DM?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-send-a-dm) * [How do I get the ID of a sent message?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-get-the-id-of-a-sent-message) * [How do I upload an image?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-upload-an-image) * [How can I add a reaction to a message?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-can-i-add-a-reaction-to-a-message) * [How do I pass a coroutine to the player’s “after” function?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-pass-a-coroutine-to-the-player-s-after-function) * [How do I run something in the background?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-run-something-in-the-background) * [How do I get a specific model?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-get-a-specific-model) * [How do I make a web request?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-make-a-web-request) * [How do I use a local image file for an embed image?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-use-a-local-image-file-for-an-embed-image) * [Is there an event for audit log entries being created?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#is-there-an-event-for-audit-log-entries-being-created) * [Commands Extension](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#commands-extension) * [Why does `on_message` make my commands stop working?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#why-does-on-message-make-my-commands-stop-working) * [Why do my arguments require quotes?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#why-do-my-arguments-require-quotes) * [How do I get the original `message`?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-get-the-original-message) * [How do I make a subcommand?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-make-a-subcommand) [Coroutines](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id1) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#coroutines "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Questions regarding coroutines and asyncio belong here. ### [What is a coroutine?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id2) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#what-is-a-coroutine "Permalink to this headline") A [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) is a function that must be invoked with `await` or `yield from`. When Python encounters an `await` it stops the function’s execution at that point and works on other things until it comes back to that point and finishes off its work. This allows for your program to be doing multiple things at the same time without using threads or complicated multiprocessing. **If you forget to await a coroutine then the coroutine will not run. Never forget to await a coroutine.** ### [Where can I use `await`?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id3) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#where-can-i-use-await "Permalink to this headline") You can only use `await` inside `async def` functions and nowhere else. ### [What does “blocking” mean?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id4) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#what-does-blocking-mean "Permalink to this headline") In asynchronous programming a blocking call is essentially all the parts of the function that are not `await`. Do not despair however, because not all forms of blocking are bad! Using blocking calls is inevitable, but you must work to make sure that you don’t excessively block functions. Remember, if you block for too long then your bot will freeze since it has not stopped the function’s execution at that point to do other things. If logging is enabled, this library will attempt to warn you that blocking is occurring with the message: `Heartbeat blocked for more than N seconds.` See [Setting Up Logging](https://discordpy-self.readthedocs.io/en/v2.0.1/logging.html#logging-setup) for details on enabling logging. A common source of blocking for too long is something like [`time.sleep()`](https://docs.python.org/3/library/time.html#time.sleep "(in Python v3.13)") . Don’t do that. Use [`asyncio.sleep()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.sleep "(in Python v3.13)") instead. Similar to this example: content\_copy \# bad time.sleep(10) \# good await asyncio.sleep(10) Another common source of blocking for too long is using HTTP requests with the famous module [Requests: HTTP for Humans™](https://requests.readthedocs.io/en/latest/ "(in Requests v2.32.3)") . While [Requests: HTTP for Humans™](https://requests.readthedocs.io/en/latest/ "(in Requests v2.32.3)") is an amazing module for non-asynchronous programming, it is not a good choice for [`asyncio`](https://docs.python.org/3/library/asyncio.html#module-asyncio "(in Python v3.13)") because certain requests can block the event loop too long. Instead, use the [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.11)") library which is installed on the side with this library. Consider the following example: content\_copy \# bad r \= requests.get('http://aws.random.cat/meow') if r.status\_code \== 200: js \= r.json() await channel.send(js\['file'\]) \# good async with aiohttp.ClientSession() as session: async with session.get('http://aws.random.cat/meow') as r: if r.status \== 200: js \= await r.json() await channel.send(js\['file'\]) [General](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id5) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#general "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- General questions regarding library usage belong here. ### [Where can I find usage examples?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id6) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#where-can-i-find-usage-examples "Permalink to this headline") Example code can be found in the [examples folder](https://github.com/dolfies/discord.py-self/tree/master/examples) in the repository. ### [How do I set the “Playing” status?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id7) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-set-the-playing-status "Permalink to this headline") The `activity` keyword argument may be passed in the [`Client`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client "discord.Client") constructor or [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.change_presence "discord.Client.change_presence") , given an [`Activity`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Activity "discord.Activity") object. The constructor may be used for static activities, while [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.change_presence "discord.Client.change_presence") may be used to update the activity at runtime. Warning It is highly discouraged to use [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.change_presence "discord.Client.change_presence") or API calls in [`on_ready()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_ready "discord.on_ready") as this event may be called many times while running, not just once. The status type (playing, listening, streaming, watching) can be set using the [`ActivityType`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.ActivityType "discord.ActivityType") enum. For memory optimisation purposes, some activities are offered in slimmed-down versions: * [`Game`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Game "discord.Game") * [`Streaming`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Streaming "discord.Streaming") Putting both of these pieces of info together, you get the following: content\_copy client \= discord.Client(activity\=discord.Game(name\='my game')) \# or, for watching: activity \= discord.Activity(name\='my activity', type\=discord.ActivityType.watching) client \= discord.Client(activity\=activity) ### [How do I send a message to a specific channel?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id8) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-send-a-message-to-a-specific-channel "Permalink to this headline") You must fetch the channel directly and then call the appropriate method. Example: content\_copy channel \= client.get\_channel(12324234183172) await channel.send('hello') ### [How do I send a DM?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id9) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-send-a-dm "Permalink to this headline") Get the [`User`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.User "discord.User") or [`Member`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Member "discord.Member") object and call [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") . For example: content\_copy user \= client.get\_user(381870129706958858) await user.send('👀') If you are responding to an event, such as [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_message "discord.on_message") , you already have the [`User`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.User "discord.User") object via [`Message.author`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Message.author "discord.Message.author") : content\_copy await message.author.send('👋') ### [How do I get the ID of a sent message?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id10) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-get-the-id-of-a-sent-message "Permalink to this headline") [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") returns the [`Message`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Message "discord.Message") that was sent. The ID of a message can be accessed via [`Message.id`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Message.id "discord.Message.id") : content\_copy message \= await channel.send('hmm…') message\_id \= message.id ### [How do I upload an image?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id11) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-upload-an-image "Permalink to this headline") To upload something to Discord you have to use the [`File`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.File "discord.File") object. A [`File`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.File "discord.File") accepts two parameters, the file-like object (or file path) and the filename to pass to Discord when uploading. If you want to upload an image it’s as simple as: content\_copy await channel.send(file\=discord.File('my\_file.png')) If you have a file-like object you can do as follows: content\_copy with open('my\_file.png', 'rb') as fp: await channel.send(file\=discord.File(fp, 'new\_filename.png')) To upload multiple files, you can use the `files` keyword argument instead of `file`: content\_copy my\_files \= \[\ discord.File('result.zip'),\ discord.File('teaser\_graph.png'),\ \] await channel.send(files\=my\_files) If you want to upload something from a URL, you will have to use an HTTP request using [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.11)") and then pass an [`io.BytesIO`](https://docs.python.org/3/library/io.html#io.BytesIO "(in Python v3.13)") instance to [`File`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.File "discord.File") like so: content\_copy import io import aiohttp async with aiohttp.ClientSession() as session: async with session.get(my\_url) as resp: if resp.status != 200: return await channel.send('Could not download file...') data \= io.BytesIO(await resp.read()) await channel.send(file\=discord.File(data, 'cool\_image.png')) ### [How can I add a reaction to a message?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id12) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-can-i-add-a-reaction-to-a-message "Permalink to this headline") You use the [`Message.add_reaction()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Message.add_reaction "discord.Message.add_reaction") method. If you want to use unicode emoji, you must pass a valid unicode code point in a string. In your code, you can write this in a few different ways: * `'👍'` * `'\U0001F44D'` * `'\N{THUMBS UP SIGN}'` Quick example: content\_copy emoji \= '\\N{THUMBS UP SIGN}' \# or '\\U0001f44d' or '👍' await message.add\_reaction(emoji) In case you want to use emoji that come from a message, you already get their code points in the content without needing to do anything special. You **cannot** send `':thumbsup:'` style shorthands. For custom emoji, you should pass an instance of [`Emoji`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Emoji "discord.Emoji") . You can also pass a `'<:name:id>'` string, but if you can use said emoji, you should be able to use [`Client.get_emoji()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.get_emoji "discord.Client.get_emoji") to get an emoji via ID or use [`utils.find()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.utils.find "discord.utils.find") / [`utils.get()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.utils.get "discord.utils.get") on [`Client.emojis`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.emojis "discord.Client.emojis") or [`Guild.emojis`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.emojis "discord.Guild.emojis") collections. The name and ID of a custom emoji can be found with the client by prefixing `:custom_emoji:` with a backslash. For example, sending the message `\:python3:` with the client will result in `<:python3:232720527448342530>`. Quick example: content\_copy \# if you have the ID already emoji \= client.get\_emoji(310177266011340803) await message.add\_reaction(emoji) \# no ID, do a lookup emoji \= discord.utils.get(guild.emojis, name\='LUL') if emoji: await message.add\_reaction(emoji) \# if you have the name and ID of a custom emoji: emoji \= '<:python3:232720527448342530>' await message.add\_reaction(emoji) ### [How do I pass a coroutine to the player’s “after” function?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id13) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-pass-a-coroutine-to-the-player-s-after-function "Permalink to this headline") The library’s music player launches on a separate thread, ergo it does not execute inside a coroutine. This does not mean that it is not possible to call a coroutine in the `after` parameter. To do so you must pass a callable that wraps up a couple of aspects. The first gotcha that you must be aware of is that calling a coroutine is not a thread-safe operation. Since we are technically in another thread, we must take caution in calling thread-safe operations so things do not bug out. Luckily for us, [`asyncio`](https://docs.python.org/3/library/asyncio.html#module-asyncio "(in Python v3.13)") comes with a [`asyncio.run_coroutine_threadsafe()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.run_coroutine_threadsafe "(in Python v3.13)") function that allows us to call a coroutine from another thread. However, this function returns a [`Future`](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future "(in Python v3.13)") and to actually call it we have to fetch its result. Putting all of this together we can do the following: content\_copy def my\_after(error): coro \= some\_channel.send('Song is done!') fut \= asyncio.run\_coroutine\_threadsafe(coro, client.loop) try: fut.result() except: \# an error happened sending the message pass voice.play(discord.FFmpegPCMAudio(url), after\=my\_after) ### [How do I run something in the background?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id14) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-run-something-in-the-background "Permalink to this headline") [Check the background\_task.py example.](https://github.com/dolfies/discord.py-self/blob/master/examples/background_task.py) ### [How do I get a specific model?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id15) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-get-a-specific-model "Permalink to this headline") There are multiple ways of doing this. If you have a specific model’s ID then you can use one of the following functions: * [`Client.get_channel()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.get_channel "discord.Client.get_channel") * [`Client.get_guild()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.get_guild "discord.Client.get_guild") * [`Client.get_user()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.get_user "discord.Client.get_user") * [`Client.get_emoji()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.get_emoji "discord.Client.get_emoji") * [`Guild.get_member()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.get_member "discord.Guild.get_member") * [`Guild.get_channel()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.get_channel "discord.Guild.get_channel") * [`Guild.get_role()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.get_role "discord.Guild.get_role") The following use an HTTP request: * [`abc.Messageable.fetch_message()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.abc.Messageable.fetch_message "discord.abc.Messageable.fetch_message") * [`Client.fetch_user()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.fetch_user "discord.Client.fetch_user") * [`Client.fetch_guilds()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.fetch_guilds "discord.Client.fetch_guilds") * [`Client.fetch_guild()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.fetch_guild "discord.Client.fetch_guild") * [`Guild.fetch_emoji()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.fetch_emoji "discord.Guild.fetch_emoji") * [`Guild.fetch_emojis()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.fetch_emojis "discord.Guild.fetch_emojis") * [`Guild.fetch_member()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.fetch_member "discord.Guild.fetch_member") If the functions above do not help you, then use of [`utils.find()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.utils.find "discord.utils.find") or [`utils.get()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.utils.get "discord.utils.get") would serve some use in finding specific models. Quick example: content\_copy \# find a guild by name guild \= discord.utils.get(client.guilds, name\='My Server') \# make sure to check if it's found if guild is not None: \# find a channel by name channel \= discord.utils.get(guild.text\_channels, name\='cool-channel') ### [How do I make a web request?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id16) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-make-a-web-request "Permalink to this headline") To make a request, you should use a non-blocking library. This library already uses and requires a 3rd party library for making requests, [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.11)") . Quick example: content\_copy async with aiohttp.ClientSession() as session: async with session.get('http://aws.random.cat/meow') as r: if r.status \== 200: js \= await r.json() See [aiohttp’s full documentation](http://aiohttp.readthedocs.io/en/stable/) for more information. ### [How do I use a local image file for an embed image?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id17) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-use-a-local-image-file-for-an-embed-image "Permalink to this headline") Discord special-cases uploading an image attachment and using it within an embed so that it will not display separately, but instead in the embed’s thumbnail, image, footer or author icon. To do so, upload the image normally with [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") , and set the embed’s image URL to `attachment://image.png`, where `image.png` is the filename of the image you will send. Quick example: content\_copy file \= discord.File("path/to/my/image.png", filename\="image.png") embed \= discord.Embed() embed.set\_image(url\="attachment://image.png") await channel.send(file\=file, embed\=embed) ### [Is there an event for audit log entries being created?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id18) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#is-there-an-event-for-audit-log-entries-being-created "Permalink to this headline") This event is now available in the library and Discord as of version 2.0. It can be found under [`on_audit_log_entry_create()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_audit_log_entry_create "discord.on_audit_log_entry_create") . [Commands Extension](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id19) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#commands-extension "Permalink to this headline") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Questions regarding `discord.ext.commands` belong here. ### [Why does `on_message` make my commands stop working?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id20) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#why-does-on-message-make-my-commands-stop-working "Permalink to this headline") Overriding the default provided `on_message` forbids any extra commands from running. To fix this, add a `bot.process_commands(message)` line at the end of your `on_message`. For example: content\_copy @bot.event async def on\_message(message): \# do some extra stuff here await bot.process\_commands(message) Alternatively, you can place your `on_message` logic into a **listener**. In this setup, you should not manually call `bot.process_commands()`. This also allows you to do multiple things asynchronously in response to a message. Example: content\_copy @bot.listen('on\_message') async def whatever\_you\_want\_to\_call\_it(message): \# do stuff here \# do not process commands here ### [Why do my arguments require quotes?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id21) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#why-do-my-arguments-require-quotes "Permalink to this headline") In a simple command defined as: content\_copy @bot.command() async def echo(ctx, message: str): await ctx.send(message) Calling it via `?echo a b c` will only fetch the first argument and disregard the rest. To fix this you should either call it via `?echo "a b c"` or change the signature to have “consume rest” behaviour. Example: content\_copy @bot.command() async def echo(ctx, \*, message: str): await ctx.send(message) This will allow you to use `?echo a b c` without needing the quotes. ### [How do I get the original `message`?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id22) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-get-the-original-message "Permalink to this headline") The [`Context`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") contains an attribute, [`message`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#discord.ext.commands.Context.message "discord.ext.commands.Context.message") to get the original message. Example: content\_copy @bot.command() async def length(ctx): await ctx.send(f'Your message is {len(ctx.message.content)} characters long.') ### [How do I make a subcommand?](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#id23) [¶](https://discordpy-self.readthedocs.io/en/v2.0.1/faq.html#how-do-i-make-a-subcommand "Permalink to this headline") Use the [`group()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#discord.ext.commands.group "discord.ext.commands.group") decorator. This will transform the callback into a [`Group`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") which will allow you to add commands into the group operating as “subcommands”. These groups can be arbitrarily nested as well. Example: content\_copy @bot.group() async def git(ctx): if ctx.invoked\_subcommand is None: await ctx.send('Invalid git command passed...') @git.command() async def push(ctx, remote: str, branch: str): await ctx.send(f'Pushing to {remote} {branch}') This could then be used as `?git push origin master`. arrow\_upward to top --- # Introduction View Documentation For discord discord.ext.commands discord.ext.tasks search settings Introduction[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/intro.html#introduction "Permalink to this headline") ====================================================================================================================== This is the documentation for discord.py-self, a library for Python to aid in creating bots running on user accounts that utilise the Discord API. Prerequisites[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/intro.html#prerequisites "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------ discord.py-self works with Python 3.8 or higher. Support for earlier versions of Python is not provided. Installing[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/intro.html#installing "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------ You can get the library directly from PyPI: content\_copy python3 \-m pip install \-U discord.py\-self If you are using Windows, then the following should be used instead: content\_copy py \-3 \-m pip install \-U discord.py\-self To get voice support, you should use `discord.py-self[voice]` instead of `discord.py`, e.g. content\_copy python3 \-m pip install \-U discord.py\-self\[voice\] On Linux environments, installing voice requires getting the following dependencies: * [libffi](https://github.com/libffi/libffi) * [libnacl](https://github.com/saltstack/libnacl) * [python3-dev](https://packages.debian.org/python3-dev) For a Debian-based system, the following command will get these dependencies: content\_copy $ apt install libffi-dev libnacl-dev python3-dev Remember to check your permissions! ### Virtual Environments[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/intro.html#virtual-environments "Permalink to this headline") Sometimes you want to keep libraries from polluting system installs or use a different version of libraries than the ones installed on the system. You might also not have permissions to install libraries system-wide. For this purpose, the standard library as of Python 3.3 comes with a concept called “Virtual Environment”s to help maintain these separate versions. A more in-depth tutorial is found on [Virtual Environments and Packages](https://docs.python.org/3/tutorial/venv.html "(in Python v3.13)") . However, for the quick and dirty: 1. Go to your project’s working directory: > content\_copy > > $ cd your-bot-source > $ python3 \-m venv bot-env 2. Activate the virtual environment: > content\_copy > > $ source bot-env/bin/activate > > On Windows you activate it with: > > content\_copy > > $ bot-env\\Scripts\\activate.bat 3. Use pip like usual: > content\_copy > > $ pip install \-U discord.py-self Congratulations. You now have a virtual environment all set up. Basic Concepts[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/intro.html#basic-concepts "Permalink to this headline") -------------------------------------------------------------------------------------------------------------------------- discord.py revolves around the concept of [events](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord-api-events) . An event is something you listen to and then respond to. For example, when a message happens, you will receive an event about it that you can respond to. A quick example to showcase how events work: content\_copy import discord class MyClient(discord.Client): async def on\_ready(self): print(f'Logged on as {self.user}!') async def on\_message(self, message): print(f'Message from {message.author}: {message.content}') client \= MyClient() client.run('token') arrow\_upward to top --- # Migrating to This Library View Documentation For discord discord.ext.commands discord.ext.tasks search settings Migrating to This Library[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/migrating_from_dpy.html#migrating-to-this-library "Permalink to this headline") ============================================================================================================================================================= This library is designed to be compatible with discord.py. However, the user and bot APIs are _not_ the same. Most things bots can do, users can (in some capacity) as well. The biggest difference is the amount of added things: users can do a lot more things than bots can. However, a number of things have been removed. For example: * `Intents`: While the gateway technically accepts intents for user accounts, they are—for the most part—useless and can break things. * `Shards`: Just like intents, users can utilize sharding but it is not very useful. * `discord.ui`: Users cannot utilize the bot UI kit. * `discord.app_commands`: Users cannot register application commands. However, even in features that are shared between user and bot accounts, there may be variance in functionality or simply different design choices that better reflect a user account implementation. An effort is made to minimize these differences and avoid migration pain, but it is not always the first priority. Guild Subscriptions[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/migrating_from_dpy.html#guild-subscriptions "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------- Guild subscriptions are a way for a client to limit the events it receives from a guild. For more information about guild subscriptions, see the [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/v2.0.1/guild_subscriptions.html) section. When compared to a bot account, the most noticeable differences they introduce are in relation to guild members and presence. ### Guild Members[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/migrating_from_dpy.html#guild-members "Permalink to this headline") The concept of privileged intents does not exist for user accounts, so guild member access is limited in different ways. By default, the library will subscribe to member updates for all guilds, meaning that events such as [`discord.on_member_join()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_member_join "discord.on_member_join") and [`discord.on_raw_member_remove()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_raw_member_remove "discord.on_raw_member_remove") will be dispatched for all guilds the user is in. However, events that require the member cache to be populated (such as [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_member_update "discord.on_member_update") ) are only dispatched for guilds that are chunked. A guild can only be chunked (have the local member cache populated) if the user has the [`manage_roles`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Permissions.manage_roles "discord.Permissions.manage_roles") , [`kick_members`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Permissions.kick_members "discord.Permissions.kick_members") , or [`ban_members`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Permissions.ban_members "discord.Permissions.ban_members") permissions. Additionally, guilds with less than 1,000 members may be chunked if there exists at least one channel that everyone can view. By default, the library will attempt to chunk all guilds that are chunkable. This can be disabled by setting the `chunk_guilds_at_startup` parameter to `False` when creating a [`Client`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client "discord.Client") . If a guild is not chunked, the only members that will be cached are members with an active voice state and, if the guild has less than 75,000 members, members that the user is friends, has an implicit relationship, or has an open DM with. The library offers two avenues to get the “entire” member list of a guild. * [`Guild.chunk()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.chunk "discord.Guild.chunk") : If chunking guilds at startup is disabled, you can use this method to chunk a guild manually. * [`Guild.fetch_members()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.fetch_members "discord.Guild.fetch_members") : If you have the permissions to request all guild members, you can use this method to fetch the entire member list. Else, this method scrapes the member sidebar (which can become very slow), only returning online members if the guild has more than 1,000 members. ### Presence[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/migrating_from_dpy.html#presence "Permalink to this headline") User accounts are always synced the overall presence of friends and implicit relationships, tracked in the library via the [`Relationship`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Relationship "discord.Relationship") class. Overall user presence updates will dispatch a [`discord.on_presence_update()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_presence_update "discord.on_presence_update") event with [`Relationship`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Relationship "discord.Relationship") instances. Additionally, for guilds with less than 75,000 members, they’re synced the per-guild presence of members that the user is friends, has an implicit relationship, or has an open DM with. Outside of these cases, you will not receive presence updates for any other users. To obtain the presence of an arbitrary user, you can use the [`Guild.query_members()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.query_members "discord.Guild.query_members") method. To stay informed of presence updates for a specific user, you can subscribe to them using the [`Guild.subscribe_to()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.subscribe_to "discord.Guild.subscribe_to") method. See the [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/v2.0.1/guild_subscriptions.html) section for more information. Note User updates (i.e. [`discord.on_user_update()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_user_update "discord.on_user_update") ) require either member updates (for at least one guild) or presence updates to be dispatched for the user as outlined above. AutoMod[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/migrating_from_dpy.html#automod "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------- The following Gateway events are not dispatched to user accounts: * `on_automod_rule_create` * `on_automod_rule_update` * `on_automod_rule_delete` * `on_automod_action` The first three can be replaced by listening to the [`discord.on_audit_log_entry_create()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_audit_log_entry_create "discord.on_audit_log_entry_create") event and checking the [`action`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.AuditLogEntry.action "discord.AuditLogEntry.action") attribute. The last one is partially replaceable by listening to the [`discord.on_message()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_message "discord.on_message") event and checking for AutoMod system messages, but this is not a perfect solution. arrow\_upward to top --- # Guild Subscriptions View Documentation For discord discord.ext.commands discord.ext.tasks search settings Guild Subscriptions[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/guild_subscriptions.html#guild-subscriptions "Permalink to this headline") ================================================================================================================================================== Guild subscriptions are a way for a client to limit the events it receives from a guild. While this is useful for a traditional client, it may not be of much use for a bot, so the default library behavior is to subscribe to as much as possible at startup. The client is automatically subscribed to all guilds with less than 75,000 members on connect. For guilds the client is not subscribed to, you will not receive non-stateful events (e.g. [`discord.on_message()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_message "discord.on_message") , [`discord.on_message_edit()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_message_edit "discord.on_message_edit") , [`discord.on_message_delete()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_message_delete "discord.on_message_delete") , etc.). Additionally, voice states and channel unreads are kept up to date passively, as the client does not receive events for these updates in real-time. For every guild, clients can opt to subscribe to additional features, such as typing events (i.e. [`discord.on_typing()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_typing "discord.on_typing") ), a full thread list cache, and member updates (i.e. [`discord.on_member_join()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_member_join "discord.on_member_join") , [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_member_update "discord.on_member_update") , and [`discord.on_member_remove()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_member_remove "discord.on_member_remove") ). Additionally, clients can subscribe to specific members and threads within a guild. When subscribed to specific members (or thread member lists), the client will receive member and presence updates for those members (i.e. [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_member_update "discord.on_member_update") and [`discord.on_presence_update()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_presence_update "discord.on_presence_update") ). Additionally, for guilds with less than 75,000 members, the client is automatically subscribed to all friends, implicit relationships, and members the user has open DMs with at startup. Irrespective of subscribed members, events for actions the client performs (e.g. changing a user’s nickname, kicking a user, banning a user, etc.) will always be received. While events like [`discord.on_raw_member_remove()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_raw_member_remove "discord.on_raw_member_remove") are always dispatched when received, events like [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_member_update "discord.on_member_update") are only dispatched if the member is present in the cache. Guild subscriptions are also used to subscribe to the member list of a specific channel in a guild, but this ability is not yet exposed in the library. Drawbacks[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/guild_subscriptions.html#drawbacks "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------ For library users, the biggest drawback to guild subscriptions is that there is no way to reliably get the entire member list of a guild. An additional drawback is that there is no way to subscribe to presence updates for all members in a guild. At most, you can subscribe to presence updates for specific members and thread member lists. Note that clients always receive presence updates for friends, implicit relationships, and users they have an open DM (and mutual server) with. Implementation[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/guild_subscriptions.html#implementation "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------------------------- If you would like to override the default behavior and manage guild subscriptions yourself, you can set the `guild_subscriptions` parameter to `False` when creating a [`Client`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client "discord.Client") . If you do this, you cannot use the `chunk_guilds_at_startup` parameter, as it is dependent on guild subscriptions. To subscribe to a guild (and manage features), see the [`Guild.subscribe()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.subscribe "discord.Guild.subscribe") method. To manage subscriptions to a guild’s members or threads, see the [`Guild.subscribe_to()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.subscribe_to "discord.Guild.subscribe_to") and [`Guild.unsubscribe_from()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Guild.unsubscribe_from "discord.Guild.unsubscribe_from") methods. Subscription requests are debounced before being sent to the Gateway, so changes may take up to half a second to take effect (this is an implementation detail that may be changed at any time). arrow\_upward to top --- # Quickstart View Documentation For discord discord.ext.commands discord.ext.tasks search settings Quickstart[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/quickstart.html#quickstart "Permalink to this headline") ======================================================================================================================= This page gives a brief introduction to the library. It assumes you have the library installed, if you don’t check the [Installing](https://discordpy-self.readthedocs.io/en/v2.0.1/intro.html#installing) portion. A Minimal Bot[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/quickstart.html#a-minimal-bot "Permalink to this headline") ----------------------------------------------------------------------------------------------------------------------------- Let’s make a bot that responds to a specific message and walk you through it. It looks something like this: content\_copy import discord client \= discord.Client() @client.event async def on\_ready(): print(f'We have logged in as {client.user}') @client.event async def on\_message(message): if message.author != client.user: return if message.content.startswith('$hello'): await message.channel.send('Hello!') client.run('your token here') Let’s name this file `example_bot.py`. Make sure not to name it `discord.py` as that’ll conflict with the library. There’s a lot going on here, so let’s walk you through it step by step. 1. The first line just imports the library, if this raises a [`ModuleNotFoundError`](https://docs.python.org/3/library/exceptions.html#ModuleNotFoundError "(in Python v3.13)") or [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError "(in Python v3.13)") then head on over to [Installing](https://discordpy-self.readthedocs.io/en/v2.0.1/intro.html#installing) section to properly install. 2. Next, we create an instance of a [`Client`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client "discord.Client") . This client is our connection to Discord. 3. We then use the [`Client.event()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.event "discord.Client.event") decorator to register an event. This library has many events. Since this library is asynchronous, we do things in a “callback” style manner. A callback is essentially a function that is called when something happens. In our case, the [`on_ready()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_ready "discord.on_ready") event is called when the bot has finished logging in and setting things up and the [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_message "discord.on_message") event is called when the bot has received a message. 4. Since the [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.on_message "discord.on_message") event triggers for _every_ message received, we have to make sure that we ignore messages from ourselves. We do this by checking if the [`Message.author`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Message.author "discord.Message.author") is the same as the [`Client.user`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.user "discord.Client.user") . 5. Afterwards, we check if the [`Message.content`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Message.content "discord.Message.content") starts with `'$hello'`. If it does, then we send a message in the channel it was used in with `'Hello!'`. This is a basic way of handling commands, which can be later automated with the [discord.ext.commands – Bot commands framework](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/index.html) framework. 6. Finally, we run the bot with our login token. If you need help getting your token, look in the [Authenticating](https://discordpy-self.readthedocs.io/en/v2.0.1/authenticating.html) section. Now that we’ve made a bot, we have to _run_ the bot. Luckily, this is simple since this is just a Python script, we can run it directly. On Windows: content\_copy $ py \-3 example\_bot.py On other systems: content\_copy $ python3 example\_bot.py Now you can try playing around with your basic bot. arrow\_upward to top --- # Setting Up Logging View Documentation For discord discord.ext.commands discord.ext.tasks search settings New in version 0.6.0. Setting Up Logging[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/logging.html#setting-up-logging "Permalink to this headline") ==================================================================================================================================== _discord.py-self_ logs errors and debug information via the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.13)") python module. In order to streamline this process, the library provides default configuration for the `discord` logger when using [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.run "discord.Client.run") . It is strongly recommended that the logging module is configured, as no errors or warnings will be output if it is not set up. The default logging configuration provided by the library will print to [`sys.stderr`](https://docs.python.org/3/library/sys.html#sys.stderr "(in Python v3.13)") using coloured output. You can configure it to send to a file instead by using one of the built-in [`logging.handlers`](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers "(in Python v3.13)") , such as [`logging.FileHandler`](https://docs.python.org/3/library/logging.handlers.html#logging.FileHandler "(in Python v3.13)") . This can be done by passing it through [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.run "discord.Client.run") : content\_copy import logging handler \= logging.FileHandler(filename\='discord.log', encoding\='utf-8', mode\='w') \# Assume client refers to a discord.Client subclass... client.run(token, log\_handler\=handler) You can also disable the library’s logging configuration completely by passing `None`: content\_copy client.run(token, log\_handler\=None) Likewise, configuring the log level to `logging.DEBUG` is also possible: content\_copy import logging handler \= logging.FileHandler(filename\='discord.log', encoding\='utf-8', mode\='w') \# Assume client refers to a discord.Client subclass... client.run(token, log\_handler\=handler, log\_level\=logging.DEBUG) This is recommended, especially at verbose levels such as `DEBUG`, as there are a lot of events logged and it would clog the stderr of your program. If you want the logging configuration the library provides to affect all loggers rather than just the `discord` logger, you can pass `root_logger=True` inside [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.run "discord.Client.run") : content\_copy client.run(token, log\_handler\=handler, root\_logger\=True) If you want to setup logging using the library provided configuration without using [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.run "discord.Client.run") , you can use [`discord.utils.setup_logging()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.utils.setup_logging "discord.utils.setup_logging") : content\_copy import discord discord.utils.setup\_logging() \# or, for example discord.utils.setup\_logging(level\=logging.INFO, root\=False) More advanced setups are possible with the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.13)") module. The example below configures a rotating file handler that outputs DEBUG output for everything the library outputs, except for HTTP requests: content\_copy import discord import logging import logging.handlers logger \= logging.getLogger('discord') logger.setLevel(logging.DEBUG) logging.getLogger('discord.http').setLevel(logging.INFO) handler \= logging.handlers.RotatingFileHandler( filename\='discord.log', encoding\='utf-8', maxBytes\=32 \* 1024 \* 1024, \# 32 MiB backupCount\=5, \# Rotate through 5 files ) dt\_fmt \= '%Y-%m-%d %H:%M:%S' formatter \= logging.Formatter('\[{asctime}\] \[{levelname:<8}\] {name}: {message}', dt\_fmt, style\='{') handler.setFormatter(formatter) logger.addHandler(handler) \# Assume client refers to a discord.Client subclass... \# Suppress the default configuration since we have our own client.run(token, log\_handler\=None) For more information, check the documentation and tutorial of the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.13)") module. Changed in version 2.0: The library now provides a default logging configuration. arrow\_upward to top --- # Authenticating View Documentation For discord discord.ext.commands discord.ext.tasks search settings Authenticating[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/authenticating.html#authenticating "Permalink to this headline") =================================================================================================================================== Tokens[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/authenticating.html#tokens "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------- Tokens are how we authenticate with Discord. User accounts use the same token system as bots, received after authenticating with the Discord API. They follow this format: | | | | | | --- | --- | --- | --- |Discord Token[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/authenticating.html#id2 "Permalink to this table") | | MjQ1NTU5MDg3NTI0MjE2ODMy | DulyxA | brcD2xRAqjACTuMcGPwy4TWVQdg | | --- | --- | --- | --- | | **Decode** | [`base64.b64decode()`](https://docs.python.org/3/library/base64.html#base64.b64decode "(in Python v3.13)") | [`base64.b64decode()`](https://docs.python.org/3/library/base64.html#base64.b64decode "(in Python v3.13)")
+ 1293840000 | N/A | | **Output** | User ID | Unix TS | HMAC | How do I obtain mine?[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/authenticating.html#how-do-i-obtain-mine "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------ The library does not yet support authenticating traditionally, so you will have to obtain your token manually. To obtain your token from the Discord client, the easiest way is pasting this into the developer console (CTRL+SHIFT+I): content\_copy (webpackChunkdiscord\_app.push(\[\[''\],{},e\=>{m\=\[\];for(let c in e.c)m.push(e.c\[c\])}\]),m).find(m \=> m?.exports?.default?.getToken).exports.default.getToken() Or, you can do it manually: 1. Open developer tools (CTRL+SHIFT+I). 2. Click the Network tab. 3. Click the XHR tab. 4. Select a request and click the Headers tab. 5. Copy-paste the value in the Authorization header. arrow\_upward to top --- # discord.ext.commands – Bot commands framework View Documentation For discord discord.ext.commands discord.ext.tasks search settings `discord.ext.commands` – Bot commands framework[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/index.html#discord-ext-commands-bot-commands-framework "Permalink to this headline") ===================================================================================================================================================================================================== `discord.py` offers a lower level aspect on interacting with Discord. Often times, the library is used for the creation of bots. However this task can be daunting and confusing to get correctly the first time. Many times there comes a repetition in creating a bot command framework that is extensible, flexible, and powerful. For this reason, `discord.py` comes with an extension library that handles this for you. * [Commands](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/commands.html) * [Parameters](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/commands.html#parameters) * [Invocation Context](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/commands.html#invocation-context) * [Converters](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/commands.html#converters) * [Parameter Metadata](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/commands.html#parameter-metadata) * [Error Handling](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/commands.html#error-handling) * [Checks](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/commands.html#checks) * [Cogs](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/cogs.html) * [Quick Example](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/cogs.html#quick-example) * [Cog Registration](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/cogs.html#cog-registration) * [Using Cogs](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/cogs.html#using-cogs) * [Special Methods](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/cogs.html#special-methods) * [Meta Options](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/cogs.html#meta-options) * [Inspection](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/cogs.html#inspection) * [Extensions](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/extensions.html) * [Primer](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/extensions.html#primer) * [Reloading](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/extensions.html#reloading) * [Cleaning Up](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/extensions.html#cleaning-up) * [API Reference](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html) * [Bots](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#bots) * [Prefix Helpers](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#prefix-helpers) * [Event Reference](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#event-reference) * [Commands](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#commands) * [Cogs](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#cogs) * [Help Commands](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#help-commands) * [Enums](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#enums) * [Checks](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#checks) * [Cooldown](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#cooldown) * [Context](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#context) * [Converters](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#converters) * [Defaults](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#defaults) * [Exceptions](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#exceptions) arrow\_upward to top --- # discord.ext.tasks – asyncio.Task helpers View Documentation For discord discord.ext.commands discord.ext.tasks search settings `discord.ext.tasks` – asyncio.Task helpers[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord-ext-tasks-asyncio-task-helpers "Permalink to this headline") ======================================================================================================================================================================================== New in version 1.1.0. One of the most common operations when making a bot is having a loop run in the background at a specified interval. This pattern is very common but has a lot of things you need to look out for: * How do I handle [`asyncio.CancelledError`](https://docs.python.org/3/library/asyncio-exceptions.html#asyncio.CancelledError "(in Python v3.13)") ? * What do I do if the internet goes out? * What is the maximum number of seconds I can sleep anyway? The goal of this discord.py extension is to abstract all these worries away from you. Recipes[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#recipes "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------- A simple background task in a [`Cog`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") : content\_copy from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self): self.index \= 0 self.printer.start() def cog\_unload(self): self.printer.cancel() @tasks.loop(seconds\=5.0) async def printer(self): print(self.index) self.index += 1 Adding an exception to handle during reconnect: content\_copy import asyncpg from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.data \= \[\] self.batch\_update.add\_exception\_type(asyncpg.PostgresConnectionError) self.batch\_update.start() def cog\_unload(self): self.batch\_update.cancel() @tasks.loop(minutes\=5.0) async def batch\_update(self): async with self.bot.pool.acquire() as con: \# batch update here... pass Looping a certain amount of times before exiting: content\_copy from discord.ext import tasks import discord @tasks.loop(seconds\=5.0, count\=5) async def slow\_count(): print(slow\_count.current\_loop) @slow\_count.after\_loop async def after\_slow\_count(): print('done!') class MyClient(discord.Client): async def setup\_hook(self): slow\_count.start() Waiting until the bot is ready before the loop starts: content\_copy from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.index \= 0 self.bot \= bot self.printer.start() def cog\_unload(self): self.printer.cancel() @tasks.loop(seconds\=5.0) async def printer(self): print(self.index) self.index += 1 @printer.before\_loop async def before\_printer(self): print('waiting...') await self.bot.wait\_until\_ready() Doing something during cancellation: content\_copy from discord.ext import tasks, commands import asyncio class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.\_batch \= \[\] self.lock \= asyncio.Lock() self.bulker.start() async def cog\_unload(self): self.bulker.cancel() async def do\_bulk(self): \# bulk insert data here ... @tasks.loop(seconds\=10.0) async def bulker(self): async with self.lock: await self.do\_bulk() @bulker.after\_loop async def on\_bulker\_cancel(self): if self.bulker.is\_being\_cancelled() and len(self.\_batch) != 0: \# if we're cancelled and we have some data left... \# let's insert it to our database await self.do\_bulk() Doing something at a specific time each day: content\_copy import datetime from discord.ext import commands, tasks utc \= datetime.timezone.utc \# If no tzinfo is given then UTC is assumed. time \= datetime.time(hour\=8, minute\=30, tzinfo\=utc) class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.my\_task.start() def cog\_unload(self): self.my\_task.cancel() @tasks.loop(time\=time) async def my\_task(self): print("My task is running!") Doing something at multiple specific times each day: content\_copy import datetime from discord.ext import commands, tasks utc \= datetime.timezone.utc \# If no tzinfo is given then UTC is assumed. times \= \[\ datetime.time(hour\=8, tzinfo\=utc),\ datetime.time(hour\=12, minute\=30, tzinfo\=utc),\ datetime.time(hour\=16, minute\=40, second\=30, tzinfo\=utc)\ \] class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.my\_task.start() def cog\_unload(self): self.my\_task.cancel() @tasks.loop(time\=times) async def my\_task(self): print("My task is running!") API Reference[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#api-reference "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------------------- _class_ discord.ext.tasks.Loop[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop "Permalink to this definition") Attributes * [current\_loop](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.current_loop) * [hours](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.hours) * [minutes](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.minutes) * [next\_iteration](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.next_iteration) * [seconds](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.seconds) * [time](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.time) Methods * async[\_\_call\_\_](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.__call__) * def[add\_exception\_type](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.add_exception_type) * @[after\_loop](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.after_loop) * @[before\_loop](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop) * def[cancel](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.cancel) * def[change\_interval](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.change_interval) * def[clear\_exception\_types](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types) * @[error](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.error) * def[failed](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.failed) * def[get\_task](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.get_task) * def[is\_being\_cancelled](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled) * def[is\_running](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.is_running) * def[remove\_exception\_type](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.remove_exception_type) * def[restart](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.restart) * def[start](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.start) * def[stop](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.stop) A background task helper that abstracts the loop and reconnection logic for you. The main interface to create this is through [`loop()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.loop "discord.ext.tasks.loop") . @after\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.after_loop "Permalink to this definition") A decorator that registers a coroutine to be called after the loop finishes running. The coroutine must take no arguments (except `self` in a class context). Note This coroutine is called even during cancellation. If it is desirable to tell apart whether something was cancelled or not, check to see whether [`is_being_cancelled()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled "discord.ext.tasks.Loop.is_being_cancelled") is `True` or not. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.13)") ) – The coroutine to register after the loop finishes. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.13)") – The function was not a coroutine. @before\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop "Permalink to this definition") A decorator that registers a coroutine to be called before the loop starts running. This is useful if you want to wait for some bot state before the loop starts, such as [`discord.Client.wait_until_ready()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.wait_until_ready "discord.Client.wait_until_ready") . The coroutine must take no arguments (except `self` in a class context). Changed in version 2.0: Calling [`stop()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.stop "discord.ext.tasks.Loop.stop") in this coroutine will stop the initial iteration from running. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.13)") ) – The coroutine to register before the loop runs. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.13)") – The function was not a coroutine. @error[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.error "Permalink to this definition") A decorator that registers a coroutine to be called if the task encounters an unhandled exception. The coroutine must take only one argument the exception raised (except `self` in a class context). By default this logs to the library logger however it could be overridden to have a different implementation. New in version 1.4. Changed in version 2.0: Instead of writing to `sys.stderr`, the library’s logger is used. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.13)") ) – The coroutine to register in the event of an unhandled exception. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.13)") – The function was not a coroutine. _property_ seconds[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.seconds "Permalink to this definition") Read-only value for the number of seconds between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")\ \] _property_ minutes[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.minutes "Permalink to this definition") Read-only value for the number of minutes between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")\ \] _property_ hours[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.hours "Permalink to this definition") Read-only value for the number of hours between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")\ \] _property_ time[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.time "Permalink to this definition") Read-only list for the exact times this loop runs at. `None` if relative times were passed instead. New in version 2.0. Type Optional\[List\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.13)")\ \]\] _property_ current\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.current_loop "Permalink to this definition") The current iteration of the loop. Type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") _property_ next\_iteration[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.next_iteration "Permalink to this definition") When the next iteration of the loop will occur. New in version 1.3. Type Optional\[[`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.13)")\ \] _await_ \_\_call\_\_(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.__call__ "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Calls the internal callback that the task holds. New in version 1.6. Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. start(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.start "Permalink to this definition") Starts the internal task in the event loop. Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. Raises [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.13)") – A task has already been launched and is running. Returns The task that has been created. Return type [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.13)") stop()[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.stop "Permalink to this definition") Gracefully stops the task from running. Unlike [`cancel()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "discord.ext.tasks.Loop.cancel") , this allows the task to finish its current iteration before gracefully exiting. Note If the internal function raises an error that can be handled before finishing then it will retry until it succeeds. If this is undesirable, either remove the error handling before stopping via [`clear_exception_types()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types "discord.ext.tasks.Loop.clear_exception_types") or use [`cancel()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "discord.ext.tasks.Loop.cancel") instead. Changed in version 2.0: Calling this method in [`before_loop()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop "discord.ext.tasks.Loop.before_loop") will stop the first iteration from running. New in version 1.2. cancel()[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "Permalink to this definition") Cancels the internal task, if it is running. restart(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.restart "Permalink to this definition") A convenience method to restart the internal task. Note Due to the way this function works, the task is not returned like [`start()`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.start "discord.ext.tasks.Loop.start") . Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. add\_exception\_type(_\*exceptions_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.add_exception_type "Permalink to this definition") Adds exception types to be handled during the reconnect logic. By default the exception types handled are those handled by [`discord.Client.connect()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.connect "discord.Client.connect") , which includes a lot of internet disconnection errors. This function is useful if you’re interacting with a 3rd party library that raises its own set of exceptions. Parameters **\*exceptions** (Type\[[`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.13)")\ \]) – An argument list of exception classes to handle. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.13)") – An exception passed is either not a class or not inherited from [`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.13)") . clear\_exception\_types()[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types "Permalink to this definition") Removes all exception types that are handled. Note This operation obviously cannot be undone! remove\_exception\_type(_\*exceptions_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.remove_exception_type "Permalink to this definition") Removes exception types from being handled during the reconnect logic. Parameters **\*exceptions** (Type\[[`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.13)")\ \]) – An argument list of exception classes to handle. Returns Whether all exceptions were successfully removed. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") get\_task()[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.get_task "Permalink to this definition") Optional\[[`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.13)")\ \]: Fetches the internal task or `None` if there isn’t one running. is\_being\_cancelled()[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled "Permalink to this definition") Whether the task is being cancelled. failed()[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.failed "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") : Whether the internal task has failed. New in version 1.2. is\_running()[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.is_running "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") : Check if the task is currently running. New in version 1.4. change\_interval(_\*_, _seconds\=0_, _minutes\=0_, _hours\=0_, _time\=..._)[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop.change_interval "Permalink to this definition") Changes the interval for the sleep time. New in version 1.2. Parameters * **seconds** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") ) – The number of seconds between every iteration. * **minutes** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") ) – The number of minutes between every iteration. * **hours** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") ) – The number of hours between every iteration. * **time** (Union\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.13)")\ , Sequence\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.13)")\ \]\]) – The exact times to run this loop at. Either a non-empty list or a single value of [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.13)") should be passed. This cannot be used in conjunction with the relative time parameters. New in version 2.0. Note Duplicate times will be ignored, and only run once. Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An invalid value was given. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.13)") – An invalid value for the `time` parameter was passed, or the `time` parameter was passed in conjunction with relative time parameters. @discord.ext.tasks.loop(_\*_, _seconds\=..._, _minutes\=..._, _hours\=..._, _time\=..._, _count\=None_, _reconnect\=True_, _name\=None_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.loop "Permalink to this definition") A decorator that schedules a task in the background for you with optional reconnect logic. The decorator returns a [`Loop`](https://discordpy-self.readthedocs.io/en/v2.0.1/ext/tasks/index.html#discord.ext.tasks.Loop "discord.ext.tasks.Loop") . Parameters * **seconds** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") ) – The number of seconds between every iteration. * **minutes** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") ) – The number of minutes between every iteration. * **hours** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") ) – The number of hours between every iteration. * **time** (Union\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.13)")\ , Sequence\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.13)")\ \]\]) – The exact times to run this loop at. Either a non-empty list or a single value of [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.13)") should be passed. Timezones are supported. If no timezone is given for the times, it is assumed to represent UTC time. This cannot be used in conjunction with the relative time parameters. Note Duplicate times will be ignored, and only run once. New in version 2.0. * **count** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")\ \]) – The number of loops to do, `None` if it should be an infinite loop. * **reconnect** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") ) – Whether to handle errors and restart the task using an exponential back-off algorithm similar to the one used in [`discord.Client.connect()`](https://discordpy-self.readthedocs.io/en/v2.0.1/api.html#discord.Client.connect "discord.Client.connect") . * **name** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")\ \]) – The name to assign to the internal task. By default it is assigned a name based off of the callable name such as `discord-ext-tasks: function_name`. New in version 2.1. Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – An invalid value was given. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.13)") – The function was not a coroutine, an invalid value for the `time` parameter was passed, or `time` parameter was passed in conjunction with relative time parameters. arrow\_upward to top --- # Search View Documentation For discord discord.ext.commands discord.ext.tasks search settings Search ====== Searching for multiple words only shows matches that contain all words. arrow\_upward to top --- # Migrating to This Library View Documentation For discord discord.ext.commands discord.ext.tasks search settings Migrating to This Library[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/migrating_from_dpy.html#migrating-to-this-library "Permalink to this headline") ============================================================================================================================================================= This library is designed to be compatible with discord.py. However, the user and bot APIs are _not_ the same. Most things bots can do, users can (in some capacity) as well. The biggest difference is the amount of added things: users can do a lot more things than bots can. However, a number of things have been removed. For example: * `Intents`: While the gateway technically accepts intents for user accounts, it can break things and is a giant waving red flag to Discord. * `Shards`: Again, technically accepted but useless. * `discord.ui`: Users cannot utilize the bot UI kit. * `discord.app_commands`: Users cannot register application commands. Additionally, existing payloads and headers have been changed to match the Discord client. Guild members[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/migrating_from_dpy.html#guild-members "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------- Since the concept of Intents (mostly) doesn’t exist for user accounts; you just get all events, right? Well, yes but actually no. For 80% of things, events are identical to bot events. However, other than the quite large amount of new events, not all events work the same. The biggest example of this are the events `on_member_add`, `on_member_update`/`on_user_update`, `on_member_remove`, and `on_presence_update`. (If you’re just looking for the implementation, skip to the bottom of this section.) ### Bots[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/migrating_from_dpy.html#bots "Permalink to this headline") For bots (with the member intent), it’s simple. They request all guild members with an OPCode 8 (chunk the guild), and receive respective `GUILD_MEMBER_*` events, that are then parsed by the library and dispatched to users. If the bot has the presence intent, it even gets an initial member cache in the `GUILD_CREATE` event and receives `PRESENCE_UPDATE`. ### Users[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/migrating_from_dpy.html#users "Permalink to this headline") Users, however, do not work like this. If you have one of kick members, ban members, or manage roles, you can request all guild members the same way bots do. The client uses this in various areas of guild settings. But, here’s the twist: users do not receive `GUILD_MEMBER_*` reliably. They receive them in certain circumstances (such as when subscribing to updates for specific users), but they’re usually rare and nothing to be relied on. If the Discord client ever needs member objects for specific users, it sends an OPCode 8 with the specific user IDs/names. This is why this is recommended if you want to fetch specific members (implemented as [`Guild.query_members()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.query_members "discord.Guild.query_members") in the library). However, the maximum amount of members you can get with this method is 100 per request. But, you may be thinking, how does the member sidebar work? Why can’t you just utilize that? This is where it gets complicated. First, let’s make sure we understand a few things: * The API doesn’t differentiate between offline and invisible members (for a good reason). * The concept of a member sidebar is not per-guild, it’s per-channel. This makes sense if you think about it, since the member sidebar only shows users that have access to a specific channel. Member lists have IDs that can be calculated from channel permission overwrites to find unique member lists. * If a server has >1,000 members, the member sidebar does **not** have offline members. The member sidebar uses OPCode 14 and the `GUILD_MEMBER_LIST_UPDATE` event. One more thing you need to understand, is that the member sidebar is lazily loaded. You usually subscribe to 100 member ranges, and can subscribe to 5 per-channel per-request (up to 5 channels a request). If the guild’s member count has never been above 75,000 members, you can subscribe to 400 member ranges instead. So, to subscribe to all available ranges, you need to spam the gateway quite a bit (especially for large guilds). Additionally, while you can subscribe to 5 channels/request, the channels need to have the same permissions, or you’ll be subscribing to two different lists (not ideal). Once you subscribe to a range, you’ll receive `GUILD_MEMBER_LIST_UPDATE` s for it whenever someone is added to it (i.e. someone joined the guild, changed their nickname so they moved in the member list alphabetically, came online, etc.), removed from it (i.e. someone left the guild, went offline, changed their nickname so they moved in the member sidebar alphabetically), or updated in it (i.e. someone got their roles changed, or changed their nickname but remained in the same position). These can be parsed and dispatched as `on_member_add`, `on_member_update`/`on_user_update`, `on_member_remove`, and `on_presence_update`. You may have already noticed a few problems with this: 1. You’ll get spammed with `member_add/remove` s whenever someone changes position in the member sidebar. 2. For guilds with >1,000 members, you don’t receive offline members. So, you won’t know if an offline member is kicked, or an invisible member joins/leaves. You also won’t know if someone came online or joined. Or, if someone went offline or left. #1 is mostly solveable with a bit of parsing, but #2 is a huge problem. If you have the permissions to request all guild members, you can combine that with member sidebar scraping and get a _decent_ local member cache. However, because of the nature of this (and the fact that you’ll have to request all guild membesr again every so often), accurate events are nearly impossible. Additionally, there are more caveats: 1. `GUILD_MEMBER_LIST_UPDATE` removes provide an index, not a user ID. The index starts at 0 from the top of the member sidebar and includes hoisted roles. 2. You get ratelimited pretty fast, so scraping can take minutes for extremely large guilds. 3. The scraping has to happen every time the bot starts. This not only slows things down, but _may_ make Discord suspicious. 4. Remember that member sidebars are per-channel? Well, that means you can only subscribe all members that can _see_ the channel(s) you’re subscribing too. #1 is again solveable with a bit of parsing. There’s not much you can do about #2 and #3. But, to solve #4, you _can_ subscribe to multiple channels (which has problems of its own and makes events virtually impossible). There are a few more pieces of the puzzle: * There is a `/guilds/:id/roles/:id/member-ids` endpoint that provides up to 100 member IDs for any role other than the default role. You can use [`Guild.query_members()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.query_members "discord.Guild.query_members") to fetch all these members in one go. * With OPCode 14, you can subscribe to certain member IDs and receive member/presence updates for them. There is no limit to the amount of IDs you can subscribe to (except for the gateway payload size limit). * Thread member sidebars do _not_ work the same. You just send an OPCode 14 with the thread IDs and receive a `THREAD_MEMBER_LIST_UPDATE` with all the members. The cache then stays updated with `GUILD_MEMBER_UPDATE` and `THREAD_MEMBERS_UPDATE` events. ### Implementation[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/migrating_from_dpy.html#implementation "Permalink to this headline") The library offers two avenues to get the “entire” member list of a guild. * [`Guild.chunk()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.chunk "discord.Guild.chunk") : If a guild has less than 1,000 members, and has at least one channel that everyone can view, you can use this method to fetch the entire member list by scraping the member sidebar. With this method, you also get events. * [`Guild.fetch_members()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.fetch_members "discord.Guild.fetch_members") : If you have the permissions to request all guild members, you can use this method to fetch the entire member list. Else, this method scrapes the member sidebar (which can become very slow), this only returns online members if the guild has more than 1,000 members. This method does not get events. arrow\_upward to top --- # Changelog View Documentation For discord discord.ext.commands discord.ext.tasks search settings Changelog[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/whats_new.html#changelog "Permalink to this headline") ==================================================================================================================== This page keeps a detailed human friendly rendering of what’s new and changed in specific versions. v2.0[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/whats_new.html#v2-0 "Permalink to this headline") ---------------------------------------------------------------------------------------------------------- This is considered the initial stable version. All previous versions were mostly a stepping stone to this one. The changes are too enormous to list here, so please check out the rest of the documentation. arrow\_upward to top --- # Version Guarantees View Documentation For discord discord.ext.commands discord.ext.tasks search settings Version Guarantees[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/version_guarantees.html#version-guarantees "Permalink to this headline") =============================================================================================================================================== The library follows a [semantic versioning principle](https://semver.org/) which means that the major version is updated every time there is an incompatible API change. However due to the lack of guarantees on the Discord side when it comes to breaking changes along with the fairly dynamic nature of Python it can be hard to discern what can be considered a breaking change and what isn’t. The first thing to keep in mind is that breaking changes only apply to **publicly documented functions and classes**. If it’s not listed in the documentation here then it is not part of the public API and is thus bound to change. This includes attributes that start with an underscore or functions without an underscore that are not documented. However, the Discord user API is in constant flux, so sometimes breaking changes may creep in. The guarantee is that patch releases will not introduce breaking changes, but minor releases may introduce minor ones. Major breaking changes will continue to be reserved for major releases. Note The examples below are non-exhaustive. Examples of Breaking Changes[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/version_guarantees.html#examples-of-breaking-changes "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Changing the default parameter value to something else. * Renaming a function without an alias to an old function. * Adding or removing parameters to an event. Examples of Non-Breaking Changes[¶](https://discordpy-self.readthedocs.io/en/v2.0.1/version_guarantees.html#examples-of-non-breaking-changes "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Adding or removing private underscored attributes. * Adding an element into the `__slots__` of a data class. * Changing the behaviour of a function to fix a bug. * Changes in the documentation. * Modifying the internal HTTP handling. * Upgrading the dependencies to a new version, major or otherwise. arrow\_upward to top --- # Frequently Asked Questions View Documentation For discord discord.ext.commands discord.ext.tasks search settings Frequently Asked Questions[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#frequently-asked-questions "Permalink to this headline") ================================================================================================================================================ This is a list of Frequently Asked Questions regarding using `discord.py-self` and its extension modules. Feel free to suggest a new question or submit one via pull requests. Questions * [Coroutines](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#coroutines) * [What is a coroutine?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#what-is-a-coroutine) * [Where can I use `await`?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#where-can-i-use-await) * [What does “blocking” mean?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#what-does-blocking-mean) * [General](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#general) * [Where can I find usage examples?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#where-can-i-find-usage-examples) * [How do I set the “Playing” status?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-set-the-playing-status) * [How do I send a message to a specific channel?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-send-a-message-to-a-specific-channel) * [How do I send a DM?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-send-a-dm) * [How do I get the ID of a sent message?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-get-the-id-of-a-sent-message) * [How do I upload an image?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-upload-an-image) * [How can I add a reaction to a message?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-can-i-add-a-reaction-to-a-message) * [How do I pass a coroutine to the player’s “after” function?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-pass-a-coroutine-to-the-player-s-after-function) * [How do I run something in the background?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-run-something-in-the-background) * [How do I get a specific model?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-get-a-specific-model) * [How do I make a web request?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-make-a-web-request) * [How do I use a local image file for an embed image?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-use-a-local-image-file-for-an-embed-image) * [Is there an event for audit log entries being created?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#is-there-an-event-for-audit-log-entries-being-created) * [Commands Extension](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#commands-extension) * [Why does `on_message` make my commands stop working?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#why-does-on-message-make-my-commands-stop-working) * [Why do my arguments require quotes?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#why-do-my-arguments-require-quotes) * [How do I get the original `message`?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-get-the-original-message) * [How do I make a subcommand?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-make-a-subcommand) [Coroutines](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id1) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#coroutines "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Questions regarding coroutines and asyncio belong here. ### [What is a coroutine?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id2) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#what-is-a-coroutine "Permalink to this headline") A [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) is a function that must be invoked with `await` or `yield from`. When Python encounters an `await` it stops the function’s execution at that point and works on other things until it comes back to that point and finishes off its work. This allows for your program to be doing multiple things at the same time without using threads or complicated multiprocessing. **If you forget to await a coroutine then the coroutine will not run. Never forget to await a coroutine.** ### [Where can I use `await`?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id3) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#where-can-i-use-await "Permalink to this headline") You can only use `await` inside `async def` functions and nowhere else. ### [What does “blocking” mean?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id4) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#what-does-blocking-mean "Permalink to this headline") In asynchronous programming a blocking call is essentially all the parts of the function that are not `await`. Do not despair however, because not all forms of blocking are bad! Using blocking calls is inevitable, but you must work to make sure that you don’t excessively block functions. Remember, if you block for too long then your bot will freeze since it has not stopped the function’s execution at that point to do other things. If logging is enabled, this library will attempt to warn you that blocking is occurring with the message: `Heartbeat blocked for more than N seconds.` See [Setting Up Logging](https://discordpy-self.readthedocs.io/en/v2.0.0/logging.html#logging-setup) for details on enabling logging. A common source of blocking for too long is something like [`time.sleep()`](https://docs.python.org/3/library/time.html#time.sleep "(in Python v3.11)") . Don’t do that. Use [`asyncio.sleep()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.sleep "(in Python v3.11)") instead. Similar to this example: content\_copy \# bad time.sleep(10) \# good await asyncio.sleep(10) Another common source of blocking for too long is using HTTP requests with the famous module [Requests: HTTP for Humans™](https://requests.readthedocs.io/en/latest/ "(in Requests v2.28.2)") . While [Requests: HTTP for Humans™](https://requests.readthedocs.io/en/latest/ "(in Requests v2.28.2)") is an amazing module for non-asynchronous programming, it is not a good choice for [`asyncio`](https://docs.python.org/3/library/asyncio.html#module-asyncio "(in Python v3.11)") because certain requests can block the event loop too long. Instead, use the [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.8)") library which is installed on the side with this library. Consider the following example: content\_copy \# bad r \= requests.get('http://aws.random.cat/meow') if r.status\_code \== 200: js \= r.json() await channel.send(js\['file'\]) \# good async with aiohttp.ClientSession() as session: async with session.get('http://aws.random.cat/meow') as r: if r.status \== 200: js \= await r.json() await channel.send(js\['file'\]) [General](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id5) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#general "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- General questions regarding library usage belong here. ### [Where can I find usage examples?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id6) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#where-can-i-find-usage-examples "Permalink to this headline") Example code can be found in the [examples folder](https://github.com/dolfies/discord.py-self/tree/master/examples) in the repository. ### [How do I set the “Playing” status?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id7) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-set-the-playing-status "Permalink to this headline") The `activity` keyword argument may be passed in the [`Client`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client "discord.Client") constructor or [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.change_presence "discord.Client.change_presence") , given an [`Activity`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Activity "discord.Activity") object. The constructor may be used for static activities, while [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.change_presence "discord.Client.change_presence") may be used to update the activity at runtime. Warning It is highly discouraged to use [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.change_presence "discord.Client.change_presence") or API calls in [`on_ready()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.on_ready "discord.on_ready") as this event may be called many times while running, not just once. The status type (playing, listening, streaming, watching) can be set using the [`ActivityType`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.ActivityType "discord.ActivityType") enum. For memory optimisation purposes, some activities are offered in slimmed-down versions: * [`Game`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Game "discord.Game") * [`Streaming`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Streaming "discord.Streaming") Putting both of these pieces of info together, you get the following: content\_copy client \= discord.Client(activity\=discord.Game(name\='my game')) \# or, for watching: activity \= discord.Activity(name\='my activity', type\=discord.ActivityType.watching) client \= discord.Client(activity\=activity) ### [How do I send a message to a specific channel?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id8) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-send-a-message-to-a-specific-channel "Permalink to this headline") You must fetch the channel directly and then call the appropriate method. Example: content\_copy channel \= client.get\_channel(12324234183172) await channel.send('hello') ### [How do I send a DM?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id9) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-send-a-dm "Permalink to this headline") Get the [`User`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.User "discord.User") or [`Member`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Member "discord.Member") object and call [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") . For example: content\_copy user \= client.get\_user(381870129706958858) await user.send('👀') If you are responding to an event, such as [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.on_message "discord.on_message") , you already have the [`User`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.User "discord.User") object via [`Message.author`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Message.author "discord.Message.author") : content\_copy await message.author.send('👋') ### [How do I get the ID of a sent message?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id10) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-get-the-id-of-a-sent-message "Permalink to this headline") [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") returns the [`Message`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Message "discord.Message") that was sent. The ID of a message can be accessed via [`Message.id`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Message.id "discord.Message.id") : content\_copy message \= await channel.send('hmm…') message\_id \= message.id ### [How do I upload an image?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id11) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-upload-an-image "Permalink to this headline") To upload something to Discord you have to use the [`File`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.File "discord.File") object. A [`File`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.File "discord.File") accepts two parameters, the file-like object (or file path) and the filename to pass to Discord when uploading. If you want to upload an image it’s as simple as: content\_copy await channel.send(file\=discord.File('my\_file.png')) If you have a file-like object you can do as follows: content\_copy with open('my\_file.png', 'rb') as fp: await channel.send(file\=discord.File(fp, 'new\_filename.png')) To upload multiple files, you can use the `files` keyword argument instead of `file`: content\_copy my\_files \= \[\ discord.File('result.zip'),\ discord.File('teaser\_graph.png'),\ \] await channel.send(files\=my\_files) If you want to upload something from a URL, you will have to use an HTTP request using [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.8)") and then pass an [`io.BytesIO`](https://docs.python.org/3/library/io.html#io.BytesIO "(in Python v3.11)") instance to [`File`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.File "discord.File") like so: content\_copy import io import aiohttp async with aiohttp.ClientSession() as session: async with session.get(my\_url) as resp: if resp.status != 200: return await channel.send('Could not download file...') data \= io.BytesIO(await resp.read()) await channel.send(file\=discord.File(data, 'cool\_image.png')) ### [How can I add a reaction to a message?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id12) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-can-i-add-a-reaction-to-a-message "Permalink to this headline") You use the [`Message.add_reaction()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Message.add_reaction "discord.Message.add_reaction") method. If you want to use unicode emoji, you must pass a valid unicode code point in a string. In your code, you can write this in a few different ways: * `'👍'` * `'\U0001F44D'` * `'\N{THUMBS UP SIGN}'` Quick example: content\_copy emoji \= '\\N{THUMBS UP SIGN}' \# or '\\U0001f44d' or '👍' await message.add\_reaction(emoji) In case you want to use emoji that come from a message, you already get their code points in the content without needing to do anything special. You **cannot** send `':thumbsup:'` style shorthands. For custom emoji, you should pass an instance of [`Emoji`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Emoji "discord.Emoji") . You can also pass a `'<:name:id>'` string, but if you can use said emoji, you should be able to use [`Client.get_emoji()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.get_emoji "discord.Client.get_emoji") to get an emoji via ID or use [`utils.find()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.utils.find "discord.utils.find") / [`utils.get()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.utils.get "discord.utils.get") on [`Client.emojis`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.emojis "discord.Client.emojis") or [`Guild.emojis`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.emojis "discord.Guild.emojis") collections. The name and ID of a custom emoji can be found with the client by prefixing `:custom_emoji:` with a backslash. For example, sending the message `\:python3:` with the client will result in `<:python3:232720527448342530>`. Quick example: content\_copy \# if you have the ID already emoji \= client.get\_emoji(310177266011340803) await message.add\_reaction(emoji) \# no ID, do a lookup emoji \= discord.utils.get(guild.emojis, name\='LUL') if emoji: await message.add\_reaction(emoji) \# if you have the name and ID of a custom emoji: emoji \= '<:python3:232720527448342530>' await message.add\_reaction(emoji) ### [How do I pass a coroutine to the player’s “after” function?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id13) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-pass-a-coroutine-to-the-player-s-after-function "Permalink to this headline") The library’s music player launches on a separate thread, ergo it does not execute inside a coroutine. This does not mean that it is not possible to call a coroutine in the `after` parameter. To do so you must pass a callable that wraps up a couple of aspects. The first gotcha that you must be aware of is that calling a coroutine is not a thread-safe operation. Since we are technically in another thread, we must take caution in calling thread-safe operations so things do not bug out. Luckily for us, [`asyncio`](https://docs.python.org/3/library/asyncio.html#module-asyncio "(in Python v3.11)") comes with a [`asyncio.run_coroutine_threadsafe()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.run_coroutine_threadsafe "(in Python v3.11)") function that allows us to call a coroutine from another thread. However, this function returns a [`Future`](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future "(in Python v3.11)") and to actually call it we have to fetch its result. Putting all of this together we can do the following: content\_copy def my\_after(error): coro \= some\_channel.send('Song is done!') fut \= asyncio.run\_coroutine\_threadsafe(coro, client.loop) try: fut.result() except: \# an error happened sending the message pass voice.play(discord.FFmpegPCMAudio(url), after\=my\_after) ### [How do I run something in the background?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id14) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-run-something-in-the-background "Permalink to this headline") [Check the background\_task.py example.](https://github.com/dolfies/discord.py-self/blob/master/examples/background_task.py) ### [How do I get a specific model?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id15) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-get-a-specific-model "Permalink to this headline") There are multiple ways of doing this. If you have a specific model’s ID then you can use one of the following functions: * [`Client.get_channel()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.get_channel "discord.Client.get_channel") * [`Client.get_guild()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.get_guild "discord.Client.get_guild") * [`Client.get_user()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.get_user "discord.Client.get_user") * [`Client.get_emoji()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.get_emoji "discord.Client.get_emoji") * [`Guild.get_member()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.get_member "discord.Guild.get_member") * [`Guild.get_channel()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.get_channel "discord.Guild.get_channel") * [`Guild.get_role()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.get_role "discord.Guild.get_role") The following use an HTTP request: * [`abc.Messageable.fetch_message()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.abc.Messageable.fetch_message "discord.abc.Messageable.fetch_message") * [`Client.fetch_user()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.fetch_user "discord.Client.fetch_user") * [`Client.fetch_guilds()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.fetch_guilds "discord.Client.fetch_guilds") * [`Client.fetch_guild()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.fetch_guild "discord.Client.fetch_guild") * [`Guild.fetch_emoji()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.fetch_emoji "discord.Guild.fetch_emoji") * [`Guild.fetch_emojis()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.fetch_emojis "discord.Guild.fetch_emojis") * [`Guild.fetch_member()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Guild.fetch_member "discord.Guild.fetch_member") If the functions above do not help you, then use of [`utils.find()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.utils.find "discord.utils.find") or [`utils.get()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.utils.get "discord.utils.get") would serve some use in finding specific models. Quick example: content\_copy \# find a guild by name guild \= discord.utils.get(client.guilds, name\='My Server') \# make sure to check if it's found if guild is not None: \# find a channel by name channel \= discord.utils.get(guild.text\_channels, name\='cool-channel') ### [How do I make a web request?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id16) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-make-a-web-request "Permalink to this headline") To make a request, you should use a non-blocking library. This library already uses and requires a 3rd party library for making requests, [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.8)") . Quick example: content\_copy async with aiohttp.ClientSession() as session: async with session.get('http://aws.random.cat/meow') as r: if r.status \== 200: js \= await r.json() See [aiohttp’s full documentation](http://aiohttp.readthedocs.io/en/stable/) for more information. ### [How do I use a local image file for an embed image?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id17) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-use-a-local-image-file-for-an-embed-image "Permalink to this headline") Discord special-cases uploading an image attachment and using it within an embed so that it will not display separately, but instead in the embed’s thumbnail, image, footer or author icon. To do so, upload the image normally with [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") , and set the embed’s image URL to `attachment://image.png`, where `image.png` is the filename of the image you will send. Quick example: content\_copy file \= discord.File("path/to/my/image.png", filename\="image.png") embed \= discord.Embed() embed.set\_image(url\="attachment://image.png") await channel.send(file\=file, embed\=embed) ### [Is there an event for audit log entries being created?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id18) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#is-there-an-event-for-audit-log-entries-being-created "Permalink to this headline") This event is now available in the library and Discord as of version 2.0. It can be found under [`on_audit_log_entry_create()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.on_audit_log_entry_create "discord.on_audit_log_entry_create") . [Commands Extension](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id19) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#commands-extension "Permalink to this headline") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Questions regarding `discord.ext.commands` belong here. ### [Why does `on_message` make my commands stop working?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id20) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#why-does-on-message-make-my-commands-stop-working "Permalink to this headline") Overriding the default provided `on_message` forbids any extra commands from running. To fix this, add a `bot.process_commands(message)` line at the end of your `on_message`. For example: content\_copy @bot.event async def on\_message(message): \# do some extra stuff here await bot.process\_commands(message) Alternatively, you can place your `on_message` logic into a **listener**. In this setup, you should not manually call `bot.process_commands()`. This also allows you to do multiple things asynchronously in response to a message. Example: content\_copy @bot.listen('on\_message') async def whatever\_you\_want\_to\_call\_it(message): \# do stuff here \# do not process commands here ### [Why do my arguments require quotes?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id21) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#why-do-my-arguments-require-quotes "Permalink to this headline") In a simple command defined as: content\_copy @bot.command() async def echo(ctx, message: str): await ctx.send(message) Calling it via `?echo a b c` will only fetch the first argument and disregard the rest. To fix this you should either call it via `?echo "a b c"` or change the signature to have “consume rest” behaviour. Example: content\_copy @bot.command() async def echo(ctx, \*, message: str): await ctx.send(message) This will allow you to use `?echo a b c` without needing the quotes. ### [How do I get the original `message`?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id22) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-get-the-original-message "Permalink to this headline") The [`Context`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") contains an attribute, [`message`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#discord.ext.commands.Context.message "discord.ext.commands.Context.message") to get the original message. Example: content\_copy @bot.command() async def length(ctx): await ctx.send(f'Your message is {len(ctx.message.content)} characters long.') ### [How do I make a subcommand?](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#id23) [¶](https://discordpy-self.readthedocs.io/en/v2.0.0/faq.html#how-do-i-make-a-subcommand "Permalink to this headline") Use the [`group()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#discord.ext.commands.group "discord.ext.commands.group") decorator. This will transform the callback into a [`Group`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") which will allow you to add commands into the group operating as “subcommands”. These groups can be arbitrarily nested as well. Example: content\_copy @bot.group() async def git(ctx): if ctx.invoked\_subcommand is None: await ctx.send('Invalid git command passed...') @git.command() async def push(ctx, remote: str, branch: str): await ctx.send(f'Pushing to {remote} {branch}') This could then be used as `?git push origin master`. arrow\_upward to top --- # Migrating to This Library View Documentation For discord discord.ext.commands discord.ext.tasks search settings Migrating to This Library[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/migrating_from_dpy.html#migrating-to-this-library "Permalink to this headline") ============================================================================================================================================================= This library is designed to be compatible with discord.py. However, the user and bot APIs are _not_ the same. Most things bots can do, users can (in some capacity) as well. The biggest difference is the amount of added things: users can do a lot more things than bots can. However, a number of things have been removed. For example: * `Intents`: While the gateway technically accepts intents for user accounts, they are—for the most part—useless and can break things. * `Shards`: Just like intents, users can utilize sharding but it is not very useful. * `discord.ui`: Users cannot utilize the bot UI kit. * `discord.app_commands`: Users cannot register application commands. However, even in features that are shared between user and bot accounts, there may be variance in functionality or simply different design choices that better reflect a user account implementation. An effort is made to minimize these differences and avoid migration pain, but it is not always the first priority. Guild Subscriptions[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/migrating_from_dpy.html#guild-subscriptions "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------- Guild subscriptions are a way for a client to limit the events it receives from a guild. For more information about guild subscriptions, see the [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/v2.1.0/guild_subscriptions.html) section. When compared to a bot account, the most noticeable differences they introduce are in relation to guild members and presence. ### Guild Members[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/migrating_from_dpy.html#guild-members "Permalink to this headline") The concept of privileged intents does not exist for user accounts, so guild member access is limited in different ways. By default, the library will subscribe to member updates for all guilds, meaning that events such as [`discord.on_member_join()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_member_join "discord.on_member_join") and [`discord.on_raw_member_remove()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_raw_member_remove "discord.on_raw_member_remove") will be dispatched for all guilds the user is in. However, events that require the member cache to be populated (such as [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_member_update "discord.on_member_update") ) are only dispatched for guilds that are chunked. A guild can only be chunked (have the local member cache populated) if the user has the [`manage_roles`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Permissions.manage_roles "discord.Permissions.manage_roles") , [`kick_members`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Permissions.kick_members "discord.Permissions.kick_members") , or [`ban_members`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Permissions.ban_members "discord.Permissions.ban_members") permissions. Additionally, guilds with less than 1,000 members may be chunked if there exists at least one channel that everyone can view. By default, the library will attempt to chunk all guilds that are chunkable. This can be disabled by setting the `chunk_guilds_at_startup` parameter to `False` when creating a [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") . If a guild is not chunked, the only members that will be cached are members with an active voice state and, if the guild has less than 75,000 members, members that the user is friends, has an implicit relationship, or has an open DM with. The library offers two avenues to get the “entire” member list of a guild. * [`Guild.chunk()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.chunk "discord.Guild.chunk") : If chunking guilds at startup is disabled, you can use this method to chunk a guild manually. * [`Guild.fetch_members()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.fetch_members "discord.Guild.fetch_members") : If you have the permissions to request all guild members, you can use this method to fetch the entire member list. Else, this method scrapes the member sidebar (which can become very slow), only returning online members if the guild has more than 1,000 members. ### Presence[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/migrating_from_dpy.html#presence "Permalink to this headline") User accounts are always synced the overall presence of friends and implicit relationships, tracked in the library via the [`Relationship`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Relationship "discord.Relationship") class. Overall user presence updates will dispatch a [`discord.on_presence_update()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_presence_update "discord.on_presence_update") event with [`Relationship`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Relationship "discord.Relationship") instances. Additionally, for guilds with less than 75,000 members, they’re synced the per-guild presence of members that the user is friends, has an implicit relationship, or has an open DM with. Outside of these cases, you will not receive presence updates for any other users. To obtain the presence of an arbitrary user, you can use the [`Guild.query_members()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.query_members "discord.Guild.query_members") method. To stay informed of presence updates for a specific user, you can subscribe to them using the [`Guild.subscribe_to()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.subscribe_to "discord.Guild.subscribe_to") method. See the [Guild Subscriptions](https://discordpy-self.readthedocs.io/en/v2.1.0/guild_subscriptions.html) section for more information. Note User updates (i.e. [`discord.on_user_update()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_user_update "discord.on_user_update") ) require either member updates (for at least one guild) or presence updates to be dispatched for the user as outlined above. AutoMod[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/migrating_from_dpy.html#automod "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------- The following Gateway events are not dispatched to user accounts: * `on_automod_rule_create` * `on_automod_rule_update` * `on_automod_rule_delete` * `on_automod_action` The first three can be replaced by listening to the [`discord.on_audit_log_entry_create()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_audit_log_entry_create "discord.on_audit_log_entry_create") event and checking the [`action`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AuditLogEntry.action "discord.AuditLogEntry.action") attribute. The last one is partially replaceable by listening to the [`discord.on_message()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_message "discord.on_message") event and checking for AutoMod system messages, but this is not a perfect solution. arrow\_upward to top --- # Frequently Asked Questions View Documentation For discord discord.ext.commands discord.ext.tasks search settings Frequently Asked Questions[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#frequently-asked-questions "Permalink to this headline") ================================================================================================================================================ This is a list of Frequently Asked Questions regarding using `discord.py-self` and its extension modules. Feel free to suggest a new question or submit one via pull requests. Questions * [Coroutines](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#coroutines) * [What is a coroutine?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#what-is-a-coroutine) * [Where can I use `await`?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#where-can-i-use-await) * [What does “blocking” mean?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#what-does-blocking-mean) * [General](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#general) * [Where can I find usage examples?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#where-can-i-find-usage-examples) * [How do I set the “Playing” status?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-set-the-playing-status) * [How do I send a message to a specific channel?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-send-a-message-to-a-specific-channel) * [How do I send a DM?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-send-a-dm) * [How do I get the ID of a sent message?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-get-the-id-of-a-sent-message) * [How do I upload an image?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-upload-an-image) * [How can I add a reaction to a message?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-can-i-add-a-reaction-to-a-message) * [How do I pass a coroutine to the player’s “after” function?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-pass-a-coroutine-to-the-player-s-after-function) * [How do I run something in the background?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-run-something-in-the-background) * [How do I get a specific model?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-get-a-specific-model) * [How do I make a web request?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-make-a-web-request) * [How do I use a local image file for an embed image?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-use-a-local-image-file-for-an-embed-image) * [Is there an event for audit log entries being created?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#is-there-an-event-for-audit-log-entries-being-created) * [Commands Extension](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#commands-extension) * [Why does `on_message` make my commands stop working?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#why-does-on-message-make-my-commands-stop-working) * [Why do my arguments require quotes?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#why-do-my-arguments-require-quotes) * [How do I get the original `message`?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-get-the-original-message) * [How do I make a subcommand?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-make-a-subcommand) [Coroutines](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id1) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#coroutines "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Questions regarding coroutines and asyncio belong here. ### [What is a coroutine?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id2) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#what-is-a-coroutine "Permalink to this headline") A [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) is a function that must be invoked with `await` or `yield from`. When Python encounters an `await` it stops the function’s execution at that point and works on other things until it comes back to that point and finishes off its work. This allows for your program to be doing multiple things at the same time without using threads or complicated multiprocessing. **If you forget to await a coroutine then the coroutine will not run. Never forget to await a coroutine.** ### [Where can I use `await`?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id3) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#where-can-i-use-await "Permalink to this headline") You can only use `await` inside `async def` functions and nowhere else. ### [What does “blocking” mean?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id4) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#what-does-blocking-mean "Permalink to this headline") In asynchronous programming a blocking call is essentially all the parts of the function that are not `await`. Do not despair however, because not all forms of blocking are bad! Using blocking calls is inevitable, but you must work to make sure that you don’t excessively block functions. Remember, if you block for too long then your bot will freeze since it has not stopped the function’s execution at that point to do other things. If logging is enabled, this library will attempt to warn you that blocking is occurring with the message: `Heartbeat blocked for more than N seconds.` See [Setting Up Logging](https://discordpy-self.readthedocs.io/en/v2.1.0/logging.html#logging-setup) for details on enabling logging. A common source of blocking for too long is something like [`time.sleep()`](https://docs.python.org/3/library/time.html#time.sleep "(in Python v3.14)") . Don’t do that. Use [`asyncio.sleep()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.sleep "(in Python v3.14)") instead. Similar to this example: content\_copy \# bad time.sleep(10) \# good await asyncio.sleep(10) Another common source of blocking for too long is using HTTP requests with the famous module [Requests: HTTP for Humans™](https://requests.readthedocs.io/en/latest/ "(in Requests v2.32.5)") . While [Requests: HTTP for Humans™](https://requests.readthedocs.io/en/latest/ "(in Requests v2.32.5)") is an amazing module for non-asynchronous programming, it is not a good choice for [`asyncio`](https://docs.python.org/3/library/asyncio.html#module-asyncio "(in Python v3.14)") because certain requests can block the event loop too long. Instead, use the [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.13)") library which is installed on the side with this library. Consider the following example: content\_copy \# bad r \= requests.get('http://aws.random.cat/meow') if r.status\_code \== 200: js \= r.json() await channel.send(js\['file'\]) \# good async with aiohttp.ClientSession() as session: async with session.get('http://aws.random.cat/meow') as r: if r.status \== 200: js \= await r.json() await channel.send(js\['file'\]) [General](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id5) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#general "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- General questions regarding library usage belong here. ### [Where can I find usage examples?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id6) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#where-can-i-find-usage-examples "Permalink to this headline") Example code can be found in the [examples folder](https://github.com/dolfies/discord.py-self/tree/master/examples) in the repository. ### [How do I set the “Playing” status?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id7) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-set-the-playing-status "Permalink to this headline") The `activity` keyword argument may be passed in the [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") constructor or [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.change_presence "discord.Client.change_presence") , given an [`Activity`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Activity "discord.Activity") object. The constructor may be used for static activities, while [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.change_presence "discord.Client.change_presence") may be used to update the activity at runtime. Warning It is highly discouraged to use [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.change_presence "discord.Client.change_presence") or API calls in [`on_ready()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_ready "discord.on_ready") as this event may be called many times while running, not just once. The status type (playing, listening, streaming, watching) can be set using the [`ActivityType`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ActivityType "discord.ActivityType") enum. For memory optimisation purposes, some activities are offered in slimmed-down versions: * [`Game`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Game "discord.Game") * [`Streaming`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Streaming "discord.Streaming") Putting both of these pieces of info together, you get the following: content\_copy client \= discord.Client(activity\=discord.Game(name\='my game')) \# or, for watching: activity \= discord.Activity(name\='my activity', type\=discord.ActivityType.watching) client \= discord.Client(activity\=activity) ### [How do I send a message to a specific channel?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id8) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-send-a-message-to-a-specific-channel "Permalink to this headline") You must fetch the channel directly and then call the appropriate method. Example: content\_copy channel \= client.get\_channel(12324234183172) await channel.send('hello') ### [How do I send a DM?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id9) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-send-a-dm "Permalink to this headline") Get the [`User`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.User "discord.User") or [`Member`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Member "discord.Member") object and call [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") . For example: content\_copy user \= client.get\_user(381870129706958858) await user.send('👀') If you are responding to an event, such as [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_message "discord.on_message") , you already have the [`User`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.User "discord.User") object via [`Message.author`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.author "discord.Message.author") : content\_copy await message.author.send('👋') ### [How do I get the ID of a sent message?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id10) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-get-the-id-of-a-sent-message "Permalink to this headline") [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") returns the [`Message`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message "discord.Message") that was sent. The ID of a message can be accessed via [`Message.id`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.id "discord.Message.id") : content\_copy message \= await channel.send('hmm…') message\_id \= message.id ### [How do I upload an image?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id11) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-upload-an-image "Permalink to this headline") To upload something to Discord you have to use the [`File`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.File "discord.File") object. A [`File`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.File "discord.File") accepts two parameters, the file-like object (or file path) and the filename to pass to Discord when uploading. If you want to upload an image it’s as simple as: content\_copy await channel.send(file\=discord.File('my\_file.png')) If you have a file-like object you can do as follows: content\_copy with open('my\_file.png', 'rb') as fp: await channel.send(file\=discord.File(fp, 'new\_filename.png')) To upload multiple files, you can use the `files` keyword argument instead of `file`: content\_copy my\_files \= \[\ discord.File('result.zip'),\ discord.File('teaser\_graph.png'),\ \] await channel.send(files\=my\_files) If you want to upload something from a URL, you will have to use an HTTP request using [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.13)") and then pass an [`io.BytesIO`](https://docs.python.org/3/library/io.html#io.BytesIO "(in Python v3.14)") instance to [`File`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.File "discord.File") like so: content\_copy import io import aiohttp async with aiohttp.ClientSession() as session: async with session.get(my\_url) as resp: if resp.status != 200: return await channel.send('Could not download file...') data \= io.BytesIO(await resp.read()) await channel.send(file\=discord.File(data, 'cool\_image.png')) ### [How can I add a reaction to a message?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id12) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-can-i-add-a-reaction-to-a-message "Permalink to this headline") You use the [`Message.add_reaction()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.add_reaction "discord.Message.add_reaction") method. If you want to use unicode emoji, you must pass a valid unicode code point in a string. In your code, you can write this in a few different ways: * `'👍'` * `'\U0001F44D'` * `'\N{THUMBS UP SIGN}'` Quick example: content\_copy emoji \= '\\N{THUMBS UP SIGN}' \# or '\\U0001f44d' or '👍' await message.add\_reaction(emoji) In case you want to use emoji that come from a message, you already get their code points in the content without needing to do anything special. You **cannot** send `':thumbsup:'` style shorthands. For custom emoji, you should pass an instance of [`Emoji`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Emoji "discord.Emoji") . You can also pass a `'<:name:id>'` string, but if you can use said emoji, you should be able to use [`Client.get_emoji()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.get_emoji "discord.Client.get_emoji") to get an emoji via ID or use [`utils.find()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.utils.find "discord.utils.find") / [`utils.get()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.utils.get "discord.utils.get") on [`Client.emojis`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.emojis "discord.Client.emojis") or [`Guild.emojis`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.emojis "discord.Guild.emojis") collections. The name and ID of a custom emoji can be found with the client by prefixing `:custom_emoji:` with a backslash. For example, sending the message `\:python3:` with the client will result in `<:python3:232720527448342530>`. Quick example: content\_copy \# if you have the ID already emoji \= client.get\_emoji(310177266011340803) await message.add\_reaction(emoji) \# no ID, do a lookup emoji \= discord.utils.get(guild.emojis, name\='LUL') if emoji: await message.add\_reaction(emoji) \# if you have the name and ID of a custom emoji: emoji \= '<:python3:232720527448342530>' await message.add\_reaction(emoji) ### [How do I pass a coroutine to the player’s “after” function?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id13) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-pass-a-coroutine-to-the-player-s-after-function "Permalink to this headline") The library’s music player launches on a separate thread, ergo it does not execute inside a coroutine. This does not mean that it is not possible to call a coroutine in the `after` parameter. To do so you must pass a callable that wraps up a couple of aspects. The first gotcha that you must be aware of is that calling a coroutine is not a thread-safe operation. Since we are technically in another thread, we must take caution in calling thread-safe operations so things do not bug out. Luckily for us, [`asyncio`](https://docs.python.org/3/library/asyncio.html#module-asyncio "(in Python v3.14)") comes with a [`asyncio.run_coroutine_threadsafe()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.run_coroutine_threadsafe "(in Python v3.14)") function that allows us to call a coroutine from another thread. However, this function returns a [`Future`](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future "(in Python v3.14)") and to actually call it we have to fetch its result. Putting all of this together we can do the following: content\_copy def my\_after(error): coro \= some\_channel.send('Song is done!') fut \= asyncio.run\_coroutine\_threadsafe(coro, client.loop) try: fut.result() except: \# an error happened sending the message pass voice.play(discord.FFmpegPCMAudio(url), after\=my\_after) ### [How do I run something in the background?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id14) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-run-something-in-the-background "Permalink to this headline") [Check the background\_task.py example.](https://github.com/dolfies/discord.py-self/blob/master/examples/background_task.py) ### [How do I get a specific model?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id15) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-get-a-specific-model "Permalink to this headline") There are multiple ways of doing this. If you have a specific model’s ID then you can use one of the following functions: * [`Client.get_channel()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.get_channel "discord.Client.get_channel") * [`Client.get_guild()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.get_guild "discord.Client.get_guild") * [`Client.get_user()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.get_user "discord.Client.get_user") * [`Client.get_emoji()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.get_emoji "discord.Client.get_emoji") * [`Guild.get_member()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.get_member "discord.Guild.get_member") * [`Guild.get_channel()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.get_channel "discord.Guild.get_channel") * [`Guild.get_role()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.get_role "discord.Guild.get_role") The following use an HTTP request: * [`abc.Messageable.fetch_message()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.fetch_message "discord.abc.Messageable.fetch_message") * [`Client.fetch_user()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_user "discord.Client.fetch_user") * [`Client.fetch_guilds()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_guilds "discord.Client.fetch_guilds") * [`Client.fetch_guild()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_guild "discord.Client.fetch_guild") * [`Guild.fetch_emoji()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.fetch_emoji "discord.Guild.fetch_emoji") * [`Guild.fetch_emojis()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.fetch_emojis "discord.Guild.fetch_emojis") * [`Guild.fetch_member()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.fetch_member "discord.Guild.fetch_member") If the functions above do not help you, then use of [`utils.find()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.utils.find "discord.utils.find") or [`utils.get()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.utils.get "discord.utils.get") would serve some use in finding specific models. Quick example: content\_copy \# find a guild by name guild \= discord.utils.get(client.guilds, name\='My Server') \# make sure to check if it's found if guild is not None: \# find a channel by name channel \= discord.utils.get(guild.text\_channels, name\='cool-channel') ### [How do I make a web request?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id16) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-make-a-web-request "Permalink to this headline") To make a request, you should use a non-blocking library. This library already uses and requires a 3rd party library for making requests, [aiohttp](https://docs.aiohttp.org/en/stable/index.html "(in aiohttp v3.13)") . Quick example: content\_copy async with aiohttp.ClientSession() as session: async with session.get('http://aws.random.cat/meow') as r: if r.status \== 200: js \= await r.json() See [aiohttp’s full documentation](http://aiohttp.readthedocs.io/en/stable/) for more information. ### [How do I use a local image file for an embed image?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id17) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-use-a-local-image-file-for-an-embed-image "Permalink to this headline") Discord special-cases uploading an image attachment and using it within an embed so that it will not display separately, but instead in the embed’s thumbnail, image, footer or author icon. To do so, upload the image normally with [`abc.Messageable.send()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.send "discord.abc.Messageable.send") , and set the embed’s image URL to `attachment://image.png`, where `image.png` is the filename of the image you will send. Quick example: content\_copy file \= discord.File("path/to/my/image.png", filename\="image.png") embed \= discord.Embed() embed.set\_image(url\="attachment://image.png") await channel.send(file\=file, embed\=embed) ### [Is there an event for audit log entries being created?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id18) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#is-there-an-event-for-audit-log-entries-being-created "Permalink to this headline") This event is now available in the library and Discord as of version 2.0. It can be found under [`on_audit_log_entry_create()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_audit_log_entry_create "discord.on_audit_log_entry_create") . [Commands Extension](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id19) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#commands-extension "Permalink to this headline") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Questions regarding `discord.ext.commands` belong here. ### [Why does `on_message` make my commands stop working?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id20) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#why-does-on-message-make-my-commands-stop-working "Permalink to this headline") Overriding the default provided `on_message` forbids any extra commands from running. To fix this, add a `bot.process_commands(message)` line at the end of your `on_message`. For example: content\_copy @bot.event async def on\_message(message): \# do some extra stuff here await bot.process\_commands(message) Alternatively, you can place your `on_message` logic into a **listener**. In this setup, you should not manually call `bot.process_commands()`. This also allows you to do multiple things asynchronously in response to a message. Example: content\_copy @bot.listen('on\_message') async def whatever\_you\_want\_to\_call\_it(message): \# do stuff here \# do not process commands here ### [Why do my arguments require quotes?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id21) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#why-do-my-arguments-require-quotes "Permalink to this headline") In a simple command defined as: content\_copy @bot.command() async def echo(ctx, message: str): await ctx.send(message) Calling it via `?echo a b c` will only fetch the first argument and disregard the rest. To fix this you should either call it via `?echo "a b c"` or change the signature to have “consume rest” behaviour. Example: content\_copy @bot.command() async def echo(ctx, \*, message: str): await ctx.send(message) This will allow you to use `?echo a b c` without needing the quotes. ### [How do I get the original `message`?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id22) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-get-the-original-message "Permalink to this headline") The [`Context`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") contains an attribute, [`message`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Context.message "discord.ext.commands.Context.message") to get the original message. Example: content\_copy @bot.command() async def length(ctx): await ctx.send(f'Your message is {len(ctx.message.content)} characters long.') ### [How do I make a subcommand?](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#id23) [¶](https://discordpy-self.readthedocs.io/en/v2.1.0/faq.html#how-do-i-make-a-subcommand "Permalink to this headline") Use the [`group()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.group "discord.ext.commands.group") decorator. This will transform the callback into a [`Group`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") which will allow you to add commands into the group operating as “subcommands”. These groups can be arbitrarily nested as well. Example: content\_copy @bot.group() async def git(ctx): if ctx.invoked\_subcommand is None: await ctx.send('Invalid git command passed...') @git.command() async def push(ctx, remote: str, branch: str): await ctx.send(f'Pushing to {remote} {branch}') This could then be used as `?git push origin master`. arrow\_upward to top --- # Introduction View Documentation For discord discord.ext.commands discord.ext.tasks search settings Introduction[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/intro.html#introduction "Permalink to this headline") ====================================================================================================================== This is the documentation for discord.py-self, a library for Python to aid in creating bots running on user accounts that utilise the Discord API. Prerequisites[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/intro.html#prerequisites "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------ discord.py-self works with Python 3.10 or higher. Support for earlier versions of Python is not provided. Installing[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/intro.html#installing "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------ You can get the library directly from PyPI: content\_copy python3 \-m pip install \-U discord.py\-self If you are using Windows, then the following should be used instead: content\_copy py \-3 \-m pip install \-U discord.py\-self To get voice support, you should use `discord.py-self[voice]` instead of `discord.py`, e.g. content\_copy python3 \-m pip install \-U discord.py\-self\[voice\] On Linux environments, installing voice requires getting the following dependencies: * [libffi](https://github.com/libffi/libffi) * [libnacl](https://github.com/saltstack/libnacl) * [python3-dev](https://packages.debian.org/python3-dev) For a Debian-based system, the following command will get these dependencies: content\_copy $ apt install libffi-dev libnacl-dev python3-dev Remember to check your permissions! ### Virtual Environments[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/intro.html#virtual-environments "Permalink to this headline") Sometimes you want to keep libraries from polluting system installs or use a different version of libraries than the ones installed on the system. You might also not have permissions to install libraries system-wide. For this purpose, the standard library as of Python 3.3 comes with a concept called “Virtual Environment”s to help maintain these separate versions. A more in-depth tutorial is found on [Virtual Environments and Packages](https://docs.python.org/3/tutorial/venv.html "(in Python v3.14)") . However, for the quick and dirty: 1. Go to your project’s working directory: > content\_copy > > $ cd your-bot-source > $ python3 \-m venv bot-env 2. Activate the virtual environment: > content\_copy > > $ source bot-env/bin/activate > > On Windows you activate it with: > > content\_copy > > $ bot-env\\Scripts\\activate.bat 3. Use pip like usual: > content\_copy > > $ pip install \-U discord.py-self Congratulations. You now have a virtual environment all set up. Basic Concepts[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/intro.html#basic-concepts "Permalink to this headline") -------------------------------------------------------------------------------------------------------------------------- discord.py revolves around the concept of [events](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord-api-events) . An event is something you listen to and then respond to. For example, when a message happens, you will receive an event about it that you can respond to. A quick example to showcase how events work: content\_copy import discord class MyClient(discord.Client): async def on\_ready(self): print(f'Logged on as {self.user}!') async def on\_message(self, message): print(f'Message from {message.author}: {message.content}') client \= MyClient() client.run('token') arrow\_upward to top --- # Quickstart View Documentation For discord discord.ext.commands discord.ext.tasks search settings Quickstart[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/quickstart.html#quickstart "Permalink to this headline") ======================================================================================================================= This page gives a brief introduction to the library. It assumes you have the library installed, if you don’t check the [Installing](https://discordpy-self.readthedocs.io/en/v2.1.0/intro.html#installing) portion. A Minimal Bot[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/quickstart.html#a-minimal-bot "Permalink to this headline") ----------------------------------------------------------------------------------------------------------------------------- Let’s make a bot that responds to a specific message and walk you through it. It looks something like this: content\_copy import discord client \= discord.Client() @client.event async def on\_ready(): print(f'We have logged in as {client.user}') @client.event async def on\_message(message): if message.author != client.user: return if message.content.startswith('$hello'): await message.channel.send('Hello!') client.run('your token here') Let’s name this file `example_bot.py`. Make sure not to name it `discord.py` as that’ll conflict with the library. There’s a lot going on here, so let’s walk you through it step by step. 1. The first line just imports the library, if this raises a [`ModuleNotFoundError`](https://docs.python.org/3/library/exceptions.html#ModuleNotFoundError "(in Python v3.14)") or [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError "(in Python v3.14)") then head on over to [Installing](https://discordpy-self.readthedocs.io/en/v2.1.0/intro.html#installing) section to properly install. 2. Next, we create an instance of a [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") . This client is our connection to Discord. 3. We then use the [`Client.event()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.event "discord.Client.event") decorator to register an event. This library has many events. Since this library is asynchronous, we do things in a “callback” style manner. A callback is essentially a function that is called when something happens. In our case, the [`on_ready()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_ready "discord.on_ready") event is called when the bot has finished logging in and setting things up and the [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_message "discord.on_message") event is called when the bot has received a message. 4. Since the [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_message "discord.on_message") event triggers for _every_ message received, we have to make sure that we ignore messages from ourselves. We do this by checking if the [`Message.author`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.author "discord.Message.author") is the same as the [`Client.user`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.user "discord.Client.user") . 5. Afterwards, we check if the [`Message.content`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.content "discord.Message.content") starts with `'$hello'`. If it does, then we send a message in the channel it was used in with `'Hello!'`. This is a basic way of handling commands, which can be later automated with the [discord.ext.commands – Bot commands framework](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html) framework. 6. Finally, we run the bot with our login token. If you need help getting your token, look in the [Authenticating](https://discordpy-self.readthedocs.io/en/v2.1.0/authenticating.html) section. Now that we’ve made a bot, we have to _run_ the bot. Luckily, this is simple since this is just a Python script, we can run it directly. On Windows: content\_copy $ py \-3 example\_bot.py On other systems: content\_copy $ python3 example\_bot.py Now you can try playing around with your basic bot. arrow\_upward to top --- # Guild Subscriptions View Documentation For discord discord.ext.commands discord.ext.tasks search settings Guild Subscriptions[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/guild_subscriptions.html#guild-subscriptions "Permalink to this headline") ================================================================================================================================================== Guild subscriptions are a way for a client to limit the events it receives from a guild. While this is useful for a traditional client, it may not be of much use for a bot, so the default library behavior is to subscribe to as much as possible at startup. The client is automatically subscribed to all guilds with less than 75,000 members on connect. For guilds the client is not subscribed to, you will not receive non-stateful events (e.g. [`discord.on_message()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_message "discord.on_message") , [`discord.on_message_edit()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_message_edit "discord.on_message_edit") , [`discord.on_message_delete()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_message_delete "discord.on_message_delete") , etc.). Additionally, voice states and channel unreads are kept up to date passively, as the client does not receive events for these updates in real-time. For every guild, clients can opt to subscribe to additional features, such as typing events (i.e. [`discord.on_typing()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_typing "discord.on_typing") ), a full thread list cache, and member updates (i.e. [`discord.on_member_join()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_member_join "discord.on_member_join") , [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_member_update "discord.on_member_update") , and [`discord.on_member_remove()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_member_remove "discord.on_member_remove") ). Additionally, clients can subscribe to specific members and threads within a guild. When subscribed to specific members (or thread member lists), the client will receive member and presence updates for those members (i.e. [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_member_update "discord.on_member_update") and [`discord.on_presence_update()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_presence_update "discord.on_presence_update") ). Additionally, for guilds with less than 75,000 members, the client is automatically subscribed to all friends, implicit relationships, and members the user has open DMs with at startup. Irrespective of subscribed members, events for actions the client performs (e.g. changing a user’s nickname, kicking a user, banning a user, etc.) will always be received. While events like [`discord.on_raw_member_remove()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_raw_member_remove "discord.on_raw_member_remove") are always dispatched when received, events like [`discord.on_member_update()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_member_update "discord.on_member_update") are only dispatched if the member is present in the cache. Guild subscriptions are also used to subscribe to the member list of a specific channel in a guild, but this ability is not yet exposed in the library. Drawbacks[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/guild_subscriptions.html#drawbacks "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------ For library users, the biggest drawback to guild subscriptions is that there is no way to reliably get the entire member list of a guild. An additional drawback is that there is no way to subscribe to presence updates for all members in a guild. At most, you can subscribe to presence updates for specific members and thread member lists. Note that clients always receive presence updates for friends, implicit relationships, and users they have an open DM (and mutual server) with. Implementation[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/guild_subscriptions.html#implementation "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------------------------- If you would like to override the default behavior and manage guild subscriptions yourself, you can set the `guild_subscriptions` parameter to `False` when creating a [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") . If you do this, you cannot use the `chunk_guilds_at_startup` parameter, as it is dependent on guild subscriptions. To subscribe to a guild (and manage features), see the [`Guild.subscribe()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.subscribe "discord.Guild.subscribe") method. To manage subscriptions to a guild’s members or threads, see the [`Guild.subscribe_to()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.subscribe_to "discord.Guild.subscribe_to") and [`Guild.unsubscribe_from()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.unsubscribe_from "discord.Guild.unsubscribe_from") methods. Subscription requests are debounced before being sent to the Gateway, so changes may take up to half a second to take effect (this is an implementation detail that may be changed at any time). arrow\_upward to top --- # Setting Up Logging View Documentation For discord discord.ext.commands discord.ext.tasks search settings New in version 0.6.0. Setting Up Logging[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/logging.html#setting-up-logging "Permalink to this headline") ==================================================================================================================================== _discord.py-self_ logs errors and debug information via the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.14)") python module. In order to streamline this process, the library provides default configuration for the `discord` logger when using [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.run "discord.Client.run") . It is strongly recommended that the logging module is configured, as no errors or warnings will be output if it is not set up. The default logging configuration provided by the library will print to [`sys.stderr`](https://docs.python.org/3/library/sys.html#sys.stderr "(in Python v3.14)") using coloured output. You can configure it to send to a file instead by using one of the built-in [`logging.handlers`](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers "(in Python v3.14)") , such as [`logging.FileHandler`](https://docs.python.org/3/library/logging.handlers.html#logging.FileHandler "(in Python v3.14)") . This can be done by passing it through [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.run "discord.Client.run") : content\_copy import logging handler \= logging.FileHandler(filename\='discord.log', encoding\='utf-8', mode\='w') \# Assume client refers to a discord.Client subclass... client.run(token, log\_handler\=handler) You can also disable the library’s logging configuration completely by passing `None`: content\_copy client.run(token, log\_handler\=None) Likewise, configuring the log level to `logging.DEBUG` is also possible: content\_copy import logging handler \= logging.FileHandler(filename\='discord.log', encoding\='utf-8', mode\='w') \# Assume client refers to a discord.Client subclass... client.run(token, log\_handler\=handler, log\_level\=logging.DEBUG) This is recommended, especially at verbose levels such as `DEBUG`, as there are a lot of events logged and it would clog the stderr of your program. If you want the logging configuration the library provides to affect all loggers rather than just the `discord` logger, you can pass `root_logger=True` inside [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.run "discord.Client.run") : content\_copy client.run(token, log\_handler\=handler, root\_logger\=True) If you want to setup logging using the library provided configuration without using [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.run "discord.Client.run") , you can use [`discord.utils.setup_logging()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.utils.setup_logging "discord.utils.setup_logging") : content\_copy import discord discord.utils.setup\_logging() \# or, for example discord.utils.setup\_logging(level\=logging.INFO, root\=False) More advanced setups are possible with the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.14)") module. The example below configures a rotating file handler that outputs DEBUG output for everything the library outputs, except for HTTP requests: content\_copy import discord import logging import logging.handlers logger \= logging.getLogger('discord') logger.setLevel(logging.DEBUG) logging.getLogger('discord.http').setLevel(logging.INFO) handler \= logging.handlers.RotatingFileHandler( filename\='discord.log', encoding\='utf-8', maxBytes\=32 \* 1024 \* 1024, \# 32 MiB backupCount\=5, \# Rotate through 5 files ) dt\_fmt \= '%Y-%m-%d %H:%M:%S' formatter \= logging.Formatter('\[{asctime}\] \[{levelname:<8}\] {name}: {message}', dt\_fmt, style\='{') handler.setFormatter(formatter) logger.addHandler(handler) \# Assume client refers to a discord.Client subclass... \# Suppress the default configuration since we have our own client.run(token, log\_handler\=None) For more information, check the documentation and tutorial of the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.14)") module. Changed in version 2.0: The library now provides a default logging configuration. arrow\_upward to top --- # Authenticating View Documentation For discord discord.ext.commands discord.ext.tasks search settings Authenticating[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/authenticating.html#authenticating "Permalink to this headline") =================================================================================================================================== Tokens[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/authenticating.html#tokens "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------- Tokens are how we authenticate with Discord. User accounts use the same token system as bots, received after authenticating with the Discord API. How do I obtain mine?[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/authenticating.html#how-do-i-obtain-mine "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------ The library does not yet support authenticating traditionally, so you will have to obtain your token manually. To obtain your token from the Discord client, the easiest way is pasting this into the developer console (CTRL+SHIFT+I): content\_copy (()=>{for(let e of Object.values(webpackChunkdiscord\_app.push(\[\[Symbol()\],{},e\=>e.c\])))try{if(!e.exports||e.exports\===window)continue;if(e.exports?.getToken)return e.exports.getToken();for(let t in e.exports)if(e.exports?.\[t\]?.getToken&&"IntlMessagesProxy"!==e.exports\[t\]\[Symbol.toStringTag\])return e.exports\[t\].getToken()}catch{}})(); Or, you can do it manually: 1. Open developer tools (CTRL+SHIFT+I). 2. Click the Network tab. 3. Click the XHR tab. 4. Select a request and click the Headers tab. 5. Copy-paste the value in the Authorization header. arrow\_upward to top --- # Search View Documentation For discord discord.ext.commands discord.ext.tasks search settings Search ====== Searching for multiple words only shows matches that contain all words. arrow\_upward to top --- # discord.ext.commands – Bot commands framework View Documentation For discord discord.ext.commands discord.ext.tasks search settings `discord.ext.commands` – Bot commands framework[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands-bot-commands-framework "Permalink to this headline") ===================================================================================================================================================================================================== `discord.py` offers a lower level aspect on interacting with Discord. Often times, the library is used for the creation of bots. However this task can be daunting and confusing to get correctly the first time. Many times there comes a repetition in creating a bot command framework that is extensible, flexible, and powerful. For this reason, `discord.py` comes with an extension library that handles this for you. * [Commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/commands.html) * [Parameters](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/commands.html#parameters) * [Invocation Context](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/commands.html#invocation-context) * [Converters](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/commands.html#converters) * [Parameter Metadata](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/commands.html#parameter-metadata) * [Error Handling](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/commands.html#error-handling) * [Checks](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/commands.html#checks) * [Cogs](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/cogs.html) * [Quick Example](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/cogs.html#quick-example) * [Cog Registration](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/cogs.html#cog-registration) * [Using Cogs](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/cogs.html#using-cogs) * [Special Methods](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/cogs.html#special-methods) * [Meta Options](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/cogs.html#meta-options) * [Inspection](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/cogs.html#inspection) * [Extensions](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/extensions.html) * [Primer](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/extensions.html#primer) * [Reloading](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/extensions.html#reloading) * [Cleaning Up](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/extensions.html#cleaning-up) * [API Reference](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html) * [Bots](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#bots) * [Prefix Helpers](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#prefix-helpers) * [Event Reference](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#event-reference) * [Commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#commands) * [Cogs](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#cogs) * [Help Commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#help-commands) * [Enums](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#enums) * [Checks](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#checks) * [Cooldown](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#cooldown) * [Context](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#context) * [Converters](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#converters) * [Defaults](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#defaults) * [Exceptions](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#exceptions) arrow\_upward to top --- # discord.ext.tasks – asyncio.Task helpers View Documentation For discord discord.ext.commands discord.ext.tasks search settings `discord.ext.tasks` – asyncio.Task helpers[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord-ext-tasks-asyncio-task-helpers "Permalink to this headline") ======================================================================================================================================================================================== New in version 1.1.0. One of the most common operations when making a bot is having a loop run in the background at a specified interval. This pattern is very common but has a lot of things you need to look out for: * How do I handle [`asyncio.CancelledError`](https://docs.python.org/3/library/asyncio-exceptions.html#asyncio.CancelledError "(in Python v3.14)") ? * What do I do if the internet goes out? * What is the maximum number of seconds I can sleep anyway? The goal of this discord.py extension is to abstract all these worries away from you. Recipes[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#recipes "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------- A simple background task in a [`Cog`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") : content\_copy from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self): self.index \= 0 self.printer.start() def cog\_unload(self): self.printer.cancel() @tasks.loop(seconds\=5.0) async def printer(self): print(self.index) self.index += 1 Adding an exception to handle during reconnect: content\_copy import asyncpg from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.data \= \[\] self.batch\_update.add\_exception\_type(asyncpg.PostgresConnectionError) self.batch\_update.start() def cog\_unload(self): self.batch\_update.cancel() @tasks.loop(minutes\=5.0) async def batch\_update(self): async with self.bot.pool.acquire() as con: \# batch update here... pass Looping a certain amount of times before exiting: content\_copy from discord.ext import tasks import discord @tasks.loop(seconds\=5.0, count\=5) async def slow\_count(): print(slow\_count.current\_loop) @slow\_count.after\_loop async def after\_slow\_count(): print('done!') class MyClient(discord.Client): async def setup\_hook(self): slow\_count.start() Waiting until the bot is ready before the loop starts: content\_copy from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.index \= 0 self.bot \= bot self.printer.start() def cog\_unload(self): self.printer.cancel() @tasks.loop(seconds\=5.0) async def printer(self): print(self.index) self.index += 1 @printer.before\_loop async def before\_printer(self): print('waiting...') await self.bot.wait\_until\_ready() Doing something during cancellation: content\_copy from discord.ext import tasks, commands import asyncio class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.\_batch \= \[\] self.lock \= asyncio.Lock() self.bulker.start() async def cog\_unload(self): self.bulker.cancel() async def do\_bulk(self): \# bulk insert data here ... @tasks.loop(seconds\=10.0) async def bulker(self): async with self.lock: await self.do\_bulk() @bulker.after\_loop async def on\_bulker\_cancel(self): if self.bulker.is\_being\_cancelled() and len(self.\_batch) != 0: \# if we're cancelled and we have some data left... \# let's insert it to our database await self.do\_bulk() Doing something at a specific time each day: content\_copy import datetime from discord.ext import commands, tasks utc \= datetime.timezone.utc \# If no tzinfo is given then UTC is assumed. time \= datetime.time(hour\=8, minute\=30, tzinfo\=utc) class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.my\_task.start() def cog\_unload(self): self.my\_task.cancel() @tasks.loop(time\=time) async def my\_task(self): print("My task is running!") Doing something at multiple specific times each day: content\_copy import datetime from discord.ext import commands, tasks utc \= datetime.timezone.utc \# If no tzinfo is given then UTC is assumed. times \= \[\ datetime.time(hour\=8, tzinfo\=utc),\ datetime.time(hour\=12, minute\=30, tzinfo\=utc),\ datetime.time(hour\=16, minute\=40, second\=30, tzinfo\=utc)\ \] class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.my\_task.start() def cog\_unload(self): self.my\_task.cancel() @tasks.loop(time\=times) async def my\_task(self): print("My task is running!") API Reference[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#api-reference "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------------------- _class_ discord.ext.tasks.Loop[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop "Permalink to this definition") Attributes * [current\_loop](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.current_loop) * [hours](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.hours) * [minutes](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.minutes) * [next\_iteration](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.next_iteration) * [seconds](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.seconds) * [time](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.time) Methods * async[\_\_call\_\_](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.__call__) * def[add\_exception\_type](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.add_exception_type) * @[after\_loop](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.after_loop) * @[before\_loop](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop) * def[cancel](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.cancel) * def[change\_interval](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.change_interval) * def[clear\_exception\_types](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types) * @[error](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.error) * def[failed](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.failed) * def[get\_task](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.get_task) * def[is\_being\_cancelled](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled) * def[is\_running](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_running) * def[remove\_exception\_type](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.remove_exception_type) * def[restart](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.restart) * def[start](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.start) * def[stop](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.stop) A background task helper that abstracts the loop and reconnection logic for you. The main interface to create this is through [`loop()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.loop "discord.ext.tasks.loop") . @after\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.after_loop "Permalink to this definition") A decorator that registers a coroutine to be called after the loop finishes running. The coroutine must take no arguments (except `self` in a class context). Note This coroutine is called even during cancellation. If it is desirable to tell apart whether something was cancelled or not, check to see whether [`is_being_cancelled()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled "discord.ext.tasks.Loop.is_being_cancelled") is `True` or not. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register after the loop finishes. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function was not a coroutine. @before\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop "Permalink to this definition") A decorator that registers a coroutine to be called before the loop starts running. This is useful if you want to wait for some bot state before the loop starts, such as [`discord.Client.wait_until_ready()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.wait_until_ready "discord.Client.wait_until_ready") . The coroutine must take no arguments (except `self` in a class context). Changed in version 2.0: Calling [`stop()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.stop "discord.ext.tasks.Loop.stop") in this coroutine will stop the initial iteration from running. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register before the loop runs. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function was not a coroutine. @error[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.error "Permalink to this definition") A decorator that registers a coroutine to be called if the task encounters an unhandled exception. The coroutine must take only one argument the exception raised (except `self` in a class context). By default this logs to the library logger however it could be overridden to have a different implementation. New in version 1.4. Changed in version 2.0: Instead of writing to `sys.stderr`, the library’s logger is used. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register in the event of an unhandled exception. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function was not a coroutine. _property_ seconds[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.seconds "Permalink to this definition") Read-only value for the number of seconds between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)")\ \] _property_ minutes[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.minutes "Permalink to this definition") Read-only value for the number of minutes between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)")\ \] _property_ hours[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.hours "Permalink to this definition") Read-only value for the number of hours between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)")\ \] _property_ time[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.time "Permalink to this definition") Read-only list for the exact times this loop runs at. `None` if relative times were passed instead. New in version 2.0. Type Optional\[List\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ \]\] _property_ current\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.current_loop "Permalink to this definition") The current iteration of the loop. Type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") _property_ next\_iteration[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.next_iteration "Permalink to this definition") When the next iteration of the loop will occur. New in version 1.3. Type Optional\[[`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.14)")\ \] _await_ \_\_call\_\_(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.__call__ "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Calls the internal callback that the task holds. New in version 1.6. Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. start(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.start "Permalink to this definition") Starts the internal task in the event loop. Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. Raises [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.14)") – A task has already been launched and is running. Returns The task that has been created. Return type [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.14)") stop()[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.stop "Permalink to this definition") Gracefully stops the task from running. Unlike [`cancel()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "discord.ext.tasks.Loop.cancel") , this allows the task to finish its current iteration before gracefully exiting. Note If the internal function raises an error that can be handled before finishing then it will retry until it succeeds. If this is undesirable, either remove the error handling before stopping via [`clear_exception_types()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types "discord.ext.tasks.Loop.clear_exception_types") or use [`cancel()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "discord.ext.tasks.Loop.cancel") instead. Changed in version 2.0: Calling this method in [`before_loop()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop "discord.ext.tasks.Loop.before_loop") will stop the first iteration from running. New in version 1.2. cancel()[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "Permalink to this definition") Cancels the internal task, if it is running. restart(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.restart "Permalink to this definition") A convenience method to restart the internal task. Note Due to the way this function works, the task is not returned like [`start()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.start "discord.ext.tasks.Loop.start") . Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. add\_exception\_type(_\*exceptions_)[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.add_exception_type "Permalink to this definition") Adds exception types to be handled during the reconnect logic. By default the exception types handled are those handled by [`discord.Client.connect()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.connect "discord.Client.connect") , which includes a lot of internet disconnection errors. This function is useful if you’re interacting with a 3rd party library that raises its own set of exceptions. Parameters **\*exceptions** (Type\[[`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.14)")\ \]) – An argument list of exception classes to handle. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – An exception passed is either not a class or not inherited from [`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.14)") . clear\_exception\_types()[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types "Permalink to this definition") Removes all exception types that are handled. Note This operation obviously cannot be undone! remove\_exception\_type(_\*exceptions_)[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.remove_exception_type "Permalink to this definition") Removes exception types from being handled during the reconnect logic. Parameters **\*exceptions** (Type\[[`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.14)")\ \]) – An argument list of exception classes to handle. Returns Whether all exceptions were successfully removed. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") get\_task()[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.get_task "Permalink to this definition") Optional\[[`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.14)")\ \]: Fetches the internal task or `None` if there isn’t one running. is\_being\_cancelled()[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled "Permalink to this definition") Whether the task is being cancelled. failed()[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.failed "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Whether the internal task has failed. New in version 1.2. is\_running()[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_running "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Check if the task is currently running. New in version 1.4. change\_interval(_\*_, _seconds\=0_, _minutes\=0_, _hours\=0_, _time\=..._)[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop.change_interval "Permalink to this definition") Changes the interval for the sleep time. New in version 1.2. Parameters * **seconds** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of seconds between every iteration. * **minutes** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of minutes between every iteration. * **hours** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of hours between every iteration. * **time** (Union\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ , Sequence\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ \]\]) – The exact times to run this loop at. Either a non-empty list or a single value of [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)") should be passed. This cannot be used in conjunction with the relative time parameters. New in version 2.0. Note Duplicate times will be ignored, and only run once. Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – An invalid value was given. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – An invalid value for the `time` parameter was passed, or the `time` parameter was passed in conjunction with relative time parameters. @discord.ext.tasks.loop(_\*_, _seconds\=..._, _minutes\=..._, _hours\=..._, _time\=..._, _count\=None_, _reconnect\=True_, _name\=None_)[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.loop "Permalink to this definition") A decorator that schedules a task in the background for you with optional reconnect logic. The decorator returns a [`Loop`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.Loop "discord.ext.tasks.Loop") . Parameters * **seconds** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of seconds between every iteration. * **minutes** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of minutes between every iteration. * **hours** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The number of hours between every iteration. * **time** (Union\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ , Sequence\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)")\ \]\]) – The exact times to run this loop at. Either a non-empty list or a single value of [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.14)") should be passed. Timezones are supported. If no timezone is given for the times, it is assumed to represent UTC time. This cannot be used in conjunction with the relative time parameters. Note Duplicate times will be ignored, and only run once. New in version 2.0. * **count** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The number of loops to do, `None` if it should be an infinite loop. * **reconnect** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to handle errors and restart the task using an exponential back-off algorithm similar to the one used in [`discord.Client.connect()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.connect "discord.Client.connect") . * **name** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The name to assign to the internal task. By default it is assigned a name based off of the callable name such as `discord-ext-tasks: function_name`. New in version 2.1. Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – An invalid value was given. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function was not a coroutine, an invalid value for the `time` parameter was passed, or `time` parameter was passed in conjunction with relative time parameters. arrow\_upward to top --- # Version Guarantees View Documentation For discord discord.ext.commands discord.ext.tasks search settings Version Guarantees[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/version_guarantees.html#version-guarantees "Permalink to this headline") =============================================================================================================================================== The library follows a [semantic versioning principle](https://semver.org/) which means that the major version is updated every time there is an incompatible API change. However due to the lack of guarantees on the Discord side when it comes to breaking changes along with the fairly dynamic nature of Python it can be hard to discern what can be considered a breaking change and what isn’t. The first thing to keep in mind is that breaking changes only apply to **publicly documented functions and classes**. If it’s not listed in the documentation here then it is not part of the public API and is thus bound to change. This includes attributes that start with an underscore or functions without an underscore that are not documented. However, the Discord user API is in constant flux, so sometimes breaking changes may creep in. The guarantee is that patch releases will not introduce breaking changes, but minor releases may introduce minor ones. Major breaking changes will continue to be reserved for major releases. Note The examples below are non-exhaustive. Examples of Breaking Changes[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/version_guarantees.html#examples-of-breaking-changes "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Changing the default parameter value to something else. * Renaming a function without an alias to an old function. * Adding or removing parameters to an event. Examples of Non-Breaking Changes[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/version_guarantees.html#examples-of-non-breaking-changes "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Adding or removing private underscored attributes. * Adding an element into the `__slots__` of a data class. * Changing the behaviour of a function to fix a bug. * Changes in the documentation. * Modifying the internal HTTP handling. * Upgrading the dependencies to a new version, major or otherwise. arrow\_upward to top --- # Changelog View Documentation For discord discord.ext.commands discord.ext.tasks search settings Changelog[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/whats_new.html#changelog "Permalink to this headline") ==================================================================================================================== This page keeps a detailed human friendly rendering of what’s new and changed in specific versions. v2.1.0[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/whats_new.html#v2-1-0 "Permalink to this headline") -------------------------------------------------------------------------------------------------------------- Due to the enormous amount of changes in this release, some minor changes may be omitted from this changelog. Please refer to the documentation for more details on specific features. ### New Features[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/whats_new.html#new-features "Permalink to this headline") * Add new flags to [`ApplicationFlags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ApplicationFlags "discord.ApplicationFlags") , [`PublicUserFlags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PublicUserFlags "discord.PublicUserFlags") , [`MessageFlags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MessageFlags "discord.MessageFlags") , [`MemberFlags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MemberFlags "discord.MemberFlags") , [`ChannelFlags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ChannelFlags "discord.ChannelFlags") , and more * Support new [`MessageType`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MessageType "discord.MessageType") values, update [`Message.system_content`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.system_content "discord.Message.system_content") accordingly * Support new [`ConnectionType`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ConnectionType "discord.ConnectionType") values * Overhaul rich presence, adding support for viewing and sending all activity fields (including many new fields) * New activity type: [`ActivityType.hang`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ActivityType.hang "discord.ActivityType.hang") , supported via [`HangActivity`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.HangActivity "discord.HangActivity") * New classes: [`ActivityParty`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ActivityParty "discord.ActivityParty") , [`ActivityAssets`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ActivityAssets "discord.ActivityAssets") , [`ActivitySecrets`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ActivitySecrets "discord.ActivitySecrets") , and [`ActivityTimestamps`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ActivityTimestamps "discord.ActivityTimestamps") * Deprecated [`Game`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Game "discord.Game") and [`Streaming`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Streaming "discord.Streaming") in favour of [`Activity`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Activity "discord.Activity") * Made [`Spotify`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Spotify "discord.Spotify") constructible and sendable via [`Client.change_presence()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.change_presence "discord.Client.change_presence") * Add [`Client.proxy_external_application_assets()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.proxy_external_application_assets "discord.Client.proxy_external_application_assets") to proxy external assets for rich presence * Support read states * New low-level interface: [`ReadState`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ReadState "discord.ReadState") * Access all read states from [`Client.read_states`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.read_states "discord.Client.read_states") and access per-channel read states via the [`TextChannel.read_state`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.TextChannel.read_state "discord.TextChannel.read_state") attribute * Add rich attributes: [`TextChannel.acked_message_id`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.TextChannel.acked_message_id "discord.TextChannel.acked_message_id") , [`TextChannel.acked_message`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.TextChannel.acked_message "discord.TextChannel.acked_message") , [`TextChannel.acked_pin_timestamp`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.TextChannel.acked_pin_timestamp "discord.TextChannel.acked_pin_timestamp") , [`TextChannel.mention_count`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.TextChannel.mention_count "discord.TextChannel.mention_count") , and [`TextChannel.last_viewed_timestamp`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.TextChannel.last_viewed_timestamp "discord.TextChannel.last_viewed_timestamp") * Add [`abc.Messageable.unack()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.unack "discord.abc.Messageable.unack") to unacknowledge all messages in a channel * Add [`Client.bulk_ack()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.bulk_ack "discord.Client.bulk_ack") to acknowledge multiple read states at once * Support experiments * Add [`UserExperiment`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.UserExperiment "discord.UserExperiment") and [`GuildExperiment`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.GuildExperiment "discord.GuildExperiment") * Access user experiments via [`Client.experiments`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.experiments "discord.Client.experiments") and guild experiments via [`Client.guild_experiments`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.guild_experiments "discord.Client.guild_experiments") * Add [`Client.get_experiment()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.get_experiment "discord.Client.get_experiment") helper and [`Client.fetch_experiments()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_experiments "discord.Client.fetch_experiments") coroutine * Add message search functionality * Search guilds with [`Guild.search()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.search "discord.Guild.search") * Search channels with [`abc.Messageable.search()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.search "discord.abc.Messageable.search") * Add support for the new username system (also known as “pomelo”) * Add [`User.is_pomelo()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.User.is_pomelo "discord.User.is_pomelo") to check if a user has been migrated * Add [`User.global_name`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.User.global_name "discord.User.global_name") to get their global nickname or “display name” * Update [`User.display_name`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.User.display_name "discord.User.display_name") and [`Member.display_name`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Member.display_name "discord.Member.display_name") to understand global nicknames * Update `__str__` for [`User`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.User "discord.User") to drop discriminators if the user has been migrated * Update [`Guild.get_member_named()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.get_member_named "discord.Guild.get_member_named") to work with migrated users * Update [`User.default_avatar`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.User.default_avatar "discord.User.default_avatar") to work with migrated users * Update [`ClientUser.edit()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ClientUser.edit "discord.ClientUser.edit") to allow migrating and changing global names * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Update user and member converters to understand migrated users * Add GCP uploads * Allows pre-uploading files to Google Cloud Storage for faster file sending * Supports uploading in parallel and allows reusing previously uploaded files * Allows sending files up to 500 MiB each (Nitro only) * Implemented via [`CloudFile`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.CloudFile "discord.CloudFile") and [`abc.Messageable.upload_files()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.upload_files "discord.abc.Messageable.upload_files") * The [`CloudFile`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.CloudFile "discord.CloudFile") instances can be used in place of [`File`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.File "discord.File") instances when sending messages * Support application command fetching V3 * Add [`abc.Messageable.application_commands()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.application_commands "discord.abc.Messageable.application_commands") and [`Guild.application_commands()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.application_commands "discord.Guild.application_commands") to get all application commands in a guild or private channel * Alias and deprecate all old application command fetching methods * It is highly recommended that the result of this method is cached to avoid rate limits * Support hubs * Add [`DirectoryChannel`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.DirectoryChannel "discord.DirectoryChannel") , [`DirectoryEntry`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.DirectoryEntry "discord.DirectoryEntry") , and relevant methods for fetching and creating * Add [`Guild.hub_type`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.hub_type "discord.Guild.hub_type") * Add [`Client.join_hub_waitlist()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.join_hub_waitlist "discord.Client.join_hub_waitlist") , [`Client.lookup_hubs()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.lookup_hubs "discord.Client.lookup_hubs") , and [`Client.join_hub()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.join_hub "discord.Client.join_hub") * Support friend suggestions * Add [`FriendSuggestion`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.FriendSuggestion "discord.FriendSuggestion") and [`Client.friend_suggestion_count`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.friend_suggestion_count "discord.Client.friend_suggestion_count") * Add [`Client.friend_suggestions()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.friend_suggestions "discord.Client.friend_suggestions") * Add new events, [`on_friend_suggestion_add()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_friend_suggestion_add "discord.on_friend_suggestion_add") and [`on_friend_suggestion_remove()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_friend_suggestion_remove "discord.on_friend_suggestion_remove") * Support OAuth2 authorizations * Add [`Client.oauth2_tokens()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.oauth2_tokens "discord.Client.oauth2_tokens") , [`Client.fetch_authorization()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_authorization "discord.Client.fetch_authorization") , [`Client.create_authorization()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.create_authorization "discord.Client.create_authorization") * Heavily improve guild subscriptions * \[BREAKING\] Remove `Guild.request` method; use [`Guild.subscribe()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.subscribe "discord.Guild.subscribe") instead * Allow disabling auto guild subscription via `guild_subscriptions` parameter in [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") * Add [`Guild.is_subscribed()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.is_subscribed "discord.Guild.is_subscribed") and [`Guild.is_subscribed_to()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.is_subscribed_to "discord.Guild.is_subscribed_to") to check if the client is subscribed to a guild * Add [`Guild.subscribe()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.subscribe "discord.Guild.subscribe") and [`Guild.subscribe_to()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.subscribe_to "discord.Guild.subscribe_to") to allow manually managing guild subscriptions * \[BREAKING\] User notes handling is now entirely rewritten * The `UserNote` class is removed; notes are now represented as strings * `Client.notes` is renamed to [`Client.fetch_notes()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_notes "discord.Client.fetch_notes") for forward-compatibility * Update various payment and billing related models to add new fields * \[BREAKING\] Remove `Payment.refund` as it is no longer supported by the API * Add `BRAINTREE_KEY`, `STRIPE_KEY`, and `ADYEN_KEY` to package exports * Add `message_send_cooldown` and `thread_create_cooldown` attributes to the [`abc.Messageable.typing()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.typing "discord.abc.Messageable.typing") context manager. * Add [`Client.channel_affinities()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.channel_affinities "discord.Client.channel_affinities") to get channel affinities and [`Client.premium_affinities()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.premium_affinities "discord.Client.premium_affinities") to get premium user affinities * Add various new fields to [`Application`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Application "discord.Application") and [`PartialApplication`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PartialApplication "discord.PartialApplication") , update implementations to match API * Allow passing `activities`, `afk`, and `idle_since` to [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") for initial presence setup * Add [`Client.is_afk()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.is_afk "discord.Client.is_afk") and [`Client.idle_since`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.idle_since "discord.Client.idle_since") helpers * Allow passing `preferred_rtc_regions` to [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") to override Discord’s suggested RTC regions * \[BREAKING\] Rename `Client.preferred_voice_regions` to [`Client.preferred_rtc_regions`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.preferred_rtc_regions "discord.Client.preferred_rtc_regions") to match the API * \[BREAKING\] Rename `Client.fetch_preferred_voice_regions` to [`Client.fetch_preferred_rtc_regions()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_preferred_rtc_regions "discord.Client.fetch_preferred_rtc_regions") to match the API * \[BREAKING\] Remove `preferred_region` from [`Client.change_voice_state()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.change_voice_state "discord.Client.change_voice_state") and [`Guild.change_voice_state()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.change_voice_state "discord.Guild.change_voice_state") * Allow setting the [`Client.preferred_rtc_regions`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.preferred_rtc_regions "discord.Client.preferred_rtc_regions") property after initialisation * Allow passing `canary` to [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") to use the canary API * Allow passing `timezone` to [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") to configure the timezone broadcasted to Discord * Add [`Tutorial`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Tutorial "discord.Tutorial") and [`Client.tutorial`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.tutorial "discord.Client.tutorial") to access new user tutorial information * Add `with_permissions` to [`Client.fetch_invite()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_invite "discord.Client.fetch_invite") * Add [`Client.create_invite()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.create_invite "discord.Client.create_invite") and [`Client.revoke_invites()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.revoke_invites "discord.Client.revoke_invites") to create and revoke friend invites * Allow [`Client.create_group()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.create_group "discord.Client.create_group") to create a group channel with only one other recipient * \[BREAKING\] Rename `Client.relationship_activity_statistics` to [`Client.global_activity_statistics()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.global_activity_statistics "discord.Client.global_activity_statistics") to better reflect its purpose * Add [`Client.user_offer()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.user_offer "discord.Client.user_offer") to replace deprecated [`Client.trial_offer()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.trial_offer "discord.Client.trial_offer") * Add [`Client.report_unverified_application()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.report_unverified_application "discord.Client.report_unverified_application") to report game detection issues * Add [`Client.recent_avatars()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.recent_avatars "discord.Client.recent_avatars") to get recently used avatars * Add [`Guild.query_recent_members()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.query_recent_members "discord.Guild.query_recent_members") to fetch members who recently joined * Add various new fields to [`UserProfile`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.UserProfile "discord.UserProfile") and [`MemberProfile`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MemberProfile "discord.MemberProfile") * Note that nearly all fields are unavailable if the user has blocked the client user. This can be determined with [`UserProfile.is_blocker()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.UserProfile.is_blocker "discord.UserProfile.is_blocker") * Add [`DefaultAvatar.pink`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.DefaultAvatar.pink "discord.DefaultAvatar.pink") for new pink default avatars * Add [`Colour.pink()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.pink "discord.Colour.pink") to get the pink default avatar colour * Add support for voice messages ([GH-9358](https://github.com/dolfies/discord.py-self/issues/9358) ) * Add [`Attachment.duration`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Attachment.duration "discord.Attachment.duration") and [`Attachment.waveform`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Attachment.waveform "discord.Attachment.waveform") * Add [`Attachment.is_voice_message()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Attachment.is_voice_message "discord.Attachment.is_voice_message") * This does not support _sending_ voice messages yet * Add support for [`TextChannel.default_thread_slowmode_delay`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.TextChannel.default_thread_slowmode_delay "discord.TextChannel.default_thread_slowmode_delay") * Add support for [`ForumChannel.default_sort_order`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ForumChannel.default_sort_order "discord.ForumChannel.default_sort_order") * Add support for `default_reaction_emoji` and `default_forum_layout` in [`Guild.create_forum()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.create_forum "discord.Guild.create_forum") * Add support for `widget_channel`, `widget_enabled`, and `mfa_level` in [`Guild.edit()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.edit "discord.Guild.edit") * Add various new [`Permissions`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Permissions "discord.Permissions") and changes * Add support for `with_counts` parameter to [`Client.fetch_guilds()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_guilds "discord.Client.fetch_guilds") * Add new [`Guild.get_emoji()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.get_emoji "discord.Guild.get_emoji") helper * Add [`Guild.max_stage_video_channel_users`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.max_stage_video_channel_users "discord.Guild.max_stage_video_channel_users") and [`Guild.safety_alerts_channel`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.safety_alerts_channel "discord.Guild.safety_alerts_channel") * Add support for `raid_alerts_disabled` and `safety_alerts_channel` in [`Guild.edit()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.edit "discord.Guild.edit") . * Add support for Polls ([GH-9759](https://github.com/dolfies/discord.py-self/issues/9759) ). * Polls can be created using [`Poll`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Poll "discord.Poll") and the `poll` keyword-only parameter in various message sending methods * Add [`PollAnswer`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PollAnswer "discord.PollAnswer") and [`PollMedia`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PollMedia "discord.PollMedia") * Add [`Message.end_poll()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.end_poll "discord.Message.end_poll") method to end polls * Add new events, [`on_poll_vote_add()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_poll_vote_add "discord.on_poll_vote_add") , [`on_poll_vote_remove()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_poll_vote_remove "discord.on_poll_vote_remove") , [`on_raw_poll_vote_add()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_raw_poll_vote_add "discord.on_raw_poll_vote_add") , and [`on_raw_poll_vote_remove()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_raw_poll_vote_remove "discord.on_raw_poll_vote_remove") * Voice handling has been completely rewritten to fix many bugs * Add support for [`RawReactionActionEvent.message_author_id`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.RawReactionActionEvent.message_author_id "discord.RawReactionActionEvent.message_author_id") * Add support for [`AuditLogAction.creator_monetization_request_created`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AuditLogAction.creator_monetization_request_created "discord.AuditLogAction.creator_monetization_request_created") and [`AuditLogAction.creator_monetization_terms_accepted`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AuditLogAction.creator_monetization_terms_accepted "discord.AuditLogAction.creator_monetization_terms_accepted") * Add support for [`AttachmentFlags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AttachmentFlags "discord.AttachmentFlags") , accessed via [`Attachment.flags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Attachment.flags "discord.Attachment.flags") * Add support for [`RoleFlags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.RoleFlags "discord.RoleFlags") , accessed via [`Role.flags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Role.flags "discord.Role.flags") * Add support for [`ChannelType.media`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ChannelType.media "discord.ChannelType.media") , accessed via [`ForumChannel.is_media()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ForumChannel.is_media "discord.ForumChannel.is_media") * Add shortcut for [`CategoryChannel.forums`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.CategoryChannel.forums "discord.CategoryChannel.forums") . * Add encoder options to [`VoiceClient.play()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.VoiceClient.play "discord.VoiceClient.play") * Add optional attribute `integration_type` in [`AuditLogEntry.extra`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AuditLogEntry.extra "discord.AuditLogEntry.extra") for `kick` or `member_role_update` actions * Add support for reading burst reactions * Add [`Reaction.normal_count`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Reaction.normal_count "discord.Reaction.normal_count") * Add [`Reaction.burst_count`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Reaction.burst_count "discord.Reaction.burst_count") * Add [`Reaction.me_burst`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Reaction.me_burst "discord.Reaction.me_burst") * Add `scheduled_event` parameter for [`StageChannel.create_instance()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.StageChannel.create_instance "discord.StageChannel.create_instance") * Add support for auto mod members * Add `type` keyword argument to [`AutoModRuleAction`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AutoModRuleAction "discord.AutoModRuleAction") * Add [`AutoModTrigger.mention_raid_protection`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AutoModTrigger.mention_raid_protection "discord.AutoModTrigger.mention_raid_protection") * Add [`AutoModRuleTriggerType.member_profile`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AutoModRuleTriggerType.member_profile "discord.AutoModRuleTriggerType.member_profile") * Add [`AutoModRuleEventType.member_update`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AutoModRuleEventType.member_update "discord.AutoModRuleEventType.member_update") * Add [`AutoModRuleActionType.block_member_interactions`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AutoModRuleActionType.block_member_interactions "discord.AutoModRuleActionType.block_member_interactions") * Add support for getting/fetching threads from [`Message`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message "discord.Message") * Add [`PartialMessage.thread`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PartialMessage.thread "discord.PartialMessage.thread") * Add [`Message.thread`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.thread "discord.Message.thread") * Add [`Message.fetch_thread()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.fetch_thread "discord.Message.fetch_thread") * Add support for adding forum thread tags via webhook * Add [`Locale.latin_american_spanish`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Locale.latin_american_spanish "discord.Locale.latin_american_spanish") * Add support for setting voice channel status * Add support for guild incidents * Updated [`Guild.edit()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.edit "discord.Guild.edit") with `invites_disabled_until` and `dms_disabled_until` parameters * Add [`Guild.invites_paused_until`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.invites_paused_until "discord.Guild.invites_paused_until") * Add [`Guild.dms_paused_until`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.dms_paused_until "discord.Guild.dms_paused_until") * Add [`Guild.invites_paused()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.invites_paused "discord.Guild.invites_paused") * Add [`Guild.dms_paused()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.dms_paused "discord.Guild.dms_paused") * Add support for [`abc.User.avatar_decoration`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.User.avatar_decoration "discord.abc.User.avatar_decoration") * Add support for GIF stickers * Add support for bulk banning members via [`Guild.bulk_ban()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.bulk_ban "discord.Guild.bulk_ban") * Add `reason` keyword argument to [`Thread.delete()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Thread.delete "discord.Thread.delete") * Add support for reaction types to raw and non-raw models * Add support for message forwarding * Adds [`MessageReferenceType`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MessageReferenceType "discord.MessageReferenceType") * Adds [`MessageSnapshot`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MessageSnapshot "discord.MessageSnapshot") * Adds `type` parameter to [`MessageReference`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MessageReference "discord.MessageReference") , [`MessageReference.from_message()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MessageReference.from_message "discord.MessageReference.from_message") , and [`PartialMessage.to_reference()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PartialMessage.to_reference "discord.PartialMessage.to_reference") * Add ``PartialMessage.forward`ionCallbackResponse.resource()`` will be different * Add [`PartialWebhookChannel.mention`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PartialWebhookChannel.mention "discord.PartialWebhookChannel.mention") attribute * Add richer [`Role.move()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Role.move "discord.Role.move") interface * Add support for [`EmbedFlags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.EmbedFlags "discord.EmbedFlags") via [`Embed.flags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Embed.flags "discord.Embed.flags") * Add [`ForumChannel.members`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ForumChannel.members "discord.ForumChannel.members") property * Add [`PartialMessageable.mention`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PartialMessageable.mention "discord.PartialMessageable.mention") * Add support for purchase notification messages * Add new type [`MessageType.purchase_notification`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.MessageType.purchase_notification "discord.MessageType.purchase_notification") * Add new models [`GuildProductPurchase`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.GuildProductPurchase "discord.GuildProductPurchase") and [`PurchaseNotification`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PurchaseNotification "discord.PurchaseNotification") * Add [`Message.purchase_notification`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message.purchase_notification "discord.Message.purchase_notification") * Add `category` parameter to [`abc.GuildChannel.clone()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.GuildChannel.clone "discord.abc.GuildChannel.clone") * Parse full message for message edit event * Adds [`RawMessageUpdateEvent.message`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.RawMessageUpdateEvent.message "discord.RawMessageUpdateEvent.message") attribute * Potentially speeds up [`on_message_edit()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_message_edit "discord.on_message_edit") by no longer copying data * Allow passing `None` for `scopes` parameter in [`utils.oauth_url()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.utils.oauth_url "discord.utils.oauth_url") * Add [`Guild.dm_spam_detected_at`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.dm_spam_detected_at "discord.Guild.dm_spam_detected_at") and [`Guild.is_dm_spam_detected()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.is_dm_spam_detected "discord.Guild.is_dm_spam_detected") * Add [`Guild.raid_detected_at`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.raid_detected_at "discord.Guild.raid_detected_at") and [`Guild.is_raid_detected()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.is_raid_detected "discord.Guild.is_raid_detected") * Add [`Client.fetch_sticker_pack()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_sticker_pack "discord.Client.fetch_sticker_pack") * Add [`Guild.fetch_role()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.fetch_role "discord.Guild.fetch_role") * Add new [`Attachment`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Attachment "discord.Attachment") fields * Add [`Member.guild_banner`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Member.guild_banner "discord.Member.guild_banner") and [`Member.display_banner`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Member.display_banner "discord.Member.display_banner") * Add support for guild tags (also known as primary guilds) * This is through the [`PrimaryGuild`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PrimaryGuild "discord.PrimaryGuild") class * You retrieve this via [`Member.primary_guild`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Member.primary_guild "discord.Member.primary_guild") * Add support for the new pins endpoint * This turns [`abc.Messageable.pins()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.pins "discord.abc.Messageable.pins") into an async iterator * The old eager behaviour of using `await` is still supported, but is now deprecated * Add support for guild onboarding * Completing onboarding is still not supported * Add support new gradient and holographic role colours * Add [`Locale.language_code`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Locale.language_code "discord.Locale.language_code") attribute * Add support for guest invites * Add `File.uri` to get the `attachment://` URI of a file * Add ability to create a media-only forum channel via `media` parameter in [`Guild.create_forum()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.create_forum "discord.Guild.create_forum") * Add new colours from the new Discord themes * This updates the old [`Colour.dark_theme()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.dark_theme "discord.Colour.dark_theme") , [`Colour.light_theme()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.light_theme "discord.Colour.light_theme") , [`Colour.light_embed()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.light_embed "discord.Colour.light_embed") and [`Colour.dark_embed()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.dark_embed "discord.Colour.dark_embed") * This adds [`Colour.ash_theme()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.ash_theme "discord.Colour.ash_theme") , [`Colour.ash_embed()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.ash_embed "discord.Colour.ash_embed") , [`Colour.onyx_theme()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.onyx_theme "discord.Colour.onyx_theme") , and [`Colour.onyx_embed()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.onyx_embed "discord.Colour.onyx_embed") * \[[ext.tasks](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord-ext-tasks)\ \] Add `name` parameter to [`loop()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord.ext.tasks.loop "discord.ext.tasks.loop") to name the internal [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.14)") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Add fallback behaviour to `CurrentGuild` * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Add logging for errors that occur during [`cog_unload()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Cog.cog_unload "discord.ext.commands.Cog.cog_unload") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Add support for [`typing.NewType`](https://docs.python.org/3/library/typing.html#typing.NewType "(in Python v3.14)") and `type` keyword type aliases * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Add support for positional-only flag parameters * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Add support for channel URLs in ChannelConverter related classes * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Add [`BadLiteralArgument.argument`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.BadLiteralArgument.argument "discord.ext.commands.BadLiteralArgument.argument") to get the failed argument’s value * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Add [`Context.filesize_limit`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Context.filesize_limit "discord.ext.commands.Context.filesize_limit") property * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Add support for [`Parameter.displayed_name`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Parameter.displayed_name "discord.ext.commands.Parameter.displayed_name") ### Bug Fixes[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/whats_new.html#bug-fixes "Permalink to this headline") * Fix TLS fingerprinting issues causing unnecessary CAPTCHA challenges and blocked requests * Fix the type of [`ClientUser.phone`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ClientUser.phone "discord.ClientUser.phone") to be a string * Fix various state issues when managing guild subscriptions * \[BREAKING\] Remove no longer functional `validate` parameter from [`abc.GuildChannel.create_invite()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.GuildChannel.create_invite "discord.abc.GuildChannel.create_invite") * Improve presence syncing to reduce unnecessary updates and lost presences * \[BREAKING\] Update return type of [`Client.detectable_applications()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.detectable_applications "discord.Client.detectable_applications") to fix a crash due to an API change * \[BREAKING\] Remove nonexistant `Gift.revoked` attribute * \[BREAKING\] Rename `Guild.owner_application_id` to `Guild.application_id` to match API and upstream * \[BREAKING\] Remove no longer functional `Guild.application_command_counts` attribute * Fix crash in [`Integration`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Integration "discord.Integration") with the Twitch integration ID being a string * Improve member and relationship presence support and handling * Fix `FileHandler` handlers being written ANSI characters when the bot is executed inside PyCharm * This has the side effect of removing coloured logs from the PyCharm terminal due an upstream bug involving TTY detection. This issue is tracked under [PY-43798](https://youtrack.jetbrains.com/issue/PY-43798) * Fix channel edits with [`Webhook.edit()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Webhook.edit "discord.Webhook.edit") sending two requests instead of one * Fix [`StageChannel.last_message_id`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.StageChannel.last_message_id "discord.StageChannel.last_message_id") always being `None` * Fix piped audio input ending prematurely * Fix AutoMod audit log entry error due to empty `channel_id` * Fix handling of `around` parameter in [`abc.Messageable.history()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.Messageable.history "discord.abc.Messageable.history") * Fix [`utils.escape_markdown()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.utils.escape_markdown "discord.utils.escape_markdown") not escaping the new markdown * Fix webhook targets not being converted in audit logs * Fix error when not passing `enabled` in [`Guild.create_automod_rule()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.create_automod_rule "discord.Guild.create_automod_rule") * Fix how various parameters are handled in [`Guild.create_scheduled_event()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.create_scheduled_event "discord.Guild.create_scheduled_event") * Fix not sending the `ssrc` parameter when sending the `SPEAKING` voice payload * Fix username lookup in [`Guild.get_member_named()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.get_member_named "discord.Guild.get_member_named") * Fix false positives in [`PartialEmoji.from_str()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.PartialEmoji.from_str "discord.PartialEmoji.from_str") inappropriately setting `animated` to `True` * Fix `NameError` when using [`abc.GuildChannel.create_invite()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.abc.GuildChannel.create_invite "discord.abc.GuildChannel.create_invite") * Fix escape behaviour for lists and headers in [`escape_markdown()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.utils.escape_markdown "discord.utils.escape_markdown") * Fixes and improvements for [`FFmpegAudio`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.FFmpegAudio "discord.FFmpegAudio") and all related subclasses * Fix [`Template.source_guild()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Template.source_guild "discord.Template.source_guild") attempting to resolve from cache * Fix [`IndexError`](https://docs.python.org/3/library/exceptions.html#IndexError "(in Python v3.14)") being raised instead of [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") when calling [`Colour.from_str()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Colour.from_str "discord.Colour.from_str") with an empty string * Fix possible error in voice cleanup logic * Fix possible bad voice state where you move to a voice channel with missing permissions * Fix handling of [`AuditLogDiff`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AuditLogDiff "discord.AuditLogDiff") when relating to auto mod triggers * Fix race condition in voice logic relating to disconnect and connect * Fix restriction on auto moderation audit log ID range * Fix comparison between [`Object`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Object "discord.Object") classes with a `type` set * Fix handling of an enum in [`AutoModRule.edit()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AutoModRule.edit "discord.AutoModRule.edit") * Fix handling of [`Client.close()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.close "discord.Client.close") within `Client.__aexit__()` * Fix channel deletion not evicting related threads from cache * Fix bug with cache superfluously incrementing role positions * Fix `exempt_channels` not being passed along in [`Guild.create_automod_rule()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Guild.create_automod_rule "discord.Guild.create_automod_rule") * Fix `abc.GuildChannel.purge()` failing if the message was deleted * Handle improper 1000 close code closures by Discord * Add support for AEAD XChaCha20 Poly1305 encryption model * This allows voice to continue working when the older encryption modes eventually get removed * Update all channel clone implementations to work as expected * Fix [`TextChannel.clone()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.TextChannel.clone "discord.TextChannel.clone") always sending slowmode when not applicable to news channels * Fix [`Sticker.url`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Sticker.url "discord.Sticker.url") for GIF stickers * Fix [`User.default_avatar`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.User.default_avatar "discord.User.default_avatar") for team users and webhooks * Fix [`AuditLogEntry.target`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AuditLogEntry.target "discord.AuditLogEntry.target") causing errors for [`AuditLogAction.message_pin`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AuditLogAction.message_pin "discord.AuditLogAction.message_pin") and [`AuditLogAction.message_unpin`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.AuditLogAction.message_unpin "discord.AuditLogAction.message_unpin") actions * Fix path sanitisation for absolute Windows paths when using `__main__` * Create [`ScheduledEvent`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.ScheduledEvent "discord.ScheduledEvent") on cache miss for [`on_scheduled_event_delete()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.on_scheduled_event_delete "discord.on_scheduled_event_delete") * Add defaults for [`Message`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Message "discord.Message") creation preventing some crashes * Fix voice connection issues and upgrade the voice version to 8 * Fix calculation of hashed rate limit keys * Fix [`Thread.applied_tags`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Thread.applied_tags "discord.Thread.applied_tags") being empty for media channels * Fix potentially stuck ratelimit buckets in certain circumstances * Fix audit log `automod_rule_trigger_type` extra being missing * \[[ext.tasks](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/tasks/index.html#discord-ext-tasks)\ \] Fix race condition when setting timer handle when using uvloop * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Fix issue with category cooldowns outside of guild channels * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Fix callable FlagConverter defaults on hybrid commands not being called * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Unwrap [`Parameter`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Parameter "discord.ext.commands.Parameter") if given as default to [`parameter()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.parameter "discord.ext.commands.parameter") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Fix fallback behaviour not being respected when calling replace for [`Parameter`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Parameter "discord.ext.commands.Parameter") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Fix [`HelpCommand`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.HelpCommand "discord.ext.commands.HelpCommand") defined checks not carrying over during copy * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Fix the wrong [`on_help_command_error()`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.HelpCommand.on_help_command_error "discord.ext.commands.HelpCommand.on_help_command_error") being called when ejected from a cog * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Fix `=None` being displayed in [`signature`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.Command.signature "discord.ext.commands.Command.signature") * \[[ext.commands](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/index.html#discord-ext-commands)\ \] Change lookup order for [`MemberConverter`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.MemberConverter "discord.ext.commands.MemberConverter") and [`UserConverter`](https://discordpy-self.readthedocs.io/en/v2.1.0/ext/commands/api.html#discord.ext.commands.UserConverter "discord.ext.commands.UserConverter") to prioritise usernames instead of nicknames ### Miscellaneous[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/whats_new.html#miscellaneous "Permalink to this headline") * Minimum version is now Python 3.10 * New dependency: `curl_cffi` * Update filesize limit constants * Additional documentation added for logging capabilities * Performance increases of constructing [`Permissions`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Permissions "discord.Permissions") using keyword arguments * Improve `__repr__` of [`SyncWebhook`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.SyncWebhook "discord.SyncWebhook") and [`Webhook`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Webhook "discord.Webhook") * Change internal thread names to be consistent * Use a fallback package for `audioop` to allow the library to work in Python 3.13 or newer * Remove `aiodns` from being used on Windows * Add zstd gateway compression to `speed` extras * This can be installed using `discord.py-self[speed]` * Add proxy support fetching from the CDN * Remove `/` from being safe from URI encoding when constructing paths internally * Sanitize invite argument before calling the invite info endpoint * Avoid returning in finally in specific places to prevent exception swallowing * Deprecate the `with_expiration` parameter in [`Client.fetch_invite()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.fetch_invite "discord.Client.fetch_invite") * Allow creating NSFW voice/stage channels * The [`Invite`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Invite "discord.Invite") is now returned when using [`Invite.delete()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Invite.delete "discord.Invite.delete") or [`Client.delete_invite()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.delete_invite "discord.Client.delete_invite") * Update PyNaCl minimum version dependency * `AppCommandType` is now `ApplicationCommandType` for consistency; the old name is still available as an alias * `AppCommandOptionType` is now `ApplicationCommandOptionType` for consistency; the old name is still available as an alias * \[BREAKING\] Remove all achievement support as the endpoints have been removed by Discord * \[BREAKING\] Updated CAPTCHA handler implementation * The old `CaptchaHandler` class has been removed * New interface is via the `captcha_handler` parameter in [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") , which accepts a [`CaptchaRequired`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.CaptchaRequired "discord.CaptchaRequired") class instance and the [`Client`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client "discord.Client") itself as parameters * You can also override [`Client.handle_captcha()`](https://discordpy-self.readthedocs.io/en/v2.1.0/api.html#discord.Client.handle_captcha "discord.Client.handle_captcha") in a subclass * \[BREAKING\] Swap all `exclude_*` parameters in fetch methods to `include_*` parameters for consistency v2.0.0[¶](https://discordpy-self.readthedocs.io/en/v2.1.0/whats_new.html#v2-0-0 "Permalink to this headline") -------------------------------------------------------------------------------------------------------------- This is considered the initial stable version. All previous versions were mostly a stepping stone to this one. The changes are too enormous to list here, so please check out the rest of the documentation. arrow\_upward to top --- # Setting Up Logging View Documentation For discord discord.ext.commands discord.ext.tasks search settings New in version 0.6.0. Setting Up Logging[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/logging.html#setting-up-logging "Permalink to this headline") ==================================================================================================================================== _discord.py-self_ logs errors and debug information via the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.11)") python module. In order to streamline this process, the library provides default configuration for the `discord` logger when using [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.run "discord.Client.run") . It is strongly recommended that the logging module is configured, as no errors or warnings will be output if it is not set up. The default logging configuration provided by the library will print to [`sys.stderr`](https://docs.python.org/3/library/sys.html#sys.stderr "(in Python v3.11)") using coloured output. You can configure it to send to a file instead by using one of the built-in [`logging.handlers`](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers "(in Python v3.11)") , such as [`logging.FileHandler`](https://docs.python.org/3/library/logging.handlers.html#logging.FileHandler "(in Python v3.11)") . This can be done by passing it through [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.run "discord.Client.run") : content\_copy import logging handler \= logging.FileHandler(filename\='discord.log', encoding\='utf-8', mode\='w') \# Assume client refers to a discord.Client subclass... client.run(token, log\_handler\=handler) You can also disable the library’s logging configuration completely by passing `None`: content\_copy client.run(token, log\_handler\=None) Likewise, configuring the log level to `logging.DEBUG` is also possible: content\_copy import logging handler \= logging.FileHandler(filename\='discord.log', encoding\='utf-8', mode\='w') \# Assume client refers to a discord.Client subclass... client.run(token, log\_handler\=handler, log\_level\=logging.DEBUG) This is recommended, especially at verbose levels such as `DEBUG`, as there are a lot of events logged and it would clog the stderr of your program. If you want to setup logging using the library provided configuration without using [`Client.run()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.run "discord.Client.run") , you can use [`discord.utils.setup_logging()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.utils.setup_logging "discord.utils.setup_logging") : content\_copy import discord discord.utils.setup\_logging() \# or, for example discord.utils.setup\_logging(level\=logging.INFO, root\=False) More advanced setups are possible with the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.11)") module. The example below configures a rotating file handler that outputs DEBUG output for everything the library outputs, except for HTTP requests: content\_copy import discord import logging import logging.handlers logger \= logging.getLogger('discord') logger.setLevel(logging.DEBUG) logging.getLogger('discord.http').setLevel(logging.INFO) handler \= logging.handlers.RotatingFileHandler( filename\='discord.log', encoding\='utf-8', maxBytes\=32 \* 1024 \* 1024, \# 32 MiB backupCount\=5, \# Rotate through 5 files ) dt\_fmt \= '%Y-%m-%d %H:%M:%S' formatter \= logging.Formatter('\[{asctime}\] \[{levelname:<8}\] {name}: {message}', dt\_fmt, style\='{') handler.setFormatter(formatter) logger.addHandler(handler) \# Assume client refers to a discord.Client subclass... \# Suppress the default configuration since we have our own client.run(token, log\_handler\=None) For more information, check the documentation and tutorial of the [`logging`](https://docs.python.org/3/library/logging.html#module-logging "(in Python v3.11)") module. Changed in version 2.0: The library now provides a default logging configuration. arrow\_upward to top --- # Quickstart View Documentation For discord discord.ext.commands discord.ext.tasks search settings Quickstart[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/quickstart.html#quickstart "Permalink to this headline") ======================================================================================================================= This page gives a brief introduction to the library. It assumes you have the library installed, if you don’t check the [Installing](https://discordpy-self.readthedocs.io/en/v2.0.0/intro.html#installing) portion. A Minimal Bot[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/quickstart.html#a-minimal-bot "Permalink to this headline") ----------------------------------------------------------------------------------------------------------------------------- Let’s make a bot that responds to a specific message and walk you through it. It looks something like this: content\_copy import discord client \= discord.Client() @client.event async def on\_ready(): print(f'We have logged in as {client.user}') @client.event async def on\_message(message): if message.author != client.user: return if message.content.startswith('$hello'): await message.channel.send('Hello!') client.run('your token here') Let’s name this file `example_bot.py`. Make sure not to name it `discord.py` as that’ll conflict with the library. There’s a lot going on here, so let’s walk you through it step by step. 1. The first line just imports the library, if this raises a [`ModuleNotFoundError`](https://docs.python.org/3/library/exceptions.html#ModuleNotFoundError "(in Python v3.11)") or [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError "(in Python v3.11)") then head on over to [Installing](https://discordpy-self.readthedocs.io/en/v2.0.0/intro.html#installing) section to properly install. 2. Next, we create an instance of a [`Client`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client "discord.Client") . This client is our connection to Discord. 3. We then use the [`Client.event()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.event "discord.Client.event") decorator to register an event. This library has many events. Since this library is asynchronous, we do things in a “callback” style manner. A callback is essentially a function that is called when something happens. In our case, the [`on_ready()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.on_ready "discord.on_ready") event is called when the bot has finished logging in and setting things up and the [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.on_message "discord.on_message") event is called when the bot has received a message. 4. Since the [`on_message()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.on_message "discord.on_message") event triggers for _every_ message received, we have to make sure that we ignore messages from ourselves. We do this by checking if the [`Message.author`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Message.author "discord.Message.author") is the same as the [`Client.user`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.user "discord.Client.user") . 5. Afterwards, we check if the [`Message.content`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Message.content "discord.Message.content") starts with `'$hello'`. If it does, then we send a message in the channel it was used in with `'Hello!'`. This is a basic way of handling commands, which can be later automated with the [discord.ext.commands – Bot commands framework](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/index.html) framework. 6. Finally, we run the bot with our login token. If you need help getting your token, look in the [Tokens](https://discordpy-self.readthedocs.io/en/v2.0.0/token.html) section. Now that we’ve made a bot, we have to _run_ the bot. Luckily, this is simple since this is just a Python script, we can run it directly. On Windows: content\_copy $ py \-3 example\_bot.py On other systems: content\_copy $ python3 example\_bot.py Now you can try playing around with your basic bot. arrow\_upward to top --- # Introduction View Documentation For discord discord.ext.commands discord.ext.tasks search settings Introduction[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/intro.html#introduction "Permalink to this headline") ====================================================================================================================== This is the documentation for discord.py-self, a library for Python to aid in creating bots running on user accounts that utilise the Discord API. Prerequisites[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/intro.html#prerequisites "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------ discord.py-self works with Python 3.8 or higher. Support for earlier versions of Python is not provided. Installing[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/intro.html#installing "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------ You can get the library directly from PyPI: content\_copy python3 \-m pip install \-U discord.py\-self If you are using Windows, then the following should be used instead: content\_copy py \-3 \-m pip install \-U discord.py\-self To get voice support, you should use `discord.py-self[voice]` instead of `discord.py`, e.g. content\_copy python3 \-m pip install \-U discord.py\-self\[voice\] On Linux environments, installing voice requires getting the following dependencies: * [libffi](https://github.com/libffi/libffi) * [libnacl](https://github.com/saltstack/libnacl) * [python3-dev](https://packages.debian.org/python3-dev) For a Debian-based system, the following command will get these dependencies: content\_copy $ apt install libffi-dev libnacl-dev python3-dev Remember to check your permissions! ### Virtual Environments[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/intro.html#virtual-environments "Permalink to this headline") Sometimes you want to keep libraries from polluting system installs or use a different version of libraries than the ones installed on the system. You might also not have permissions to install libraries system-wide. For this purpose, the standard library as of Python 3.3 comes with a concept called “Virtual Environment”s to help maintain these separate versions. A more in-depth tutorial is found on [Virtual Environments and Packages](https://docs.python.org/3/tutorial/venv.html "(in Python v3.11)") . However, for the quick and dirty: 1. Go to your project’s working directory: > content\_copy > > $ cd your-bot-source > $ python3 \-m venv bot-env 2. Activate the virtual environment: > content\_copy > > $ source bot-env/bin/activate > > On Windows you activate it with: > > content\_copy > > $ bot-env\\Scripts\\activate.bat 3. Use pip like usual: > content\_copy > > $ pip install \-U discord.py-self Congratulations. You now have a virtual environment all set up. Basic Concepts[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/intro.html#basic-concepts "Permalink to this headline") -------------------------------------------------------------------------------------------------------------------------- discord.py revolves around the concept of [events](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord-api-events) . An event is something you listen to and then respond to. For example, when a message happens, you will receive an event about it that you can respond to. A quick example to showcase how events work: content\_copy import discord class MyClient(discord.Client): async def on\_ready(self): print(f'Logged on as {self.user}!') async def on\_message(self, message): print(f'Message from {message.author}: {message.content}') client \= MyClient() client.run('token') arrow\_upward to top --- # Tokens View Documentation For discord discord.ext.commands discord.ext.tasks search settings Tokens[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/token.html#tokens "Permalink to this headline") ========================================================================================================== Tokens are how we authenticate with Discord. Regular (and bot) tokens have this format: | | | | | | --- | --- | --- | --- |Discord Token[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/token.html#id2 "Permalink to this table") | | MjQ1NTU5MDg3NTI0MjE2ODMy | DulyxA | brcD2xRAqjACTuMcGPwy4TWVQdg | | --- | --- | --- | --- | | **Decode** | [`base64.b64decode()`](https://docs.python.org/3/library/base64.html#base64.b64decode "(in Python v3.11)") | [`base64.b64decode()`](https://docs.python.org/3/library/base64.html#base64.b64decode "(in Python v3.11)")
+ 1293840000 | N/A | | **Output** | User ID | Unix TS | HMAC | MFA tokens, however, are just the HMAC prefixed with `mfa.`. How do I obtain mine?[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/token.html#how-do-i-obtain-mine "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------- To obtain your token from the Discord client, the easiest way is pasting this into the developer console (CTRL+SHIFT+I): content\_copy (webpackChunkdiscord\_app.push(\[\[''\],{},e\=>{m\=\[\];for(let c in e.c)m.push(e.c\[c\])}\]),m).find(m \=> m?.exports?.default?.getToken).exports.default.getToken() Or, you can do it manually: 1. Open developer tools (CTRL+SHIFT+I). 2. Click the Network tab. 3. Click the XHR tab. 4. Select a request and click the Headers tab. 5. Copy-paste the value in the Authorization header. arrow\_upward to top --- # discord.ext.tasks – asyncio.Task helpers View Documentation For discord discord.ext.commands discord.ext.tasks search settings `discord.ext.tasks` – asyncio.Task helpers[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord-ext-tasks-asyncio-task-helpers "Permalink to this headline") ======================================================================================================================================================================================== New in version 1.1.0. One of the most common operations when making a bot is having a loop run in the background at a specified interval. This pattern is very common but has a lot of things you need to look out for: * How do I handle [`asyncio.CancelledError`](https://docs.python.org/3/library/asyncio-exceptions.html#asyncio.CancelledError "(in Python v3.11)") ? * What do I do if the internet goes out? * What is the maximum number of seconds I can sleep anyway? The goal of this discord.py extension is to abstract all these worries away from you. Recipes[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#recipes "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------- A simple background task in a [`Cog`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") : content\_copy from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self): self.index \= 0 self.printer.start() def cog\_unload(self): self.printer.cancel() @tasks.loop(seconds\=5.0) async def printer(self): print(self.index) self.index += 1 Adding an exception to handle during reconnect: content\_copy import asyncpg from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.data \= \[\] self.batch\_update.add\_exception\_type(asyncpg.PostgresConnectionError) self.batch\_update.start() def cog\_unload(self): self.batch\_update.cancel() @tasks.loop(minutes\=5.0) async def batch\_update(self): async with self.bot.pool.acquire() as con: \# batch update here... pass Looping a certain amount of times before exiting: content\_copy from discord.ext import tasks import discord @tasks.loop(seconds\=5.0, count\=5) async def slow\_count(): print(slow\_count.current\_loop) @slow\_count.after\_loop async def after\_slow\_count(): print('done!') class MyClient(discord.Client): async def setup\_hook(self): slow\_count.start() Waiting until the bot is ready before the loop starts: content\_copy from discord.ext import tasks, commands class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.index \= 0 self.bot \= bot self.printer.start() def cog\_unload(self): self.printer.cancel() @tasks.loop(seconds\=5.0) async def printer(self): print(self.index) self.index += 1 @printer.before\_loop async def before\_printer(self): print('waiting...') await self.bot.wait\_until\_ready() Doing something during cancellation: content\_copy from discord.ext import tasks, commands import asyncio class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.\_batch \= \[\] self.lock \= asyncio.Lock() self.bulker.start() async def cog\_unload(self): self.bulker.cancel() async def do\_bulk(self): \# bulk insert data here ... @tasks.loop(seconds\=10.0) async def bulker(self): async with self.lock: await self.do\_bulk() @bulker.after\_loop async def on\_bulker\_cancel(self): if self.bulker.is\_being\_cancelled() and len(self.\_batch) != 0: \# if we're cancelled and we have some data left... \# let's insert it to our database await self.do\_bulk() Doing something at a specific time each day: content\_copy import datetime from discord.ext import commands, tasks utc \= datetime.timezone.utc \# If no tzinfo is given then UTC is assumed. time \= datetime.time(hour\=8, minute\=30, tzinfo\=utc) class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.my\_task.start() def cog\_unload(self): self.my\_task.cancel() @tasks.loop(time\=time) async def my\_task(self): print("My task is running!") Doing something at multiple specific times each day: content\_copy import datetime from discord.ext import commands, tasks utc \= datetime.timezone.utc \# If no tzinfo is given then UTC is assumed. times \= \[\ datetime.time(hour\=8, tzinfo\=utc),\ datetime.time(hour\=12, minute\=30, tzinfo\=utc),\ datetime.time(hour\=16, minute\=40, second\=30, tzinfo\=utc)\ \] class MyCog(commands.Cog): def \_\_init\_\_(self, bot): self.bot \= bot self.my\_task.start() def cog\_unload(self): self.my\_task.cancel() @tasks.loop(time\=times) async def my\_task(self): print("My task is running!") API Reference[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#api-reference "Permalink to this headline") ---------------------------------------------------------------------------------------------------------------------------------- _class_ discord.ext.tasks.Loop[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop "Permalink to this definition") Attributes * [current\_loop](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.current_loop) * [hours](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.hours) * [minutes](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.minutes) * [next\_iteration](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.next_iteration) * [seconds](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.seconds) * [time](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.time) Methods * async[\_\_call\_\_](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.__call__) * def[add\_exception\_type](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.add_exception_type) * @[after\_loop](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.after_loop) * @[before\_loop](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop) * def[cancel](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.cancel) * def[change\_interval](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.change_interval) * def[clear\_exception\_types](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types) * @[error](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.error) * def[failed](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.failed) * def[get\_task](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.get_task) * def[is\_being\_cancelled](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled) * def[is\_running](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_running) * def[remove\_exception\_type](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.remove_exception_type) * def[restart](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.restart) * def[start](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.start) * def[stop](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.stop) A background task helper that abstracts the loop and reconnection logic for you. The main interface to create this is through [`loop()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.loop "discord.ext.tasks.loop") . @after\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.after_loop "Permalink to this definition") A decorator that registers a coroutine to be called after the loop finishes running. The coroutine must take no arguments (except `self` in a class context). Note This coroutine is called even during cancellation. If it is desirable to tell apart whether something was cancelled or not, check to see whether [`is_being_cancelled()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled "discord.ext.tasks.Loop.is_being_cancelled") is `True` or not. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.11)") ) – The coroutine to register after the loop finishes. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.11)") – The function was not a coroutine. @before\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop "Permalink to this definition") A decorator that registers a coroutine to be called before the loop starts running. This is useful if you want to wait for some bot state before the loop starts, such as [`discord.Client.wait_until_ready()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.wait_until_ready "discord.Client.wait_until_ready") . The coroutine must take no arguments (except `self` in a class context). Changed in version 2.0: Calling [`stop()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.stop "discord.ext.tasks.Loop.stop") in this coroutine will stop the initial iteration from running. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.11)") ) – The coroutine to register before the loop runs. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.11)") – The function was not a coroutine. @error[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.error "Permalink to this definition") A decorator that registers a coroutine to be called if the task encounters an unhandled exception. The coroutine must take only one argument the exception raised (except `self` in a class context). By default this logs to the library logger however it could be overridden to have a different implementation. New in version 1.4. Changed in version 2.0: Instead of writing to `sys.stderr`, the library’s logger is used. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.11)") ) – The coroutine to register in the event of an unhandled exception. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.11)") – The function was not a coroutine. _property_ seconds[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.seconds "Permalink to this definition") Read-only value for the number of seconds between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)")\ \] _property_ minutes[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.minutes "Permalink to this definition") Read-only value for the number of minutes between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)")\ \] _property_ hours[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.hours "Permalink to this definition") Read-only value for the number of hours between each iteration. `None` if an explicit `time` value was passed instead. New in version 2.0. Type Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)")\ \] _property_ time[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.time "Permalink to this definition") Read-only list for the exact times this loop runs at. `None` if relative times were passed instead. New in version 2.0. Type Optional\[List\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.11)")\ \]\] _property_ current\_loop[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.current_loop "Permalink to this definition") The current iteration of the loop. Type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.11)") _property_ next\_iteration[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.next_iteration "Permalink to this definition") When the next iteration of the loop will occur. New in version 1.3. Type Optional\[[`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.11)")\ \] _await_ \_\_call\_\_(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.__call__ "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Calls the internal callback that the task holds. New in version 1.6. Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. start(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.start "Permalink to this definition") Starts the internal task in the event loop. Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. Raises [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.11)") – A task has already been launched and is running. Returns The task that has been created. Return type [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.11)") stop()[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.stop "Permalink to this definition") Gracefully stops the task from running. Unlike [`cancel()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "discord.ext.tasks.Loop.cancel") , this allows the task to finish its current iteration before gracefully exiting. Note If the internal function raises an error that can be handled before finishing then it will retry until it succeeds. If this is undesirable, either remove the error handling before stopping via [`clear_exception_types()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types "discord.ext.tasks.Loop.clear_exception_types") or use [`cancel()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "discord.ext.tasks.Loop.cancel") instead. Changed in version 2.0: Calling this method in [`before_loop()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.before_loop "discord.ext.tasks.Loop.before_loop") will stop the first iteration from running. New in version 1.2. cancel()[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.cancel "Permalink to this definition") Cancels the internal task, if it is running. restart(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.restart "Permalink to this definition") A convenience method to restart the internal task. Note Due to the way this function works, the task is not returned like [`start()`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.start "discord.ext.tasks.Loop.start") . Parameters * **\*args** – The arguments to use. * **\*\*kwargs** – The keyword arguments to use. add\_exception\_type(_\*exceptions_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.add_exception_type "Permalink to this definition") Adds exception types to be handled during the reconnect logic. By default the exception types handled are those handled by [`discord.Client.connect()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.connect "discord.Client.connect") , which includes a lot of internet disconnection errors. This function is useful if you’re interacting with a 3rd party library that raises its own set of exceptions. Parameters **\*exceptions** (Type\[[`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.11)")\ \]) – An argument list of exception classes to handle. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.11)") – An exception passed is either not a class or not inherited from [`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.11)") . clear\_exception\_types()[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.clear_exception_types "Permalink to this definition") Removes all exception types that are handled. Note This operation obviously cannot be undone! remove\_exception\_type(_\*exceptions_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.remove_exception_type "Permalink to this definition") Removes exception types from being handled during the reconnect logic. Parameters **\*exceptions** (Type\[[`BaseException`](https://docs.python.org/3/library/exceptions.html#BaseException "(in Python v3.11)")\ \]) – An argument list of exception classes to handle. Returns Whether all exceptions were successfully removed. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.11)") get\_task()[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.get_task "Permalink to this definition") Optional\[[`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task "(in Python v3.11)")\ \]: Fetches the internal task or `None` if there isn’t one running. is\_being\_cancelled()[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_being_cancelled "Permalink to this definition") Whether the task is being cancelled. failed()[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.failed "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.11)") : Whether the internal task has failed. New in version 1.2. is\_running()[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.is_running "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.11)") : Check if the task is currently running. New in version 1.4. change\_interval(_\*_, _seconds\=0_, _minutes\=0_, _hours\=0_, _time\=..._)[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop.change_interval "Permalink to this definition") Changes the interval for the sleep time. New in version 1.2. Parameters * **seconds** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)") ) – The number of seconds between every iteration. * **minutes** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)") ) – The number of minutes between every iteration. * **hours** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)") ) – The number of hours between every iteration. * **time** (Union\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.11)")\ , Sequence\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.11)")\ \]\]) – The exact times to run this loop at. Either a non-empty list or a single value of [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.11)") should be passed. This cannot be used in conjunction with the relative time parameters. New in version 2.0. Note Duplicate times will be ignored, and only run once. Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.11)") – An invalid value was given. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.11)") – An invalid value for the `time` parameter was passed, or the `time` parameter was passed in conjunction with relative time parameters. @discord.ext.tasks.loop(_\*_, _seconds\=..._, _minutes\=..._, _hours\=..._, _time\=..._, _count\=None_, _reconnect\=True_)[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.loop "Permalink to this definition") A decorator that schedules a task in the background for you with optional reconnect logic. The decorator returns a [`Loop`](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/tasks/index.html#discord.ext.tasks.Loop "discord.ext.tasks.Loop") . Parameters * **seconds** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)") ) – The number of seconds between every iteration. * **minutes** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)") ) – The number of minutes between every iteration. * **hours** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.11)") ) – The number of hours between every iteration. * **time** (Union\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.11)")\ , Sequence\[[`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.11)")\ \]\]) – The exact times to run this loop at. Either a non-empty list or a single value of [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time "(in Python v3.11)") should be passed. Timezones are supported. If no timezone is given for the times, it is assumed to represent UTC time. This cannot be used in conjunction with the relative time parameters. Note Duplicate times will be ignored, and only run once. New in version 2.0. * **count** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.11)")\ \]) – The number of loops to do, `None` if it should be an infinite loop. * **reconnect** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.11)") ) – Whether to handle errors and restart the task using an exponential back-off algorithm similar to the one used in [`discord.Client.connect()`](https://discordpy-self.readthedocs.io/en/v2.0.0/api.html#discord.Client.connect "discord.Client.connect") . Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.11)") – An invalid value was given. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.11)") – The function was not a coroutine, an invalid value for the `time` parameter was passed, or `time` parameter was passed in conjunction with relative time parameters. arrow\_upward to top --- # discord.ext.commands – Bot commands framework View Documentation For discord discord.ext.commands discord.ext.tasks search settings `discord.ext.commands` – Bot commands framework[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/index.html#discord-ext-commands-bot-commands-framework "Permalink to this headline") ===================================================================================================================================================================================================== `discord.py` offers a lower level aspect on interacting with Discord. Often times, the library is used for the creation of bots. However this task can be daunting and confusing to get correctly the first time. Many times there comes a repetition in creating a bot command framework that is extensible, flexible, and powerful. For this reason, `discord.py` comes with an extension library that handles this for you. * [Commands](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/commands.html) * [Parameters](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/commands.html#parameters) * [Invocation Context](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/commands.html#invocation-context) * [Converters](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/commands.html#converters) * [Parameter Metadata](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/commands.html#parameter-metadata) * [Error Handling](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/commands.html#error-handling) * [Checks](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/commands.html#checks) * [Cogs](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/cogs.html) * [Quick Example](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/cogs.html#quick-example) * [Cog Registration](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/cogs.html#cog-registration) * [Using Cogs](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/cogs.html#using-cogs) * [Special Methods](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/cogs.html#special-methods) * [Meta Options](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/cogs.html#meta-options) * [Inspection](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/cogs.html#inspection) * [Extensions](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/extensions.html) * [Primer](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/extensions.html#primer) * [Reloading](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/extensions.html#reloading) * [Cleaning Up](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/extensions.html#cleaning-up) * [API Reference](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html) * [Bots](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#bots) * [Prefix Helpers](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#prefix-helpers) * [Event Reference](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#event-reference) * [Commands](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#commands) * [Cogs](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#cogs) * [Help Commands](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#help-commands) * [Enums](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#enums) * [Checks](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#checks) * [Cooldown](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#cooldown) * [Context](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#context) * [Converters](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#converters) * [Defaults](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#defaults) * [Exceptions](https://discordpy-self.readthedocs.io/en/v2.0.0/ext/commands/api.html#exceptions) arrow\_upward to top --- # Search View Documentation For discord discord.ext.commands discord.ext.tasks search settings Search ====== Searching for multiple words only shows matches that contain all words. arrow\_upward to top --- # Changelog View Documentation For discord discord.ext.commands discord.ext.tasks search settings Changelog[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/whats_new.html#changelog "Permalink to this headline") ==================================================================================================================== This page keeps a detailed human friendly rendering of what’s new and changed in specific versions. v2.0[¶](https://discordpy-self.readthedocs.io/en/v2.0.0/whats_new.html#v2-0 "Permalink to this headline") ---------------------------------------------------------------------------------------------------------- This is considered the initial stable version. All previous versions were mostly a stepping stone to this one. The changes are too enormous to list here, so please check out the rest of the documentation. arrow\_upward to top --- # API Reference View Documentation For discord discord.ext.commands discord.ext.tasks search settings API Reference[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#api-reference "Permalink to this headline") =================================================================================================================================== The following section outlines the API of discord.py’s command extension module. Bots[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#bots "Permalink to this headline") ----------------------------------------------------------------------------------------------------------------- ### Bot[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#bot "Permalink to this headline") _class_ discord.ext.commands.Bot(_command\_prefix_, _help\_command=_, _description=None_, _\*\*options_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot "Permalink to this definition") Attributes * [activities](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.activities) * [activity](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.activity) * [allowed\_mentions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.allowed_mentions) * [blocked](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.blocked) * [cached\_messages](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.cached_messages) * [case\_insensitive](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.case_insensitive) * [client\_activities](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.client_activities) * [client\_status](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.client_status) * [cogs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.cogs) * [command\_prefix](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.command_prefix) * [commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.commands) * [connections](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.connections) * [country\_code](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.country_code) * [description](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.description) * [disclose](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.disclose) * [emojis](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.emojis) * [experiments](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.experiments) * [extensions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.extensions) * [friend\_suggestion\_count](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.friend_suggestion_count) * [friends](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.friends) * [guild\_experiments](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.guild_experiments) * [guilds](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.guilds) * [help\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.help_command) * [idle\_since](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.idle_since) * [initial\_activities](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.initial_activities) * [initial\_activity](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.initial_activity) * [initial\_status](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.initial_status) * [latency](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.latency) * [notification\_settings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.notification_settings) * [owner\_id](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.owner_id) * [owner\_ids](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.owner_ids) * [pending\_payments](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.pending_payments) * [preferred\_rtc\_regions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.preferred_rtc_regions) * [private\_channels](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.private_channels) * [raw\_status](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.raw_status) * [read\_states](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.read_states) * [relationships](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.relationships) * [required\_action](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.required_action) * [sessions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.sessions) * [settings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.settings) * [status](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.status) * [stickers](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.stickers) * [strip\_after\_prefix](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.strip_after_prefix) * [tracking\_settings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.tracking_settings) * [tutorial](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.tutorial) * [user](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.user) * [users](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.users) * [voice\_client](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.voice_client) * [voice\_clients](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.voice_clients) Methods * async[accept\_invite](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.accept_invite) * async[activity\_statistics](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.activity_statistics) * def[add\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_check) * async[add\_cog](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_cog) * def[add\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_command) * def[add\_listener](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_listener) * @[after\_invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.after_invoke) * async[applications](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.applications) * async[authorize\_connection](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.authorize_connection) * async[before\_identify\_hook](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.before_identify_hook) * @[before\_invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.before_invoke) * async[bulk\_ack](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.bulk_ack) * async[change\_presence](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.change_presence) * async[change\_voice\_state](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.change_voice_state) * async[channel\_affinities](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.channel_affinities) * @[check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check) * @[check\_once](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check_once) * async[check\_pomelo\_username](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check_pomelo_username) * async[checkout\_recovery](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.checkout_recovery) * def[clear](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.clear) * async[close](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.close) * @[command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.command) * async[connect](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.connect) * async[create\_application](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_application) * async[create\_authorization](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_authorization) * async[create\_connection](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_connection) * async[create\_dm](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_dm) * async[create\_group](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_group) * async[create\_guild](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_guild) * async[create\_invite](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_invite) * async[create\_payment\_source](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_payment_source) * async[create\_subscription](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_subscription) * async[create\_team](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_team) * async[delete\_invite](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.delete_invite) * async[delete\_recent\_mention](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.delete_recent_mention) * async[detectable\_applications](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.detectable_applications) * async[edit\_legacy\_settings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.edit_legacy_settings) * async[email\_settings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.email_settings) * async[entitlements](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.entitlements) * @[event](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.event) * async[fetch\_application](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_application) * async[fetch\_authorization](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_authorization) * async[fetch\_channel](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_channel) * async[fetch\_company](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_company) * async[fetch\_connections](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_connections) * async[fetch\_country\_code](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_country_code) * async[fetch\_entitlements](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_entitlements) * async[fetch\_eula](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_eula) * async[fetch\_experiments](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_experiments) * async[fetch\_gift](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_gift) * async[fetch\_guild](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_guild) * async[fetch\_guild\_preview](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_guild_preview) * async[fetch\_guilds](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_guilds) * async[fetch\_invite](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_invite) * async[fetch\_live\_build\_ids](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_live_build_ids) * async[fetch\_location\_info](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_location_info) * async[fetch\_note](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_note) * async[fetch\_notes](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_notes) * async[fetch\_partial\_application](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_partial_application) * async[fetch\_payment](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_payment) * async[fetch\_payment\_source](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_payment_source) * async[fetch\_preferred\_rtc\_regions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_preferred_rtc_regions) * async[fetch\_price\_tier](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_price_tier) * async[fetch\_primary\_store\_listing](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_primary_store_listing) * async[fetch\_primary\_store\_listings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_primary_store_listings) * async[fetch\_private\_channels](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_private_channels) * async[fetch\_public\_application](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_public_application) * async[fetch\_public\_applications](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_public_applications) * async[fetch\_published\_store\_listing](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_published_store_listing) * async[fetch\_published\_store\_listings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_published_store_listings) * async[fetch\_relationships](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_relationships) * async[fetch\_settings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_settings) * async[fetch\_sku](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sku) * async[fetch\_sku\_subscription\_plans](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sku_subscription_plans) * async[fetch\_skus\_subscription\_plans](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_skus_subscription_plans) * async[fetch\_stage\_instance](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_stage_instance) * async[fetch\_sticker](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sticker) * async[fetch\_sticker\_pack](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sticker_pack) * async[fetch\_store\_listing](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_store_listing) * async[fetch\_subscription](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_subscription) * async[fetch\_team](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_team) * async[fetch\_template](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_template) * async[fetch\_tracking\_settings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_tracking_settings) * async[fetch\_user](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_user) * async[fetch\_user\_profile](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_user_profile) * async[fetch\_webhook](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_webhook) * async[fetch\_widget](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_widget) * async[friend\_suggestions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.friend_suggestions) * def[get\_all\_channels](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_all_channels) * def[get\_all\_members](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_all_members) * def[get\_channel](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_channel) * def[get\_cog](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_cog) * def[get\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_command) * async[get\_context](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_context) * def[get\_emoji](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_emoji) * def[get\_experiment](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_experiment) * def[get\_guild](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_guild) * def[get\_partial\_messageable](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_partial_messageable) * async[get\_prefix](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_prefix) * def[get\_relationship](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_relationship) * def[get\_stage\_instance](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_stage_instance) * def[get\_sticker](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_sticker) * def[get\_user](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_user) * async[giftable\_entitlements](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.giftable_entitlements) * async[global\_activity\_statistics](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.global_activity_statistics) * @[group](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.group) * async[guild\_affinities](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.guild_affinities) * async[handle\_captcha](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.handle_captcha) * async[invites](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invites) * async[invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invoke) * def[is\_afk](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_afk) * def[is\_closed](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_closed) * def[is\_on\_mobile](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_on_mobile) * async[is\_owner](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_owner) * def[is\_ready](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_ready) * def[is\_ws\_ratelimited](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_ws_ratelimited) * async[join\_active\_developer\_program](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.join_active_developer_program) * async[join\_guild](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.join_guild) * async[join\_hub](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.join_hub) * async[join\_hub\_waitlist](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.join_hub_waitlist) * async[leave\_active\_developer\_program](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.leave_active_developer_program) * async[leave\_guild](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.leave_guild) * async[legacy\_settings](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.legacy_settings) * async[library](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.library) * @[listen](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.listen) * async[load\_extension](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.load_extension) * async[login](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.login) * async[lookup\_hubs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.lookup_hubs) * async[oauth2\_tokens](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.oauth2_tokens) * async[on\_command\_error](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.on_command_error) * async[on\_error](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.on_error) * async[payment\_sources](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.payment_sources) * async for[payments](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.payments) * async[pomelo\_suggestion](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.pomelo_suggestion) * async[premium\_affinities](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_affinities) * async[premium\_entitlements](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_entitlements) * async[premium\_guild\_subscription\_cooldown](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_guild_subscription_cooldown) * async[premium\_guild\_subscription\_slots](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_guild_subscription_slots) * async[premium\_guild\_subscriptions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_guild_subscriptions) * async[premium\_subscription\_plans](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_subscription_plans) * async[premium\_usage](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_usage) * async[preview\_subscription](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.preview_subscription) * async[price\_tiers](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.price_tiers) * async[pricing\_promotion](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.pricing_promotion) * async[process\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.process_commands) * async[promotions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.promotions) * async[proxy\_external\_application\_assets](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.proxy_external_application_assets) * async[recent\_avatars](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.recent_avatars) * async for[recent\_mentions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.recent_mentions) * async[reload\_extension](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.reload_extension) * def[remove\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.remove_check) * async[remove\_cog](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.remove_cog) * def[remove\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.remove_command) * def[remove\_listener](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.remove_listener) * async[report\_unverified\_application](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.report_unverified_application) * async[revoke\_invites](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.revoke_invites) * def[run](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.run) * async[search\_companies](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.search_companies) * async[send\_friend\_request](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.send_friend_request) * async[setup\_hook](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.setup_hook) * async[start](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.start) * async[sticker\_packs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.sticker_packs) * async[subscriptions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.subscriptions) * async[teams](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.teams) * async[trial\_offer](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.trial_offer) * async[unload\_extension](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.unload_extension) * async[user\_affinities](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.user_affinities) * async[user\_offer](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.user_offer) * async[wait\_for](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.wait_for) * async[wait\_until\_ready](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.wait_until_ready) * def[walk\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.walk_commands) Represents a Discord bot. This class is a subclass of [`discord.Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") and as a result anything that you can do with a [`discord.Client`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Client "discord.Client") you can do with this bot. This class also subclasses [`GroupMixin`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin "discord.ext.commands.GroupMixin") to provide the functionality to manage commands. async with x Asynchronously initialises the bot and automatically cleans up. New in version 2.0. command\_prefix[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.command_prefix "Permalink to this definition") The command prefix is what the message content must contain initially to have a command invoked. This prefix could either be a string to indicate what the prefix should be, or a callable that takes in the bot as its first parameter and [`discord.Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") as its second parameter and returns the prefix. This is to facilitate “dynamic” command prefixes. This callable can be either a regular function or a coroutine. An empty string as the prefix always matches, enabling prefix-less command invocation. While this may be useful in DMs it should be avoided in servers, as it’s likely to cause performance issues and unintended command invocations. The command prefix could also be an iterable of strings indicating that multiple checks for the prefix should be used and the first one to match will be the invocation prefix. You can get this prefix via [`Context.prefix`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context.prefix "discord.ext.commands.Context.prefix") . Note When passing multiple prefixes be careful to not pass a prefix that matches a longer prefix occurring later in the sequence. For example, if the command prefix is `('!', '!?')` the `'!?'` prefix will never be matched to any message as the previous one matches messages starting with `!?`. This is especially important when passing an empty string, it should always be last as no prefix after it will be matched. case\_insensitive[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.case_insensitive "Permalink to this definition") Whether the commands should be case insensitive. Defaults to `False`. This attribute does not carry over to groups. You must set it to every group if you require group commands to be case insensitive as well. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") description[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.description "Permalink to this definition") The content prefixed into the default help message. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") help\_command[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.help_command "Permalink to this definition") The help command implementation to use. This can be dynamically set at runtime. To remove the help command pass `None`. For more information on implementing a help command, see [Help Commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#ext-commands-help-command) . Type Optional\[[`HelpCommand`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand "discord.ext.commands.HelpCommand")\ \] owner\_id[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.owner_id "Permalink to this definition") The user ID that owns the bot. If this is not set and is then queried via [`is_owner()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_owner "discord.ext.commands.Bot.is_owner") then it will error. Type Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \] owner\_ids[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.owner_ids "Permalink to this definition") The user IDs that owns the bot. This is similar to [`owner_id`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.owner_id "discord.ext.commands.Bot.owner_id") . If this is not set and and is then queried via [`is_owner()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_owner "discord.ext.commands.Bot.is_owner") then it will error. For performance reasons it is recommended to use a [`set`](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.14)") for the collection. You cannot set both `owner_id` and `owner_ids`. New in version 1.3. Type Optional\[Collection\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]\] strip\_after\_prefix[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.strip_after_prefix "Permalink to this definition") Whether to strip whitespace characters after encountering the command prefix. This allows for `!   hello` and `!hello` to both work if the `command_prefix` is set to `!`. Defaults to `False`. New in version 1.7. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") @after\_invoke[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.after_invoke "Permalink to this definition") A decorator that registers a coroutine as a post-invoke hook. A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required. This post-invoke hook takes a sole parameter, a [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . Note Similar to [`before_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.before_invoke "discord.ext.commands.Bot.before_invoke") , this is not called unless checks and argument parsing procedures succeed. This hook is, however, **always** called regardless of the internal command callback raising an error (i.e. [`CommandInvokeError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandInvokeError "discord.ext.commands.CommandInvokeError") ). This makes it ideal for clean-up scenarios. Changed in version 2.0: `coro` parameter is now positional-only. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register as the post-invoke hook. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. @before\_invoke[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.before_invoke "Permalink to this definition") A decorator that registers a coroutine as a pre-invoke hook. A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required. This pre-invoke hook takes a sole parameter, a [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . Note The [`before_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.before_invoke "discord.ext.commands.Bot.before_invoke") and [`after_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.after_invoke "discord.ext.commands.Bot.after_invoke") hooks are only called if all checks and argument parsing procedures pass without error. If any check or argument parsing procedures fail then the hooks are not called. Changed in version 2.0: `coro` parameter is now positional-only. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register as the pre-invoke hook. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. @check[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check "Permalink to this definition") A decorator that adds a global check to the bot. A global check is similar to a [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") that is applied on a per command basis except it is run before any command checks have been verified and applies to every command the bot has. Note This function can either be a regular function or a coroutine. Similar to a command [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") , this takes a single parameter of type [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") and can only raise exceptions inherited from [`CommandError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") . Example content\_copy @bot.check def check\_commands(ctx): return ctx.command.qualified\_name in allowed\_commands Changed in version 2.0: `func` parameter is now positional-only. @check\_once[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check_once "Permalink to this definition") A decorator that adds a “call once” global check to the bot. Unlike regular global checks, this one is called only once per [`invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invoke "discord.ext.commands.Bot.invoke") call. Regular global checks are called whenever a command is called or [`Command.can_run()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.can_run "discord.ext.commands.Command.can_run") is called. This type of check bypasses that and ensures that it’s called only once, even inside the default help command. Note When using this function the [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") sent to a group subcommand may only parse the parent command and not the subcommands due to it being invoked once per [`Bot.invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invoke "discord.ext.commands.Bot.invoke") call. Note This function can either be a regular function or a coroutine. Similar to a command [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") , this takes a single parameter of type [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") and can only raise exceptions inherited from [`CommandError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") . Example content\_copy @bot.check\_once def whitelist(ctx): return ctx.message.author.id in my\_whitelist Changed in version 2.0: `func` parameter is now positional-only. @command(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.command "Permalink to this definition") A shortcut decorator that invokes [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.command "discord.ext.commands.command") and adds it to the internal command list via [`add_command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.add_command "discord.ext.commands.GroupMixin.add_command") . Returns A decorator that converts the provided method into a Command, adds it to the bot, then returns it. Return type Callable\[…, [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] @event[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.event "Permalink to this definition") A decorator that registers an event to listen to. You can find more info about the events on the [documentation below](https://discordpy-self.readthedocs.io/en/latest/api.html#discord-api-events) . The events must be a [coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") , if not, [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") is raised. Example content\_copy @client.event async def on\_ready(): print('Ready!') Changed in version 2.0: `coro` parameter is now positional-only. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. @group(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.group "Permalink to this definition") A shortcut decorator that invokes [`group()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.group "discord.ext.commands.group") and adds it to the internal command list via [`add_command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.add_command "discord.ext.commands.GroupMixin.add_command") . Returns A decorator that converts the provided method into a Group, adds it to the bot, then returns it. Return type Callable\[…, [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] @listen(_name\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.listen "Permalink to this definition") A decorator that registers another function as an external event listener. Basically this allows you to listen to multiple events from different places e.g. such as [`on_ready()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_ready "discord.on_ready") The functions being listened to must be a [coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") . Example content\_copy @bot.listen() async def on\_message(message): print('one') \# in some other file... @bot.listen('on\_message') async def my\_message(message): print('two') Would print one and two in an unspecified order. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function being listened to is not a coroutine. _await_ accept\_invite(_url_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.accept_invite "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Uses an invite. Either joins a guild, joins a group DM, or adds a friend. New in version 2.0. Parameters **url** (Union\[[`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite")\ , [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The Discord invite ID, URL (must be a discord.gg URL), or [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") . Raises * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Using the invite failed. * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – Attempted to accept a guest invite without a session. Returns The accepted invite. Return type [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") _property_ activities[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.activities "Permalink to this definition") Returns the activities the client is currently doing. New in version 2.0. Note Due to a Discord API limitation, this may be `None` if the user is listening to a song on Spotify with a title longer than 128 characters. See [GH-1738](https://github.com/dolfies/discord.py-self/issues/1738) for more information. Type Tuple\[[`BaseActivity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.BaseActivity "discord.BaseActivity")\ , …\] _property_ activity[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.activity "Permalink to this definition") Returns the primary activity the client is currently doing. Could be `None` if no activity is being done. New in version 2.0. Note Due to a Discord API limitation, this may be `None` if the user is listening to a song on Spotify with a title longer than 128 characters. See [GH-1738](https://github.com/dolfies/discord.py-self/issues/1738) for more information. Note The client may have multiple activities, these can be accessed under [`activities`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.activities "discord.ext.commands.Bot.activities") . Type Optional\[[`BaseActivity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.BaseActivity "discord.BaseActivity")\ \] _await_ activity\_statistics()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.activity_statistics "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the available activity usage statistics for the games you play. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the statistics failed. Returns The activity statistics. Return type List\[[`ApplicationActivityStatistics`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ApplicationActivityStatistics "discord.ApplicationActivityStatistics")\ \] add\_check(_func_, _/_, _\*_, _call\_once\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_check "Permalink to this definition") Adds a global check to the bot. This is the non-decorator interface to [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check "discord.ext.commands.Bot.check") and [`check_once()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check_once "discord.ext.commands.Bot.check_once") . Changed in version 2.0: `func` parameter is now positional-only. Parameters * **func** – The function that was used as a global check. * **call\_once** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – If the function should only be called once per [`invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invoke "discord.ext.commands.Bot.invoke") call. _await_ add\_cog(_cog_, _/_, _\*_, _override\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_cog "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Adds a “cog” to the bot. A cog is a class that has its own event listeners and commands. Note Exceptions raised inside a [`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") ’s [`cog_load()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_load "discord.ext.commands.Cog.cog_load") method will be propagated to the caller. Changed in version 2.0: [`ClientException`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientException "discord.ClientException") is raised when a cog with the same name is already loaded. Changed in version 2.0: `cog` parameter is now positional-only. Changed in version 2.0: This method is now a [coroutine](https://docs.python.org/3/glossary.html#term-coroutine "(in Python v3.14)") . Parameters * **cog** ([`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") ) – The cog to register to the bot. * **override** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – If a previously loaded cog with the same name should be ejected instead of raising an error. New in version 2.0. Raises * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The cog does not inherit from [`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") . * [**CommandError**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") – An error happened during loading. * [**ClientException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientException "discord.ClientException") – A cog with the same name is already loaded. add\_command(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_command "Permalink to this definition") Adds a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") into the internal list of commands. This is usually not called, instead the [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.command "discord.ext.commands.GroupMixin.command") or [`group()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.group "discord.ext.commands.GroupMixin.group") shortcut decorators are used instead. Changed in version 1.4: Raise [`CommandRegistrationError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandRegistrationError "discord.ext.commands.CommandRegistrationError") instead of generic [`ClientException`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientException "discord.ClientException") Changed in version 2.0: `command` parameter is now positional-only. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to add. Raises * [**CommandRegistrationError**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandRegistrationError "discord.ext.commands.CommandRegistrationError") – If the command or its alias is already registered by different command. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – If the command passed is not a subclass of [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") . add\_listener(_func_, _/_, _name\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_listener "Permalink to this definition") The non decorator alternative to [`listen()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.listen "discord.ext.commands.Bot.listen") . Changed in version 2.0: `func` parameter is now positional-only. Parameters * **func** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The function to call. * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the event to listen for. Defaults to `func.__name__`. Example content\_copy async def on\_ready(): pass async def my\_message(message): pass bot.add\_listener(on\_ready) bot.add\_listener(my\_message, 'on\_message') _property_ allowed\_mentions[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.allowed_mentions "Permalink to this definition") The allowed mention configuration. New in version 1.4. Type Optional\[[`AllowedMentions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.AllowedMentions "discord.AllowedMentions")\ \] _await_ applications(_\*_, _with\_team\_applications\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.applications "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all applications owned by you. New in version 2.0. Parameters **with\_team\_applications** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include applications owned by teams you’re a part of. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the applications failed. Returns The applications you own. Return type List\[[`Application`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Application "discord.Application")\ \] _await_ authorize\_connection(_type_, _two\_way\_link\_type\=None_, _two\_way\_user\_code\=None_, _continuation\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.authorize_connection "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a URL to authorize a connection with a third-party service. New in version 2.0. Parameters * **type** ([`ConnectionType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ConnectionType "discord.ConnectionType") ) – The type of connection to authorize. * **two\_way\_link\_type** (Optional\[[`ClientType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientType "discord.ClientType")\ \]) – The type of two-way link to use, if any. * **two\_way\_user\_code** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The device code to use for two-way linking, if any. * **continuation** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether this is a continuation of a previous authorization. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Authorizing the connection failed. Returns The URL to redirect the user to. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _await_ before\_identify\_hook(_\*_, _initial\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.before_identify_hook "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A hook that is called before IDENTIFYing a session. This is useful if you wish to have more control over the synchronization of multiple IDENTIFYing clients. The default implementation does nothing. New in version 1.4. Parameters **initial** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether this IDENTIFY is the first initial IDENTIFY. _property_ blocked[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.blocked "Permalink to this definition") Returns all the users that the connected client has blocked. New in version 2.0. Type List\[[`Relationship`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Relationship "discord.Relationship")\ \] _await_ bulk\_ack(_acks_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.bulk_ack "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Updates multiple read states’ [`ReadState.last_acked_id`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ReadState.last_acked_id "discord.ReadState.last_acked_id") in bulk. New in version 2.1. Parameters **acks** (Dict\[[`ReadState`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ReadState "discord.ReadState")\ , [`abc.Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake")\ \]) – A mapping of read states to the last acknowledged entity ID (e.g. message ID). Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Updating the read states failed. _property_ cached\_messages[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.cached_messages "Permalink to this definition") Read-only list of messages the connected client has cached. New in version 1.1. Type Sequence\[[`Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message")\ \] _await_ change\_presence(_\*_, _activity\=..._, _activities\=..._, _status\=..._, _afk\=..._, _idle\_since\=..._, _edit\_settings\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.change_presence "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Changes the client’s presence. Changed in version 2.1: The default value for parameters is now the current value. `None` is no longer a valid value for most; you must explicitly set it to the default value if you want to reset it. Changed in version 2.0: Edits are no longer in place. Added option to update settings. Changed in version 2.0: This function will now raise [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") instead of `InvalidArgument`. Example content\_copy game \= discord.Game("with the API") await client.change\_presence(status\=discord.Status.idle, activity\=game) Parameters * **activity** (Optional\[[`BaseActivity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.BaseActivity "discord.BaseActivity")\ \]) – The activity being done. `None` if no activity is done. * **activities** (List\[[`BaseActivity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.BaseActivity "discord.BaseActivity")\ \]) – A list of the activities being done. Cannot be sent with `activity`. New in version 2.0. * **status** ([`Status`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Status "discord.Status") ) – Indicates what status to change to. * **afk** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Indicates if you are going AFK. This allows the Discord client to know how to handle push notifications better for you in case you are away from your keyboard. * **idle\_since** (Optional\[[`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.14)")\ \]) – When the client went idle. This indicates that you are truly idle and not just lying. * **edit\_settings** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to update user settings with the new status and/or custom activity. This will broadcast the change and cause all connected (official) clients to change presence as well. This should be set to `False` for idle changes. Required for setting/editing `expires_at` for custom activities. It’s not recommended to change this, as setting it to `False` can cause undefined behavior. Raises * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The `activity` parameter is not the proper type. Both `activity` and `activities` were passed. * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – More than one custom activity was passed. _await_ change\_voice\_state(_\*_, _channel_, _self\_mute\=False_, _self\_deaf\=False_, _self\_video\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.change_voice_state "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Changes client’s private channel voice state. New in version 2.0. Changed in version 2.1: Removed the `preferred_region` parameter. Parameters * **channel** (Optional\[[`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake")\ \]) – Channel the client wants to join (must be a private channel). Use `None` to disconnect. * **self\_mute** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Indicates if the client should be self-muted. * **self\_deaf** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Indicates if the client should be self-deafened. * **self\_video** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Indicates if the client is using video. Do not use. _await_ channel\_affinities()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.channel_affinities "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the channel affinities for the current user. Channel affinities are the channels you interact with most frecently. New in version 2.1. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the channel affinities failed. Returns The channel affinities. Return type List\[[`ChannelAffinity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ChannelAffinity "discord.ChannelAffinity")\ \] _await_ check\_pomelo\_username(_username_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check_pomelo_username "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Checks if a pomelo username is taken. New in version 2.1. Parameters **username** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The username to check. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – You are not in the pomelo rollout. Returns Whether the username is taken. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") _await_ checkout\_recovery()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.checkout_recovery "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Checks whether the client should prompt the user to continue their premium purchase. New in version 2.1. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the checkout recovery eligibility failed. Returns Whether the client should prompt the user for checkout recovery. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") clear()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.clear "Permalink to this definition") Clears the internal state of the bot. After this, the client can be considered “re-opened”, i.e. [`is_closed()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_closed "discord.ext.commands.Bot.is_closed") and [`is_ready()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_ready "discord.ext.commands.Bot.is_ready") both return `False` along with the bot’s internal cache cleared. _property_ client\_activities[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.client_activities "Permalink to this definition") Returns the activities the client is currently doing through this library, if applicable. New in version 2.0. Type Tuple\[[`BaseActivity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.BaseActivity "discord.BaseActivity")\ , …\] _property_ client\_status[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.client_status "Permalink to this definition") The library’s status. New in version 2.0. Type [`Status`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Status "discord.Status") _await_ close()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.close "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Closes the connection to Discord. _property_ cogs[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.cogs "Permalink to this definition") A read-only mapping of cog name to cog. Type Mapping\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , [`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog")\ \] _property_ commands[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.commands "Permalink to this definition") A unique set of commands without aliases that are registered. Type Set\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] _await_ connect(_\*_, _reconnect\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.connect "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a WebSocket connection and lets the WebSocket listen to messages from Discord. This is a loop that runs the entire event system and miscellaneous aspects of the library. Control is not resumed until the WebSocket connection is terminated. Parameters **reconnect** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as bad tokens). Raises * [**GatewayNotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GatewayNotFound "discord.GatewayNotFound") – If the gateway to connect to Discord is not found. Usually if this is thrown then there is a Discord API outage. * [**ConnectionClosed**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ConnectionClosed "discord.ConnectionClosed") – The websocket connection has been terminated. _property_ connections[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.connections "Permalink to this definition") The connections that the connected client has. These connections don’t have the [`Connection.metadata`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Connection.metadata "discord.Connection.metadata") attribute populated. New in version 2.0. Note Due to a Discord limitation, removed connections may not be removed from this cache. Type Sequence\[[`Connection`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Connection "discord.Connection")\ \] _property_ country\_code[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.country_code "Permalink to this definition") The country code of the client. `None` if not connected. New in version 2.0. Type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] _await_ create\_application(_name_, _/_, _\*_, _team\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_application "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates an application. New in version 2.0. Parameters * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the application. * **team** ([`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake") ) – The team to create the application under. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Failed to create the application. Returns The newly-created application. Return type [`Application`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Application "discord.Application") _await_ create\_authorization(_application\_id_, _/_, _\*_, _scopes_, _response\_type\=None_, _redirect\_uri\=None_, _code\_challenge\=None_, _state\=None_, _nonce\=None_, _guild\=..._, _channel\=..._, _permissions\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_authorization "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates an OAuth2 authorization for the given application. It is recommended to instead first fetch the authorization information using [`fetch_authorization()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_authorization "discord.ext.commands.Bot.fetch_authorization") and then call [`OAuth2Authorization.authorize()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.OAuth2Authorization.authorize "discord.OAuth2Authorization.authorize") . New in version 2.1. Parameters * **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the application to create the authorization for. * **scopes** (List\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The scopes to request for the authorization. * **response\_type** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The response type to use for the authorization, if using the full OAuth2 flow. * **redirect\_uri** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The redirect URI to use for the authorization, if using the full OAuth2 flow. If this isn’t provided and `response_type` is provided, then the default redirect URI for the application will be used. * **code\_challenge** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The code challenge to use for the PKCE authorization, if using the full OAuth2 flow. * **state** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The state to use for authorization security. You will need to verify this yourself. * **nonce** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The nonce that will be used for OpenID Connect authorization security. You will need to verify this yourself. * **guild** ([`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") ) – The guild to authorize for, if authorizing with the `applications.commands` or `bot` scopes. * **channel** (Union\[[`TextChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel "discord.TextChannel")\ , [`VoiceChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.VoiceChannel "discord.VoiceChannel")\ , [`StageChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StageChannel "discord.StageChannel")\ \]) – The channel to authorize for, if authorizing with the `webhooks.incoming` scope. See [`Guild.webhook_channels()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.webhook_channels "discord.Guild.webhook_channels") . * **permissions** ([`Permissions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Permissions "discord.Permissions") ) – The permissions to grant, if authorizing with the `bot` scope. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Creating the authorization failed. Returns The URL to redirect the user to for authorization. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _await_ create\_connection(_type_, _code_, _state_, _\*_, _two\_way\_link\_code\=None_, _insecure\=True_, _friend\_sync\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_connection "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a new connection. This is a low-level method that requires data obtained from other APIs. New in version 2.0. Parameters * **type** ([`ConnectionType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ConnectionType "discord.ConnectionType") ) – The type of connection to add. * **code** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The authorization code for the connection. * **state** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The state used to authorize the connection. * **two\_way\_link\_code** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The code to use for two-way linking, if any. * **insecure** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether the authorization is insecure. * **friend\_sync** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether friends are synced over the connection. Defaults to `True` for [`ConnectionType.facebook`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ConnectionType.facebook "discord.ConnectionType.facebook") and [`ConnectionType.contacts`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ConnectionType.contacts "discord.ConnectionType.contacts") , else `False`. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Creating the connection failed. _await_ create\_dm(_user_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_dm "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a [`DMChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.DMChannel "discord.DMChannel") with this user. This should be rarely called, as this is done transparently for most people. New in version 2.0. Parameters **user** ([`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake") ) – The user to create a DM with. Returns The channel that was created. Return type [`DMChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.DMChannel "discord.DMChannel") _await_ create\_group(_\*recipients_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_group "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a group direct message with the recipients provided. These recipients must be have a relationship of type [`RelationshipType.friend`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.RelationshipType.friend "discord.RelationshipType.friend") . New in version 2.0. Parameters **\*recipients** ([`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake") ) – An argument [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of [`discord.User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User") to have in your group. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Failed to create the group direct message. Returns The new group channel. Return type [`GroupChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GroupChannel "discord.GroupChannel") _await_ create\_guild(_name_, _icon\=..._, _code\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_guild "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") . Changed in version 2.0: `name` and `icon` parameters are now keyword-only. The `region` parameter has been removed. Changed in version 2.0: This function will now raise [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") instead of `InvalidArgument`. Parameters * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the guild. * **icon** (Optional\[[`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes "(in Python v3.14)")\ \]) – The [bytes-like object](https://docs.python.org/3/glossary.html#term-bytes-like-object "(in Python v3.14)") representing the icon. See [`ClientUser.edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientUser.edit "discord.ClientUser.edit") for more details on what is expected. * **code** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The code for a template to create the guild with. New in version 1.4. Raises * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Guild creation failed. * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – Invalid icon image format given. Must be PNG or JPG. Returns The guild created. This is not the same guild that is added to cache. Return type [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") _await_ create\_invite()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_invite "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a new friend [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") . New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Creating the invite failed. Returns The created friend invite. Return type [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") _await_ create\_payment\_source(_\*_, _token_, _payment\_gateway_, _billing\_address_, _billing\_address\_token\=..._, _return\_url\=None_, _bank\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_payment_source "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a payment source. This is a low-level method that requires data obtained from other APIs. New in version 2.0. Parameters * **token** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The payment source token. * **payment\_gateway** ([`PaymentGateway`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentGateway "discord.PaymentGateway") ) – The payment gateway to use. * **billing\_address** ([`BillingAddress`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.BillingAddress "discord.BillingAddress") ) – The billing address to use. * **billing\_address\_token** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The billing address token. If not provided, the library will fetch it for you. Not required for all payment gateways. * **return\_url** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The URL to return to after the payment source is created. * **bank** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The bank information for the payment source. Not required for most payment gateways. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Creating the payment source failed. Returns The newly-created payment source. Return type [`PaymentSource`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentSource "discord.PaymentSource") _await_ create\_subscription(_items_, _payment\_source_, _currency\='usd'_, _\*_, _trial\=None_, _payment\_source\_token\=None_, _purchase\_token\=None_, _return\_url\=None_, _gateway\_checkout\_context\=None_, _code\=None_, _metadata\=None_, _guild\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_subscription "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a new subscription. New in version 2.0. Parameters * **items** (List\[[`SubscriptionItem`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SubscriptionItem "discord.SubscriptionItem")\ \]) – The items in the subscription. * **payment\_source** ([`PaymentSource`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentSource "discord.PaymentSource") ) – The payment source to pay with. * **currency** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The currency to pay with. * **trial** (Optional\[[`SubscriptionTrial`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SubscriptionTrial "discord.SubscriptionTrial")\ \]) – The trial to apply to the subscription. * **payment\_source\_token** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The token used to authorize with the payment source. * **purchase\_token** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The purchase token to use. * **return\_url** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The URL to return to after the payment is complete. * **gateway\_checkout\_context** (Optional\[Dict\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , Any\]\]) – The current checkout context. * **code** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – Unknown. * **metadata** (Optional\[Mapping\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , Any\]\]) – Extra metadata about the subscription. * **guild** (Optional\[[`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild")\ \]) – The guild the subscription’s entitlements should be applied to. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Creating the subscription failed. Returns The newly-created subscription. Return type [`Subscription`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Subscription "discord.Subscription") _await_ create\_team(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.create_team "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Creates a team. New in version 2.0. Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the team. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Failed to create the team. Returns The newly-created team. Return type [`Team`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Team "discord.Team") _await_ delete\_invite(_invite_, _/_, _\*_, _reason\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.delete_invite "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Revokes an [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") , URL, or ID to an invite. You must have [`manage_channels`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Permissions.manage_channels "discord.Permissions.manage_channels") in the associated guild to do this. Changed in version 2.0: `invite` parameter is now positional-only. Changed in version 2.0: The function now returns the deleted invite. Parameters **invite** (Union\[[`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite")\ , [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The invite to revoke. Raises * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – You do not have permissions to revoke invites. * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The invite is invalid or expired. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Revoking the invite failed. Returns The deleted invite. Return type [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") _await_ delete\_recent\_mention(_message_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.delete_recent_mention "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Acknowledges a message the current user has been mentioned in. New in version 2.0. Parameters **message** ([`abc.Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake") ) – The message to delete. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Deleting the recent mention failed. _await_ detectable\_applications()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.detectable_applications "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the list of applications detectable by the Discord client. New in version 2.0. Changed in version 2.1: The method now returns a list of [`DetectableApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.DetectableApplication "discord.DetectableApplication") instead of [`PartialApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialApplication "discord.PartialApplication") due to an API change. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the applications failed. Returns The applications detectable by the Discord client. Return type List\[[`DetectableApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.DetectableApplication "discord.DetectableApplication")\ \] _property_ disclose[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.disclose "Permalink to this definition") Upcoming changes to the user’s account. New in version 2.1. Type Sequence\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] _await_ edit\_legacy\_settings(_\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.edit_legacy_settings "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Edits the client user’s settings. Changed in version 2.0: The edit is no longer in-place, instead the newly edited settings are returned. Deprecated since version 2.0. Parameters * **activity\_restricted\_guilds** (List\[[`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake")\ \]) – A list of guilds that your current activity will not be shown in. New in version 2.0. * **activity\_joining\_restricted\_guilds** (List\[[`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake")\ \]) – A list of guilds that will not be able to join your current activity. New in version 2.0. * **afk\_timeout** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – How long (in seconds) the user needs to be AFK until Discord sends push notifications to mobile device (30-600). * **allow\_accessibility\_detection** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to allow Discord to track screen reader usage. * **animate\_emojis** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to animate emojis in the chat. * **animate\_stickers** ([`StickerAnimationOptions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StickerAnimationOptions "discord.StickerAnimationOptions") ) – Whether to animate stickers in the chat. * **contact\_sync\_enabled** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to enable the contact sync on Discord mobile. * **convert\_emoticons** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to automatically convert emoticons into emojis (e.g. :) -> 😃). * **default\_guilds\_restricted** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to automatically disable DMs between you and members of new guilds you join. * **detect\_platform\_accounts** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to automatically detect accounts from services like Steam and Blizzard when you open the Discord client. * **developer\_mode** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to enable developer mode. * **disable\_games\_tab** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to disable the showing of the Games tab. * **enable\_tts\_command** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to allow TTS messages to be played/sent. * **explicit\_content\_filter** ([`UserContentFilter`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserContentFilter "discord.UserContentFilter") ) – The filter for explicit content in all messages. * **friend\_source\_flags** ([`FriendSourceFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.FriendSourceFlags "discord.FriendSourceFlags") ) – Who can add you as a friend. * **friend\_discovery\_flags** ([`FriendDiscoveryFlags`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.FriendDiscoveryFlags "discord.FriendDiscoveryFlags") ) – How you get recommended friends. * **gif\_auto\_play** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to automatically play GIFs that are in the chat. * **inline\_attachment\_media** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to display attachments when they are uploaded in chat. * **inline\_embed\_media** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to display videos and images from links posted in chat. * **locale** ([`Locale`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Locale "discord.Locale") ) – The [**RFC 3066**](https://datatracker.ietf.org/doc/html/rfc3066.html) language identifier of the locale to use for the language of the Discord client. * **message\_display\_compact** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to use the compact Discord display mode. * **native\_phone\_integration\_enabled** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to enable the new Discord mobile phone number friend requesting features. * **passwordless** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to enable passwordless login. * **render\_embeds** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to render embeds that are sent in the chat. * **render\_reactions** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to render reactions that are added to messages. * **restricted\_guilds** (List\[[`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake")\ \]) – A list of guilds that you will not receive DMs from. * **show\_current\_game** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to display the game that you are currently playing. * **stream\_notifications\_enabled** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether stream notifications for friends will be received. * **theme** ([`Theme`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Theme "discord.Theme") ) – The overall theme of the Discord UI. * **timezone\_offset** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The timezone offset to use. * **view\_nsfw\_guilds** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to show NSFW guilds on iOS. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Editing the settings failed. Returns The client user’s updated settings. Return type [`UserSettings`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserSettings "discord.UserSettings") _await_ email\_settings()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.email_settings "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves your email settings. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Getting the email settings failed. Returns The email settings. Return type [`EmailSettings`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.EmailSettings "discord.EmailSettings") _property_ emojis[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.emojis "Permalink to this definition") The emojis that the connected client has. Type Sequence\[[`Emoji`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Emoji "discord.Emoji")\ \] _await_ entitlements(_\*_, _with\_sku\=True_, _with\_application\=True_, _include\_ended\=True_, _entitlement\_type\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.entitlements "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all the entitlements for your account. New in version 2.0. Parameters * **with\_sku** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include the SKU information in the returned entitlements. * **with\_application** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include the application in the returned entitlements’ SKUs. The premium subscription application is always returned. * **include\_ended** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include ended entitlements in the returned list. New in version 2.1. * **entitlement\_type** (Optional\[[`EntitlementType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.EntitlementType "discord.EntitlementType")\ \]) – The type of entitlement to retrieve. If `None` then all entitlements are returned. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the entitlements failed. Returns The entitlements for your account. Return type List\[[`Entitlement`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Entitlement "discord.Entitlement")\ \] _property_ experiments[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.experiments "Permalink to this definition") The experiments assignments for the connected client. New in version 2.1. Type Sequence\[[`UserExperiment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserExperiment "discord.UserExperiment")\ \] _property_ extensions[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.extensions "Permalink to this definition") A read-only mapping of extension name to extension. Type Mapping\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , [`types.ModuleType`](https://docs.python.org/3/library/types.html#types.ModuleType "(in Python v3.14)")\ \] _await_ fetch\_application(_application\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_application "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the application with the given ID. The application must be owned by you or a team you are a part of. New in version 2.0. Parameters **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the application to fetch. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The application was not found. * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – You do not own the application. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the application failed. Returns The retrieved application. Return type [`Application`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Application "discord.Application") _await_ fetch\_authorization(_application\_id_, _/_, _\*_, _scopes_, _response\_type\=None_, _redirect\_uri\=None_, _code\_challenge\=None_, _state\=None_, _nonce\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_authorization "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves an OAuth2 authorization for the given application. This provides information about the application before you authorize it. New in version 2.1. Parameters * **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the application to fetch the authorization for. * **scopes** (List\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The scopes to request for the authorization. * **response\_type** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The response type that will be used for the authorization, if using the full OAuth2 flow. * **redirect\_uri** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The redirect URI that will be used for the authorization, if using the full OAuth2 flow. If this isn’t provided and `response_type` is provided, then the default redirect URI for the application will be provided in the returned authorization. * **code\_challenge** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The code challenge that will be used for PKCE authorization, if using the full OAuth2 flow. * **state** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The state that will be used for authorization security. You will need to verify this yourself. * **nonce** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The nonce that will be used for OpenID Connect authorization security. You will need to verify this yourself. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Fetching the authorization failed. Returns The authorization for the application. Return type [`OAuth2Authorization`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.OAuth2Authorization "discord.OAuth2Authorization") _await_ fetch\_channel(_channel\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_channel "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a [`abc.GuildChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel "discord.abc.GuildChannel") , [`abc.PrivateChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.PrivateChannel "discord.abc.PrivateChannel") , or [`Thread`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Thread "discord.Thread") with the specified ID. Note This method is an API call. For general usage, consider [`get_channel()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_channel "discord.ext.commands.Bot.get_channel") instead. New in version 1.2. Changed in version 2.0: `channel_id` parameter is now positional-only. Raises * [**InvalidData**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.InvalidData "discord.InvalidData") – An unknown channel type was received from Discord. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the channel failed. * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – Invalid Channel ID. * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – You do not have permission to fetch this channel. Returns The channel from the ID. Return type Union\[[`abc.GuildChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel "discord.abc.GuildChannel")\ , [`abc.PrivateChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.PrivateChannel "discord.abc.PrivateChannel")\ , [`Thread`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Thread "discord.Thread")\ \] _await_ fetch\_company(_company\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_company "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a company with the given ID. New in version 2.1. Parameters **company\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the company to fetch. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The company was not found. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the company failed. Returns The retrieved company. Return type [`Company`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Company "discord.Company") _await_ fetch\_connections()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_connections "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all of your connections. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving your connections failed. Returns All your connections. Return type List\[[`Connection`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Connection "discord.Connection")\ \] _await_ fetch\_country\_code()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_country_code "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the country code of the client. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the country code failed. Returns The country code of the client. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _await_ fetch\_entitlements(_application\_id_, _/_, _\*_, _include\_consumed\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_entitlements "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the entitlements this account has granted for the given application. New in version 2.0. Parameters * **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the application to fetch the entitlements for. * **include\_consumed** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include consumed entitlements. Changed in version 2.1: Renamed from `exclude_consumed` to `include_consumed`. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Fetching the entitlements failed. Returns The entitlements retrieved. Return type List\[[`Entitlement`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Entitlement "discord.Entitlement")\ \] _await_ fetch\_eula(_eula\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_eula "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a EULA with the given ID. New in version 2.0. Parameters **eula\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the EULA to retrieve. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The EULA does not exist. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the EULA failed. Returns The retrieved EULA. Return type [`EULA`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.EULA "discord.EULA") _await_ fetch\_experiments(_with\_guild\_experiments\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_experiments "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the experiment rollouts available in relation to the user. New in version 2.1. Note Certain guild experiments are only available via the gateway. See [`guild_experiments`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.guild_experiments "discord.ext.commands.Bot.guild_experiments") for these. Parameters **with\_guild\_experiments** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include guild experiment rollouts in the response. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the experiment assignments failed. Returns The experiment rollouts. Return type List\[Union\[[`UserExperiment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserExperiment "discord.UserExperiment")\ , [`GuildExperiment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildExperiment "discord.GuildExperiment")\ \]\] _await_ fetch\_gift(_code_, _\*_, _with\_application\=False_, _with\_subscription\_plan\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_gift "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a gift with the given code. New in version 2.0. Parameters * **code** (Union\[[`Gift`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Gift "discord.Gift")\ , [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The code of the gift to retrieve. * **with\_application** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include the application in the response’s store listing. The premium subscription application is always returned. * **with\_subscription\_plan** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include the subscription plan in the response. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The gift does not exist. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the gift failed. Returns The retrieved gift. Return type [`Gift`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Gift "discord.Gift") _await_ fetch\_guild(_guild\_id_, _/_, _\*_, _with\_counts\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_guild "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") from an ID. Note Using this, you will **not** receive [`Guild.channels`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.channels "discord.Guild.channels") and [`Guild.members`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.members "discord.Guild.members") . Note This method is an API call. For general usage, consider [`get_guild()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_guild "discord.ext.commands.Bot.get_guild") instead. Changed in version 2.0: `guild_id` parameter is now positional-only. Parameters * **guild\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The guild’s ID to fetch from. * **with\_counts** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include count information in the guild. This fills in [`Guild.approximate_member_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.approximate_member_count "discord.Guild.approximate_member_count") and [`Guild.approximate_presence_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.approximate_presence_count "discord.Guild.approximate_presence_count") . New in version 2.0. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The guild doesn’t exist or you got no access to it. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Getting the guild failed. Returns The guild from the ID. Return type [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") _await_ fetch\_guild\_preview(_guild\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_guild_preview "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a public [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") preview from an ID. New in version 2.0. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – Guild with given ID does not exist/is not public. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the guild failed. Returns The guild from the ID. Return type [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") _await_ fetch\_guilds(_\*_, _with\_counts\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_guilds "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all your guilds. Note This method is an API call. For general usage, consider [`guilds`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.guilds "discord.ext.commands.Bot.guilds") instead. Changed in version 2.0: This method now returns a list of [`UserGuild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserGuild "discord.UserGuild") instead of [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") . Parameters **with\_counts** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to fill [`Guild.approximate_member_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.approximate_member_count "discord.Guild.approximate_member_count") and [`Guild.approximate_presence_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.approximate_presence_count "discord.Guild.approximate_presence_count") . Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Getting the guilds failed. Returns A list of all your guilds. Return type List\[[`UserGuild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserGuild "discord.UserGuild")\ \] _await_ fetch\_invite(_url_, _/_, _\*_, _with\_counts\=True_, _with\_permissions\=True_, _with\_expiration\=True_, _scheduled\_event\_id\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_invite "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Gets an [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") from a discord.gg URL or ID. Note If the invite is for a guild you have not joined, the guild and channel attributes of the returned [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") will be [`PartialInviteGuild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialInviteGuild "discord.PartialInviteGuild") and [`PartialInviteChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialInviteChannel "discord.PartialInviteChannel") respectively. Changed in version 2.0: `url` parameter is now positional-only. Parameters * **url** (Union\[[`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite")\ , [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The Discord invite ID or URL (must be a discord.gg URL). * **with\_counts** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include count information in the invite. This fills the [`Invite.approximate_member_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite.approximate_member_count "discord.Invite.approximate_member_count") and [`Invite.approximate_presence_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite.approximate_presence_count "discord.Invite.approximate_presence_count") fields. * **with\_expiration** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include the expiration date of the invite. This fills the [`Invite.expires_at`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite.expires_at "discord.Invite.expires_at") field. New in version 2.0. Deprecated since version 2.1: This parameter is deprecated and will be removed in a future version as it is no longer needed to fill the [`Invite.expires_at`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite.expires_at "discord.Invite.expires_at") field. * **with\_permissions** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include permission information in the invite. This fills the [`Invite.is_nickname_changeable`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite.is_nickname_changeable "discord.Invite.is_nickname_changeable") field. New in version 2.1. * **scheduled\_event\_id** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The ID of the scheduled event this invite is for. Note It is not possible to provide a URL that contains an `event_id` parameter when using this parameter. New in version 2.0. Raises * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – The URL contains an `event_id`, but `scheduled_event_id` has also been provided. * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The invite has expired or is invalid. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Getting the invite failed. Returns The invite from the URL/ID. Return type [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") _await_ fetch\_live\_build\_ids(_\*branch\_ids_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_live_build_ids "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the live build IDs for the given branch IDs. New in version 2.0. Parameters **\*branch\_ids** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – A list of branch IDs to retrieve the live build IDs for. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the live build IDs failed. Returns A mapping of found branch IDs to their live build ID, if any. Return type Dict\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ , Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]\] _await_ fetch\_location\_info()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_location_info "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the location information of the client. New in version 2.1. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the location information failed. Returns The country code and subdivision code of the client. This is also accessible as a namedtuple with `country_code` and `subdivision_code` attributes. Return type Tuple\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]\] _await_ fetch\_note(_user\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_note "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a note for the specified user ID. New in version 1.9. Changed in version 2.0: `user_id` parameter is now positional-only. Changed in version 2.1: This method now returns a [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") instead of a `Note`. Parameters **user\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the user to fetch the note for. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the note failed. Returns The note you requested. Return type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] _await_ fetch\_notes()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_notes "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all your user notes. New in version 1.9. Changed in version 2.1: Renamed from `notes` to [`fetch_notes()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_notes "discord.ext.commands.Bot.fetch_notes") for forward compatibility. This method now returns a dictionary mapping user IDs to notes instead of a list of `Note` objects. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the notes failed. Returns A dictionary mapping user IDs to their notes. Return type Dict\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ , [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] _await_ fetch\_partial\_application(_application\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_partial_application "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the partial application with the given ID. New in version 2.0. Parameters **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the partial application to fetch. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The partial application was not found. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the partial application failed. Returns The retrieved application. Return type [`PartialApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialApplication "discord.PartialApplication") _await_ fetch\_payment(_payment\_id_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_payment "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the payment with the given ID. New in version 2.0. Parameters **payment\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the payment to fetch. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Fetching the payment failed. Returns The retrieved payment. Return type [`Payment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Payment "discord.Payment") _await_ fetch\_payment\_source(_source\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_payment_source "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the payment source with the given ID. New in version 2.0. Parameters **source\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the payment source to fetch. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The payment source was not found. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the payment source failed. Returns The retrieved payment source. Return type [`PaymentSource`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentSource "discord.PaymentSource") _await_ fetch\_preferred\_rtc\_regions()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_preferred_rtc_regions "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the preferred RTC regions of the client. New in version 2.0. Changed in version 2.1: Changed the name of the method from `fetch_preferred_voice_regions` to `fetch_preferred_rtc_regions`. The method now returns a list of tuples instead of a list of strings. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the preferred voice regions failed. Returns The region name and list of IPs for the closest voice regions. This is also accessible as a namedtuple with `region` and `ips` attributes. Return type List\[Tuple\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , List\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]\]\] _await_ fetch\_price\_tier(_price\_tier_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_price_tier "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a mapping of currency to price for the given price tier. New in version 2.0. Parameters **price\_tier** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The price tier to retrieve. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The price tier does not exist. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the price tier failed. Returns The retrieved price tier mapping. Return type Dict\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \] _await_ fetch\_primary\_store\_listing(_application\_id_, _/_, _\*_, _localize\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_primary_store_listing "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the primary store listing for the given application ID. This is the public store listing of the primary SKU. New in version 2.0. Parameters * **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the application to retrieve the listing for. * **localize** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to localize the store listings to the current user’s locale. If `False` then all localizations are returned. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The application does not exist or have a primary SKU. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the store listing failed. Returns The retrieved store listing. Return type [`StoreListing`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StoreListing "discord.StoreListing") _await_ fetch\_primary\_store\_listings(_\*application\_ids_, _localize\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_primary_store_listings "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the primary store listings for the given application IDs. This is the public store listing of the primary SKU. New in version 2.0. Parameters * **\*application\_ids** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – A list of application IDs to retrieve the listings for. * **localize** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to localize the store listings to the current user’s locale. If `False` then all localizations are returned. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the store listings failed. Returns The retrieved store listings. Return type List\[[`StoreListing`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StoreListing "discord.StoreListing")\ \] _await_ fetch\_private\_channels()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_private_channels "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all your private channels. New in version 2.0. Note This method is an API call. For general usage, consider [`private_channels`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.private_channels "discord.ext.commands.Bot.private_channels") instead. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving your private channels failed. Returns All your private channels. Return type List\[[`abc.PrivateChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.PrivateChannel "discord.abc.PrivateChannel")\ \] _await_ fetch\_public\_application(_application\_id_, _/_, _\*_, _with\_guild\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_public_application "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the public application with the given ID. New in version 2.0. Parameters * **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the public application to fetch. * **with\_guild** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include the public guild of the application. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The public application was not found. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the public application failed. Returns The retrieved application. Return type [`PartialApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialApplication "discord.PartialApplication") _await_ fetch\_public\_applications(_\*application\_ids_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_public_applications "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a list of public applications. Only found applications are returned. New in version 2.0. Parameters **\*application\_ids** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The IDs of the public applications to fetch. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the applications failed. Returns The public applications. Return type List\[[`PartialApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialApplication "discord.PartialApplication")\ \] _await_ fetch\_published\_store\_listing(_sku\_id_, _/_, _\*_, _localize\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_published_store_listing "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a published store listing with the given SKU ID. New in version 2.0. Parameters * **sku\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the SKU to retrieve the listing for. * **localize** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to localize the store listings to the current user’s locale. If `False` then all localizations are returned. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The listing does not exist or is not public. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the listing failed. Returns The store listing. Return type [`StoreListing`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StoreListing "discord.StoreListing") _await_ fetch\_published\_store\_listings(_application\_id_, _/_, _localize\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_published_store_listings "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all published store listings for the given application ID. New in version 2.0. Parameters * **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the application to retrieve the listings for. * **localize** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to localize the store listings to the current user’s locale. If `False` then all localizations are returned. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the listings failed. Returns The store listings. Return type List\[[`StoreListing`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StoreListing "discord.StoreListing")\ \] _await_ fetch\_relationships()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_relationships "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all your relationships. New in version 2.0. Note This method is an API call. For general usage, consider [`relationships`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.relationships "discord.ext.commands.Bot.relationships") instead. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving your relationships failed. Returns All your relationships. Return type List\[[`Relationship`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Relationship "discord.Relationship")\ \] _await_ fetch\_settings()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_settings "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves your user settings. New in version 2.0. Note This method is an API call. For general usage, consider [`settings`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.settings "discord.ext.commands.Bot.settings") instead. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving your settings failed. Returns The current settings for your account. Return type [`UserSettings`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserSettings "discord.UserSettings") _await_ fetch\_sku(_sku\_id_, _/_, _\*_, _localize\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sku "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a SKU with the given ID. New in version 2.0. Parameters * **sku\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the SKU to retrieve. * **localize** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to localize the SKU name and description to the current user’s locale. If `False` then all localizations are returned. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The SKU does not exist. * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – You do not have access to the SKU. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the SKU failed. Returns The retrieved SKU. Return type [`SKU`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SKU "discord.SKU") _await_ fetch\_sku\_subscription\_plans(_sku\_id_, _/_, _\*_, _country\_code\=..._, _payment\_source\=..._, _with\_unpublished\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sku_subscription_plans "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all subscription plans for the given SKU ID. New in version 2.0. Parameters * **sku\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the SKU to retrieve the subscription plans for. * **country\_code** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The country code to retrieve the subscription plan prices for. Defaults to the country code of the current user. * **payment\_source** ([`PaymentSource`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentSource "discord.PaymentSource") ) – The specific payment source to retrieve the subscription plan prices for. Defaults to all payment sources of the current user. * **with\_unpublished** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include unpublished subscription plans. If `True`, then you require access to the application. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the subscription plans failed. Returns The subscription plans. Return type List\[[`SubscriptionPlan`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SubscriptionPlan "discord.SubscriptionPlan")\ \] _await_ fetch\_skus\_subscription\_plans(_\*sku\_ids_, _country\_code\=..._, _payment\_source\=..._, _with\_unpublished\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_skus_subscription_plans "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all subscription plans for the given SKU IDs. New in version 2.0. Parameters * **\*sku\_ids** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – A list of SKU IDs to retrieve the subscription plans for. * **country\_code** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The country code to retrieve the subscription plan prices for. Defaults to the country code of the current user. * **payment\_source** ([`PaymentSource`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentSource "discord.PaymentSource") ) – The specific payment source to retrieve the subscription plan prices for. Defaults to all payment sources of the current user. * **with\_unpublished** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include unpublished subscription plans. If `True`, then you require access to the application(s). Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the subscription plans failed. Returns The subscription plans. Return type List\[[`SubscriptionPlan`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SubscriptionPlan "discord.SubscriptionPlan")\ \] _await_ fetch\_stage\_instance(_channel\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_stage_instance "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Gets a [`StageInstance`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StageInstance "discord.StageInstance") for a stage channel ID. New in version 2.0. Parameters **channel\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The stage channel ID. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The stage instance or channel could not be found. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Getting the stage instance failed. Returns The stage instance from the stage channel ID. Return type [`StageInstance`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StageInstance "discord.StageInstance") _await_ fetch\_sticker(_sticker\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sticker "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a [`Sticker`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Sticker "discord.Sticker") with the specified ID. New in version 2.0. Raises * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the sticker failed. * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – Invalid sticker ID. Returns The sticker you requested. Return type Union\[[`StandardSticker`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StandardSticker "discord.StandardSticker")\ , [`GuildSticker`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildSticker "discord.GuildSticker")\ \] _await_ fetch\_sticker\_pack(_pack\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sticker_pack "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a sticker pack with the specified ID. New in version 2.0. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – A sticker pack with that ID was not found. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the sticker packs failed. Returns The sticker pack you requested. Return type [`StickerPack`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StickerPack "discord.StickerPack") _await_ fetch\_store\_listing(_listing\_id_, _/_, _\*_, _localize\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_store_listing "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a store listing with the given ID. New in version 2.0. Parameters * **listing\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the listing to retrieve. * **localize** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to localize the store listings to the current user’s locale. If `False` then all localizations are returned. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The listing does not exist. * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – You do not have access to the listing. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the listing failed. Returns The store listing. Return type [`StoreListing`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StoreListing "discord.StoreListing") _await_ fetch\_subscription(_subscription\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_subscription "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the subscription with the given ID. New in version 2.0. Parameters **subscription\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the subscription to fetch. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The subscription was not found. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the subscription failed. Returns The retrieved subscription. Return type [`Subscription`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Subscription "discord.Subscription") _await_ fetch\_team(_team\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_team "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the team with the given ID. You must be a part of the team. New in version 2.0. Parameters **id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the team to fetch. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The team was not found. * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – You are not a part of the team. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the team failed. Returns The retrieved team. Return type [`Team`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Team "discord.Team") _await_ fetch\_template(_code_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_template "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Gets a [`Template`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Template "discord.Template") from a discord.new URL or code. Parameters **code** (Union\[[`Template`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Template "discord.Template")\ , [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The Discord Template Code or URL (must be a discord.new URL). Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – The template is invalid. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Getting the template failed. Returns The template from the URL/code. Return type [`Template`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Template "discord.Template") _await_ fetch\_tracking\_settings()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_tracking_settings "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves your Discord tracking consents. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the tracking settings failed. Returns The tracking settings. Return type [`TrackingSettings`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TrackingSettings "discord.TrackingSettings") _await_ fetch\_user(_user\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_user "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a [`discord.User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User") based on their ID. You do not have to share any guilds with the user to get this information, however many operations do require that you do. Note This method is an API call. If you have member cache enabled, consider [`get_user()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_user "discord.ext.commands.Bot.get_user") instead. Changed in version 2.0: `user_id` parameter is now positional-only. Parameters **user\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The user’s ID to fetch from. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – A user with this ID does not exist. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Fetching the user failed. Returns The user you requested. Return type [`discord.User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User") _await_ fetch\_user\_profile(_user\_id_, _/_, _\*_, _with\_mutual\_guilds\=True_, _with\_mutual\_friends\_count\=False_, _with\_mutual\_friends\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_user_profile "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a [`UserProfile`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserProfile "discord.UserProfile") based on their user ID. You must share a guild with, be friends with, or have an incoming friend request from this user to get this information, unless the user is a bot. Changed in version 2.0: `user_id` parameter is now positional-only. Parameters * **user\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the user to fetch their profile for. * **with\_mutual\_guilds** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to fetch mutual guilds. This fills in [`UserProfile.mutual_guilds`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserProfile.mutual_guilds "discord.UserProfile.mutual_guilds") . New in version 2.0. * **with\_mutual\_friends\_count** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to fetch the number of mutual friends. This fills in [`UserProfile.mutual_friends_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserProfile.mutual_friends_count "discord.UserProfile.mutual_friends_count") . New in version 2.0. * **with\_mutual\_friends** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to fetch mutual friends. This fills in [`UserProfile.mutual_friends`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserProfile.mutual_friends "discord.UserProfile.mutual_friends") and [`UserProfile.mutual_friends_count`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserProfile.mutual_friends_count "discord.UserProfile.mutual_friends_count") . New in version 2.0. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – A user with this ID does not exist. You do not have a mutual with this user and the user is not a bot. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Fetching the profile failed. Returns The profile of the user. Return type [`UserProfile`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserProfile "discord.UserProfile") _await_ fetch\_webhook(_webhook\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_webhook "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a [`Webhook`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Webhook "discord.Webhook") with the specified ID. Changed in version 2.0: `webhook_id` parameter is now positional-only. Raises * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the webhook failed. * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – Invalid webhook ID. * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – You do not have permission to fetch this webhook. Returns The webhook you requested. Return type [`Webhook`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Webhook "discord.Webhook") _await_ fetch\_widget(_guild\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_widget "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Gets a [`Widget`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Widget "discord.Widget") from a guild ID. Note The guild must have the widget enabled to get this information. Changed in version 2.0: `guild_id` parameter is now positional-only. Parameters **guild\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the guild. Raises * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – The widget for this guild is disabled. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the widget failed. Returns The guild’s widget. Return type [`Widget`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Widget "discord.Widget") _property_ friend\_suggestion\_count[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.friend_suggestion_count "Permalink to this definition") The number of friend suggestions that the connected client has. New in version 2.1. Type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") _await_ friend\_suggestions()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.friend_suggestions "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all your friend suggestions. New in version 2.1. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving your friend suggestions failed. Returns All your current friend suggestions. Return type List\[[`FriendSuggestion`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.FriendSuggestion "discord.FriendSuggestion")\ \] _property_ friends[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.friends "Permalink to this definition") Returns all the users that the connected client is friends with. New in version 2.0. Type List\[[`Relationship`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Relationship "discord.Relationship")\ \] _for ... in_ get\_all\_channels()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_all_channels "Permalink to this definition") A generator that retrieves every [`abc.GuildChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel "discord.abc.GuildChannel") the client can ‘access’. This is equivalent to: content\_copy for guild in client.guilds: for channel in guild.channels: yield channel Note Just because you receive a [`abc.GuildChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel "discord.abc.GuildChannel") does not mean that you can communicate in said channel. [`abc.GuildChannel.permissions_for()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel.permissions_for "discord.abc.GuildChannel.permissions_for") should be used for that. Yields [`abc.GuildChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel "discord.abc.GuildChannel") – A channel the client can ‘access’. _for ... in_ get\_all\_members()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_all_members "Permalink to this definition") Returns a generator with every [`Member`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Member "discord.Member") the client can see. This is equivalent to: content\_copy for guild in client.guilds: for member in guild.members: yield member Yields [`Member`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Member "discord.Member") – A member the client can see. get\_channel(_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_channel "Permalink to this definition") Returns a channel or thread with the given ID. Changed in version 2.0: `id` parameter is now positional-only. Parameters **id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID to search for. Returns The returned channel or `None` if not found. Return type Optional\[Union\[[`abc.GuildChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.GuildChannel "discord.abc.GuildChannel")\ , [`Thread`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Thread "discord.Thread")\ , [`abc.PrivateChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.PrivateChannel "discord.abc.PrivateChannel")\ \]\] get\_cog(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_cog "Permalink to this definition") Gets the cog instance requested. If the cog is not found, `None` is returned instead. Changed in version 2.0: `name` parameter is now positional-only. Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the cog you are requesting. This is equivalent to the name passed via keyword argument in class creation or the class name if unspecified. Returns The cog that was requested. If not found, returns `None`. Return type Optional\[[`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog")\ \] get\_command(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_command "Permalink to this definition") Get a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") from the internal list of commands. This could also be used as a way to get aliases. The name could be fully qualified (e.g. `'foo bar'`) will get the subcommand `bar` of the group command `foo`. If a subcommand is not found then `None` is returned just as usual. Changed in version 2.0: `name` parameter is now positional-only. Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the command to get. Returns The command that was requested. If not found, returns `None`. Return type Optional\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] _await_ get\_context(_message_, _/_, _\*_, _cls\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_context "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Returns the invocation context from the message. This is a more low-level counter-part for [`process_commands()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.process_commands "discord.ext.commands.Bot.process_commands") to allow users more fine grained control over the processing. The returned context is not guaranteed to be a valid invocation context, [`Context.valid`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context.valid "discord.ext.commands.Context.valid") must be checked to make sure it is. If the context is not valid then it is not a valid candidate to be invoked under [`invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invoke "discord.ext.commands.Bot.invoke") . Changed in version 2.0: `message` parameter is now positional-only. Parameters * **message** ([`discord.Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") ) – The message to get the invocation context from. * **cls** – The factory class that will be used to create the context. By default, this is [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . Should a custom class be provided, it must be similar enough to [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") 's interface. Returns The invocation context. The type of this can change via the `cls` parameter. Return type [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") get\_emoji(_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_emoji "Permalink to this definition") Returns an emoji with the given ID. Changed in version 2.0: `id` parameter is now positional-only. Parameters **id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID to search for. Returns The custom emoji or `None` if not found. Return type Optional\[[`Emoji`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Emoji "discord.Emoji")\ \] get\_experiment(_experiment_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_experiment "Permalink to this definition") Returns a user or guild experiment from the given experiment identifier. New in version 2.1. Parameters **experiment** (Union\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The experiment name or hash to search for. Returns The experiment, if found. Return type Optional\[Union\[[`UserExperiment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserExperiment "discord.UserExperiment")\ , [`GuildExperiment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildExperiment "discord.GuildExperiment")\ \]\] get\_guild(_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_guild "Permalink to this definition") Returns a guild with the given ID. Changed in version 2.0: `id` parameter is now positional-only. Parameters **id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID to search for. Returns The guild or `None` if not found. Return type Optional\[[`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild")\ \] get\_partial\_messageable(_id_, _\*_, _guild\_id\=None_, _type\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_partial_messageable "Permalink to this definition") Returns a partial messageable with the given channel ID. This is useful if you have a channel\_id but don’t want to do an API call to send messages to it. New in version 2.0. Parameters * **id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The channel ID to create a partial messageable for. * **guild\_id** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The optional guild ID to create a partial messageable for. This is not required to actually send messages, but it does allow the [`jump_url()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialMessageable.jump_url "discord.PartialMessageable.jump_url") and [`guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialMessageable.guild "discord.PartialMessageable.guild") properties to function properly. * **type** (Optional\[[`ChannelType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ChannelType "discord.ChannelType")\ \]) – The underlying channel type for the partial messageable. Returns The partial messageable Return type [`PartialMessageable`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PartialMessageable "discord.PartialMessageable") _await_ get\_prefix(_message_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_prefix "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the prefix the bot is listening to with the message as a context. Changed in version 2.0: `message` parameter is now positional-only. Parameters **message** ([`discord.Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") ) – The message context to get the prefix of. Returns A list of prefixes or a single prefix that the bot is listening for. Return type Union\[List\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \], [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] get\_relationship(_user\_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_relationship "Permalink to this definition") Retrieves the [`Relationship`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Relationship "discord.Relationship") , if applicable. New in version 2.0. Parameters **user\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The user ID to check if we have a relationship with them. Returns The relationship, if available. Return type Optional\[[`Relationship`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Relationship "discord.Relationship")\ \] get\_stage\_instance(_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_stage_instance "Permalink to this definition") Returns a stage instance with the given stage channel ID. New in version 2.0. Parameters **id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID to search for. Returns The stage instance or `None` if not found. Return type Optional\[[`StageInstance`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StageInstance "discord.StageInstance")\ \] get\_sticker(_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_sticker "Permalink to this definition") Returns a guild sticker with the given ID. New in version 2.0. Note To retrieve standard stickers, use [`fetch_sticker()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_sticker "discord.ext.commands.Bot.fetch_sticker") . or [`sticker_packs()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.sticker_packs "discord.ext.commands.Bot.sticker_packs") . Returns The sticker or `None` if not found. Return type Optional\[[`GuildSticker`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildSticker "discord.GuildSticker")\ \] get\_user(_id_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_user "Permalink to this definition") Returns a user with the given ID. Changed in version 2.0: `id` parameter is now positional-only. Parameters **id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID to search for. Returns The user or `None` if not found. Return type Optional\[[`User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User")\ \] _await_ giftable\_entitlements()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.giftable_entitlements "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the giftable entitlements for your account. These are entitlements you are able to gift to other users. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the giftable entitlements failed. Returns The giftable entitlements for your account. Return type List\[[`Entitlement`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Entitlement "discord.Entitlement")\ \] _await_ global\_activity\_statistics(_\*_, _with\_users\=True_, _with\_applications\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.global_activity_statistics "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the available activity usage statistics for the games your friends and implicit relationships play. New in version 2.0. Changed in version 2.1: Renamed from `relationship_activity_statistics()` to `global_activity_statistics()`. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the statistics failed. Returns The activity statistics. Return type List\[[`ApplicationActivityStatistics`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ApplicationActivityStatistics "discord.ApplicationActivityStatistics")\ \] _await_ guild\_affinities()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.guild_affinities "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the guild affinities for the current user. Guild affinities are the guilds you interact with most frecently. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the guild affinities failed. Returns The guild affinities. Return type List\[[`GuildAffinity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildAffinity "discord.GuildAffinity")\ \] _property_ guild\_experiments[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.guild_experiments "Permalink to this definition") The guild experiments assignments for the connected client. New in version 2.1. Type Sequence\[[`GuildExperiment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildExperiment "discord.GuildExperiment")\ \] _property_ guilds[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.guilds "Permalink to this definition") The guilds that the connected client is a member of. Type Sequence\[[`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild")\ \] _await_ handle\_captcha(_exception_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.handle_captcha "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Handles a CAPTCHA challenge and returns a solution. The default implementation tries to use the CAPTCHA handler passed in the constructor. New in version 2.1. Parameters **exception** ([`CaptchaRequired`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.CaptchaRequired "discord.CaptchaRequired") ) – The exception that was raised. Raises [**CaptchaRequired**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.CaptchaRequired "discord.CaptchaRequired") – The CAPTCHA challenge could not be solved. Returns The solution to the CAPTCHA challenge. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _property_ idle\_since[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.idle_since "Permalink to this definition") When the client went idle. This indicates that you are truly idle and not just lying. New in version 2.1. Type Optional\[[`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.14)")\ \] _property_ initial\_activities[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.initial_activities "Permalink to this definition") The activities set upon logging in. Type List\[[`BaseActivity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.BaseActivity "discord.BaseActivity")\ \] _property_ initial\_activity[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.initial_activity "Permalink to this definition") The primary activity set upon logging in. Note The client may be setting multiple activities, these can be accessed under [`initial_activities`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.initial_activities "discord.ext.commands.Bot.initial_activities") . Type Optional\[[`BaseActivity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.BaseActivity "discord.BaseActivity")\ \] _property_ initial\_status[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.initial_status "Permalink to this definition") The status set upon logging in. New in version 2.0. Type Optional\[[`Status`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Status "discord.Status")\ \] _await_ invites()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invites "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Gets a list of the user’s friend [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") s. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Getting the invites failed. Returns The list of invites. Return type List\[[`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite")\ \] _await_ invoke(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invoke "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Invokes the command given under the invocation context and handles all the internal event dispatch mechanisms. Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context to invoke. is\_afk()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_afk "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Indicates if the client is currently AFK. This allows the Discord client to know how to handle push notifications better for you in case you are away from your keyboard. New in version 2.1. is\_closed()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_closed "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Indicates if the websocket connection is closed. is\_on\_mobile()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_on_mobile "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : A helper function that determines if the user is active on a mobile device. New in version 2.0. _await_ is\_owner(_user_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_owner "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Checks if a [`User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User") or [`Member`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Member "discord.Member") is the owner of this bot. Changed in version 2.0: `user` parameter is now positional-only. Parameters **user** ([`abc.User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.User "discord.abc.User") ) – The user to check for. Raises [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.14)") – Owners aren’t set. Returns Whether the user is the owner. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") is\_ready()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_ready "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Specifies if the client’s internal cache is ready for use. is\_ws\_ratelimited()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.is_ws_ratelimited "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Whether the websocket is currently rate limited. This can be useful to know when deciding whether you should query members using HTTP or via the gateway. New in version 1.6. _await_ join\_active\_developer\_program(_\*_, _application_, _channel_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.join_active_developer_program "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Joins the current user to the active developer program. New in version 2.0. Parameters * **application** ([`Application`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Application "discord.Application") ) – The application to join the active developer program with. * **channel** ([`TextChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TextChannel "discord.TextChannel") ) – The channel to add the developer program webhook to. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Joining the active developer program failed. Returns The created webhook ID. Return type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") _await_ join\_guild(_guild\_id_, _/_, _lurking\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.join_guild "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Joins a discoverable [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") . Parameters * **guild\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The ID of the guild to join. * **lurking** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to lurk the guild. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – Guild with given ID does not exist/have discovery enabled. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Joining the guild failed. * [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.14)") – Attempted to lurk a guild without a session. Returns The guild joined. This is not the same guild that is added to cache. Return type [`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") _await_ join\_hub(_guild_, _email_, _\*_, _code\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.join_hub "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Joins the user to or requests a verification code for a Student Hub. New in version 2.1. Parameters * **guild** ([`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") ) – The hub to join. * **email** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The email to join with. * **code** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The email verification code. Note If not provided, this method requests a verification code instead. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Joining the hub or requesting the verification code failed. Returns The joined hub, if a code was provided. Return type Optional\[[`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild")\ \] _await_ join\_hub\_waitlist(_email_, _school_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.join_hub_waitlist "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Signs up for the Discord Student Hub waitlist. New in version 2.1. Parameters * **email** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The email to sign up with. * **school** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The school name to sign up with. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Signing up for the waitlist failed. _property_ latency[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.latency "Permalink to this definition") Measures latency between a HEARTBEAT and a HEARTBEAT\_ACK in seconds. This could be referred to as the Discord WebSocket protocol latency. Type [`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") _await_ leave\_active\_developer\_program()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.leave_active_developer_program "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Leaves the current user from the active developer program. This does not remove the created webhook. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Leaving the active developer program failed. _await_ leave\_guild(_guild_, _/_, _lurking\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.leave_guild "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Leaves a guild. Equivalent to [`Guild.leave()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.leave "discord.Guild.leave") . New in version 2.0. Parameters * **guild** ([`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake") ) – The guild to leave. * **lurking** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether you are lurking the guild. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Leaving the guild failed. _await_ legacy\_settings()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.legacy_settings "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves your legacy user settings. New in version 2.0. Deprecated since version 2.0. Note This method is no longer the recommended way to fetch your settings. Use [`fetch_settings()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.fetch_settings "discord.ext.commands.Bot.fetch_settings") instead. Note This method is an API call. For general usage, consider [`settings`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.settings "discord.ext.commands.Bot.settings") instead. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving your settings failed. Returns The current settings for your account. Return type [`LegacyUserSettings`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.LegacyUserSettings "discord.LegacyUserSettings") _await_ library()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.library "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the applications in your library. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the library failed. Returns The applications in your library. Return type List\[[`LibraryApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.LibraryApplication "discord.LibraryApplication")\ \] _await_ load\_extension(_name_, _\*_, _package\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.load_extension "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Loads an extension. An extension is a python module that contains commands, cogs, or listeners. An extension must have a global function, `setup` defined as the entry point on what to do when the extension is loaded. This entry point must have a single argument, the `bot`. Changed in version 2.0: This method is now a [coroutine](https://docs.python.org/3/glossary.html#term-coroutine "(in Python v3.14)") . Parameters * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The extension name to load. It must be dot separated like regular Python imports if accessing a sub-module. e.g. `foo.test` if you want to import `foo/test.py`. * **package** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The package name to resolve relative imports with. This is required when loading an extension using a relative path, e.g `.foo.test`. Defaults to `None`. New in version 1.7. Raises * [**ExtensionNotFound**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.ExtensionNotFound "discord.ext.commands.ExtensionNotFound") – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided `package` parameter. * [**ExtensionAlreadyLoaded**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.ExtensionAlreadyLoaded "discord.ext.commands.ExtensionAlreadyLoaded") – The extension is already loaded. * [**NoEntryPointError**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoEntryPointError "discord.ext.commands.NoEntryPointError") – The extension does not have a setup function. * [**ExtensionFailed**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.ExtensionFailed "discord.ext.commands.ExtensionFailed") – The extension or its setup function had an execution error. _await_ login(_token_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.login "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Logs in the client with the specified credentials and calls the [`setup_hook()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.setup_hook "discord.ext.commands.Bot.setup_hook") . Warning Logging on with a user token is unfortunately against the Discord [Terms of Service](https://support.discord.com/hc/en-us/articles/115002192352) and doing so might potentially get your account banned. Use this at your own risk. Parameters **token** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The authentication token. Raises * [**LoginFailure**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.LoginFailure "discord.LoginFailure") – The wrong credentials are passed. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – An unknown HTTP related error occurred, usually when it isn’t 200 or the known incorrect credentials passing status code. _await_ lookup\_hubs(_email_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.lookup_hubs "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Looks up the Discord Student Hubs for the given email. Note Using this, you will only receive [`Guild.id`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.id "discord.Guild.id") , [`Guild.name`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.name "discord.Guild.name") , and [`Guild.icon`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild.icon "discord.Guild.icon") per guild. New in version 2.1. Parameters **email** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The email to look up. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Looking up the hubs failed. Returns The hubs found. Return type List\[[`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild")\ \] _property_ notification\_settings[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.notification_settings "Permalink to this definition") Returns the notification settings for private channels. If not found, an instance is created with defaults applied. This follows Discord behaviour. New in version 2.0. Type [`GuildSettings`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildSettings "discord.GuildSettings") _await_ oauth2\_tokens()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.oauth2_tokens "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the OAuth2 applications authorized on your account. New in version 2.1. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the authorized applications failed. Returns The OAuth2 applications authorized on your account. Return type List\[[`OAuth2Token`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.OAuth2Token "discord.OAuth2Token")\ \] _await_ on\_command\_error(_context_, _exception_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.on_command_error "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . The default command error handler provided by the bot. By default this logs to the library logger, however it could be overridden to have a different implementation. This only fires if you do not specify any listeners for command error. Changed in version 2.0: `context` and `exception` parameters are now positional-only. Instead of writing to `sys.stderr` this now uses the library logger. _await_ on\_error(_event\_method_, _/_, _\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.on_error "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . The default error handler provided by the client. By default this logs to the library logger however it could be overridden to have a different implementation. Check [`on_error()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_error "discord.on_error") for more details. Changed in version 2.0: `event_method` parameter is now positional-only and instead of writing to `sys.stderr` it logs instead. _await_ payment\_sources()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.payment_sources "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all the payment sources for your account. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the payment sources failed. Returns The payment sources. Return type List\[[`PaymentSource`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentSource "discord.PaymentSource")\ \] _async for ... in_ payments(_\*_, _limit\=100_, _before\=None_, _after\=None_, _oldest\_first\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.payments "Permalink to this definition") Returns an [asynchronous iterator](https://docs.python.org/3/glossary.html#term-asynchronous-iterator "(in Python v3.14)") that enables receiving your payments. New in version 2.0. Examples Usage content\_copy counter \= 0 async for payment in client.payments(limit\=200): if payment.is\_purchased\_externally(): counter += 1 Flattening into a list: content\_copy payments \= \[payment async for payment in client.payments(limit\=123)\] \# payments is now a list of Payment... All parameters are optional. Parameters * **limit** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The number of payments to retrieve. If `None`, retrieves every payment you have made. Note, however, that this would make it a slow operation. * **before** (Optional\[Union\[[`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake")\ , [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.14)")\ \]\]) – Retrieve payments before this date or payment. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. * **after** (Optional\[Union\[[`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake")\ , [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.14)")\ \]\]) – Retrieve messages after this date or payment. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. * **oldest\_first** (Optional\[[`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)")\ \]) – If set to `True`, return payments in oldest->newest order. Defaults to `True` if `after` is specified, otherwise `False`. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – The request to get payments failed. Yields [`Payment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Payment "discord.Payment") – The payment made. _property_ pending\_payments[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.pending_payments "Permalink to this definition") The pending payments that the connected client has. New in version 2.0. Type Sequence\[[`Payment`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Payment "discord.Payment")\ \] _await_ pomelo\_suggestion(_global\_name\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.pomelo_suggestion "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Gets the suggested pomelo username for your account. This username can be used with [`edit()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientUser.edit "discord.ClientUser.edit") to migrate your account to Discord’s [new unique username system](https://discord.com/blog/usernames) Note This method requires you to be in the pomelo rollout if `global_name` is not provided. New in version 2.1. Parameters **global\_name** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The global name to suggest a username for. Defaults to the current user’s global name, if authenticated. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – You are not in the pomelo rollout. Returns The suggested username. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _property_ preferred\_rtc\_regions[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.preferred_rtc_regions "Permalink to this definition") Geo-ordered list of voice regions the connected client can use. This value is determined by Discord by default, but can be set to override it. New in version 2.0. Changed in version 2.1: Rename from `preferred_voice_regions` to `preferred_rtc_regions`. Type List\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] _await_ premium\_affinities()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_affinities "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves a list of friends who have a premium subscription, used to incentivize the user to purchase one as well. New in version 2.1. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the premium affinities failed. Returns The users who share a premium subscription with the current user. Return type List\[[`discord.User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User")\ \] _await_ premium\_entitlements(_\*_, _include\_consumed\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_entitlements "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the entitlements this account has granted for the premium application. These are the entitlements used for premium subscriptions, referred to as “Nitro Credits”. New in version 2.0. Parameters **include\_consumed** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include consumed entitlements. Changed in version 2.1: Renamed from `exclude_consumed` to `include_consumed`. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Fetching the entitlements failed. Returns The entitlements retrieved. Return type List\[[`Entitlement`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Entitlement "discord.Entitlement")\ \] _await_ premium\_guild\_subscription\_cooldown()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_guild_subscription_cooldown "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the cooldown for your premium guild subscriptions (boosts). New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the cooldown failed. Returns Your account’s premium guild subscription cooldown. Return type [`PremiumGuildSubscriptionCooldown`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PremiumGuildSubscriptionCooldown "discord.PremiumGuildSubscriptionCooldown") _await_ premium\_guild\_subscription\_slots()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_guild_subscription_slots "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all the premium guild subscription (boost) slots available on your account. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the subscriptions failed. Returns Your account’s premium guild subscription slots. Return type List\[[`PremiumGuildSubscriptionSlot`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PremiumGuildSubscriptionSlot "discord.PremiumGuildSubscriptionSlot")\ \] _await_ premium\_guild\_subscriptions()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_guild_subscriptions "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all the premium guild subscriptions (boosts) on your account. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the subscriptions failed. Returns Your account’s premium guild subscriptions. Return type List\[[`PremiumGuildSubscription`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PremiumGuildSubscription "discord.PremiumGuildSubscription")\ \] _await_ premium\_subscription\_plans()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_subscription_plans "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all premium subscription plans. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the premium subscription plans failed. Returns The premium subscription plans. Return type List\[[`SubscriptionPlan`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SubscriptionPlan "discord.SubscriptionPlan")\ \] _await_ premium\_usage()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.premium_usage "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the usage of the premium perks on your account. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the premium usage failed. Returns The premium usage. Return type [`PremiumUsage`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PremiumUsage "discord.PremiumUsage") _await_ preview\_subscription(_items_, _\*_, _payment\_source\=None_, _currency\='usd'_, _trial\=None_, _apply\_entitlements\=True_, _renewal\=False_, _code\=None_, _metadata\=None_, _guild\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.preview_subscription "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Preview an invoice for the subscription with the given parameters. All parameters are optional and default to the current subscription values. New in version 2.0. Parameters * **items** (List\[[`SubscriptionItem`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SubscriptionItem "discord.SubscriptionItem")\ \]) – The items the previewed subscription should have. * **payment\_source** (Optional\[[`PaymentSource`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentSource "discord.PaymentSource")\ \]) – The payment source the previewed subscription should be paid with. * **currency** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The currency the previewed subscription should be paid in. * **trial** (Optional\[[`SubscriptionTrial`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SubscriptionTrial "discord.SubscriptionTrial")\ \]) – The trial plan the previewed subscription should be on. * **apply\_entitlements** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to apply entitlements (credits) to the previewed subscription. * **renewal** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether the previewed subscription should be a renewal. * **code** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – Unknown. * **metadata** (Optional\[Mapping\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , Any\]\]) – Extra metadata about the subscription. * **guild** (Optional\[[`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild")\ \]) – The guild the previewed subscription’s entitlements should be applied to. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Failed to preview the invoice. Returns The previewed invoice. Return type [`SubscriptionInvoice`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.SubscriptionInvoice "discord.SubscriptionInvoice") _await_ price\_tiers()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.price_tiers "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all price tiers. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the price tiers failed. Returns The price tiers. Return type List\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \] _await_ pricing\_promotion()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.pricing_promotion "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the current localized pricing promotion for your account, if any. This also updates your current country code. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the pricing promotion failed. Returns The pricing promotion for your account, if any. Return type Optional\[[`PricingPromotion`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PricingPromotion "discord.PricingPromotion")\ \] _property_ private\_channels[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.private_channels "Permalink to this definition") The private channels that the connected client is participating on. Type Sequence\[[`abc.PrivateChannel`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.PrivateChannel "discord.abc.PrivateChannel")\ \] _await_ process\_commands(_message_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.process_commands "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . This function processes the commands that have been registered to the bot and other groups. Without this coroutine, none of the commands will be triggered. By default, this coroutine is called inside the [`on_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message "discord.on_message") event. If you choose to override the [`on_message()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_message "discord.on_message") event, then you should invoke this coroutine as well. This is built using other low level tools, and is equivalent to a call to [`get_context()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_context "discord.ext.commands.Bot.get_context") followed by a call to [`invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invoke "discord.ext.commands.Bot.invoke") . This also checks if the message’s author is a bot and doesn’t call [`get_context()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.get_context "discord.ext.commands.Bot.get_context") or [`invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.invoke "discord.ext.commands.Bot.invoke") if so. Changed in version 2.0: `message` parameter is now positional-only. Parameters **message** ([`discord.Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") ) – The message to process commands for. _await_ promotions(_claimed\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.promotions "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all the promotions available for your account. New in version 2.0. Parameters **claimed** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to only retrieve claimed promotions. These will have [`Promotion.claimed_at`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Promotion.claimed_at "discord.Promotion.claimed_at") and [`Promotion.code`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Promotion.code "discord.Promotion.code") set. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the promotions failed. Returns The promotions available for you. Return type List\[[`Promotion`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Promotion "discord.Promotion")\ \] _await_ proxy\_external\_application\_assets(_application\_id_, _\*urls_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.proxy_external_application_assets "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Proxies up to 2 external asset URLs through Discord’s media proxy, for use in rich presence. Parameters * **application\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The rich presence application ID. * **\*urls** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The external asset URLs to proxy. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Proxying the assets failed. Returns The proxied asset URLs. Return type List\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] _property_ raw\_status[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.raw_status "Permalink to this definition") The user’s overall status as a string value. New in version 2.0. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _property_ read\_states[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.read_states "Permalink to this definition") The read states that the connected client has. New in version 2.1. Type List\[[`ReadState`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ReadState "discord.ReadState")\ \] _await_ recent\_avatars()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.recent_avatars "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the recent avatars for the current user. For premium users, the six most recent avatars will be returned. Otherwise, only two will be returned. New in version 2.1. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the recent avatars failed. Returns The recent avatars. Return type List\[[`RecentAvatar`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.RecentAvatar "discord.RecentAvatar")\ \] _async for ... in_ recent\_mentions(_\*_, _limit\=25_, _before\=..._, _guild\=..._, _roles\=True_, _everyone\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.recent_mentions "Permalink to this definition") Returns an [asynchronous iterator](https://docs.python.org/3/glossary.html#term-asynchronous-iterator "(in Python v3.14)") that enables receiving your recent mentions. New in version 2.0. Examples Usage content\_copy counter \= 0 async for message in client.recent\_mentions(limit\=200): if message.author \== client.user: counter += 1 Flattening into a list: content\_copy messages \= \[message async for message in client.recent\_mentions(limit\=123)\] \# messages is now a list of Message... All parameters are optional. Parameters * **limit** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The number of messages to retrieve. If `None`, retrieves every recent mention received in the past week. Note, however, that this would make it a slow operation. * **before** (Optional\[Union\[[`Snowflake`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Snowflake "discord.abc.Snowflake")\ , [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.14)")\ \]\]) – Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. * **guild** ([`Guild`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Guild "discord.Guild") ) – The guild to retrieve recent mentions from. If not provided, then the mentions are retrieved from all guilds. * **roles** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include role mentions. * **everyone** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include @everyone or @here mentions. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – The request to get recent message history failed. Yields [`Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") – The message with the message data parsed. _property_ relationships[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.relationships "Permalink to this definition") Returns all the relationships that the connected client has. New in version 2.0. Type Sequence\[[`Relationship`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Relationship "discord.Relationship")\ \] _await_ reload\_extension(_name_, _\*_, _package\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.reload_extension "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Atomically reloads an extension. This replaces the extension with the same extension, only refreshed. This is equivalent to a [`unload_extension()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.unload_extension "discord.ext.commands.Bot.unload_extension") followed by a [`load_extension()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.load_extension "discord.ext.commands.Bot.load_extension") except done in an atomic way. That is, if an operation fails mid-reload then the bot will roll-back to the prior working state. Parameters * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The extension name to reload. It must be dot separated like regular Python imports if accessing a sub-module. e.g. `foo.test` if you want to import `foo/test.py`. * **package** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The package name to resolve relative imports with. This is required when reloading an extension using a relative path, e.g `.foo.test`. Defaults to `None`. New in version 1.7. Raises * [**ExtensionNotLoaded**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.ExtensionNotLoaded "discord.ext.commands.ExtensionNotLoaded") – The extension was not loaded. * [**ExtensionNotFound**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.ExtensionNotFound "discord.ext.commands.ExtensionNotFound") – The extension could not be imported. This is also raised if the name of the extension could not be resolved using the provided `package` parameter. * [**NoEntryPointError**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoEntryPointError "discord.ext.commands.NoEntryPointError") – The extension does not have a setup function. * [**ExtensionFailed**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.ExtensionFailed "discord.ext.commands.ExtensionFailed") – The extension setup function had an execution error. remove\_check(_func_, _/_, _\*_, _call\_once\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.remove_check "Permalink to this definition") Removes a global check from the bot. This function is idempotent and will not raise an exception if the function is not in the global checks. Changed in version 2.0: `func` parameter is now positional-only. Parameters * **func** – The function to remove from the global checks. * **call\_once** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – If the function was added with `call_once=True` in the [`Bot.add_check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.add_check "discord.ext.commands.Bot.add_check") call or using [`check_once()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check_once "discord.ext.commands.Bot.check_once") . _await_ remove\_cog(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.remove_cog "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Removes a cog from the bot and returns it. All registered commands and event listeners that the cog has registered will be removed as well. If no cog is found then this method has no effect. Changed in version 2.0: `name` parameter is now positional-only. Changed in version 2.0: This method is now a [coroutine](https://docs.python.org/3/glossary.html#term-coroutine "(in Python v3.14)") . Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the cog to remove. Returns The cog that was removed. `None` if not found. Return type Optional\[[`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog")\ \] remove\_command(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.remove_command "Permalink to this definition") Remove a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") from the internal list of commands. This could also be used as a way to remove aliases. Changed in version 2.0: `name` parameter is now positional-only. Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the command to remove. Returns The command that was removed. If the name is not valid then `None` is returned instead. Return type Optional\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] remove\_listener(_func_, _/_, _name\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.remove_listener "Permalink to this definition") Removes a listener from the pool of listeners. Changed in version 2.0: `func` parameter is now positional-only. Parameters * **func** – The function that was used as a listener to remove. * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the event we want to remove. Defaults to `func.__name__`. _await_ report\_unverified\_application(_name_, _\*_, _icon_, _os_, _executable\=..._, _publisher\=..._, _distributor\=..._, _sku\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.report_unverified_application "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Reports an unverified application (a game not detected by the Discord client) to Discord. If missing, this also uploads the application icon to Discord. New in version 2.1. Parameters * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the application. * **icon** ([`File`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.File "discord.File") ) – The icon of the application. * **os** ([`OperatingSystem`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.OperatingSystem "discord.OperatingSystem") ) – The operating system the application is found on. * **executable** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The executable of the application. * **publisher** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The publisher of the application. * **distributor** ([`Distributor`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Distributor "discord.Distributor") ) – The distributor of the application SKU. * **sku** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The SKU of the application. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Reporting the unverified application failed. Returns The reported unverified application. Return type [`UnverifiedApplication`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UnverifiedApplication "discord.UnverifiedApplication") _property_ required\_action[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.required_action "Permalink to this definition") The required action for the current user. A required action is something Discord requires you to do to continue using your account. New in version 2.0. Type Optional\[[`RequiredActionType`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.RequiredActionType "discord.RequiredActionType")\ \] _await_ revoke\_invites()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.revoke_invites "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Revokes all of the user’s friend [`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite") s. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Revoking the invites failed. Returns The revoked invites. Return type List\[[`Invite`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Invite "discord.Invite")\ \] run(_token_, _\*_, _reconnect\=True_, _log\_handler\=..._, _log\_formatter\=..._, _log\_level\=..._, _root\_logger\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.run "Permalink to this definition") A blocking call that abstracts away the event loop initialisation from you. If you want more control over the event loop then this function should not be used. Use [`start()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.start "discord.ext.commands.Bot.start") coroutine or [`connect()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.connect "discord.ext.commands.Bot.connect") + [`login()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.login "discord.ext.commands.Bot.login") . This function also sets up the logging library to make it easier for beginners to know what is going on with the library. For more advanced users, this can be disabled by passing `None` to the `log_handler` parameter. Warning This function must be the last function to call due to the fact that it is blocking. That means that registration of events or anything being called after this function call will not execute until it returns. Parameters * **token** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The authentication token. * **reconnect** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as bad tokens). * **log\_handler** (Optional\[[`logging.Handler`](https://docs.python.org/3/library/logging.html#logging.Handler "(in Python v3.14)")\ \]) – The log handler to use for the library’s logger. If this is `None` then the library will not set up anything logging related. Logging will still work if `None` is passed, though it is your responsibility to set it up. The default log handler if not provided is [`logging.StreamHandler`](https://docs.python.org/3/library/logging.handlers.html#logging.StreamHandler "(in Python v3.14)") . New in version 2.0. * **log\_formatter** ([`logging.Formatter`](https://docs.python.org/3/library/logging.html#logging.Formatter "(in Python v3.14)") ) – The formatter to use with the given log handler. If not provided then it defaults to a colour based logging formatter (if available). New in version 2.0. * **log\_level** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The default log level for the library’s logger. This is only applied if the `log_handler` parameter is not `None`. Defaults to `logging.INFO`. New in version 2.0. * **root\_logger** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to set up the root logger rather than the library logger. By default, only the library logger (`'discord'`) is set up. If this is set to `True` then the root logger is set up as well. Defaults to `False`. New in version 2.0. _await_ search\_companies(_query_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.search_companies "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Query companies registered on Discord. New in version 2.0. Parameters **query** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The query to search for. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Searching failed. Returns The companies found. Return type List\[[`Company`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Company "discord.Company")\ \] _await_ send\_friend\_request(_\*args_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.send_friend_request "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Sends a friend request to another user. This function can be used in multiple ways. New in version 2.0. content\_copy \# Passing a user object: await client.send\_friend\_request(user) \# Passing a username await client.send\_friend\_request('jake') \# Passing a legacy user: await client.send\_friend\_request('Jake#0001') \# Passing a legacy username and discriminator: await client.send\_friend\_request('Jake', '0001') Parameters * **user** (Union\[[`discord.User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User")\ , [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The user to send the friend request to. * **username** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The username of the user to send the friend request to. * **discriminator** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The discriminator of the user to send the friend request to. Raises * [**Forbidden**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Forbidden "discord.Forbidden") – Not allowed to send a friend request to this user. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Sending the friend request failed. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – More than 2 parameters or less than 1 parameter was passed. _property_ sessions[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.sessions "Permalink to this definition") The gateway sessions that the current user is connected in with. When connected, this includes a representation of the library’s session and an “all” session representing the user’s overall presence. New in version 2.0. Type Sequence\[[`Session`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Session "discord.Session")\ \] _property_ settings[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.settings "Permalink to this definition") Returns the user’s settings. New in version 2.0. Type Optional\[[`UserSettings`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserSettings "discord.UserSettings")\ \] _await_ setup\_hook()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.setup_hook "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A coroutine to be called to setup the client, by default this is blank. To perform asynchronous setup after the user is logged in but before it has connected to the Websocket, overwrite this coroutine. This is only called once, in [`login()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.login "discord.ext.commands.Bot.login") , and will be called before any events are dispatched, making it a better solution than doing such setup in the [`on_ready()`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.on_ready "discord.on_ready") event. Warning Since this is called _before_ the websocket connection is made therefore anything that waits for the websocket will deadlock, this includes things like [`wait_for()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.wait_for "discord.ext.commands.Bot.wait_for") and [`wait_until_ready()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.wait_until_ready "discord.ext.commands.Bot.wait_until_ready") . New in version 2.0. _await_ start(_token_, _\*_, _reconnect\=True_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.start "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A shorthand coroutine for [`login()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.login "discord.ext.commands.Bot.login") + [`connect()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.connect "discord.ext.commands.Bot.connect") . Parameters * **token** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The authentication token. * **reconnect** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – If we should attempt reconnecting, either due to internet failure or a specific failure on Discord’s part. Certain disconnects that lead to bad state will not be handled (such as bad tokens). Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – An unexpected keyword argument was received. _property_ status[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.status "Permalink to this definition") The user’s overall status. New in version 2.0. Type [`Status`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Status "discord.Status") _await_ sticker\_packs()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.sticker_packs "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all available default sticker packs. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the sticker packs failed. Returns All available sticker packs. Return type List\[[`StickerPack`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.StickerPack "discord.StickerPack")\ \] _property_ stickers[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.stickers "Permalink to this definition") The stickers that the connected client has. New in version 2.0. Type Sequence\[[`GuildSticker`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.GuildSticker "discord.GuildSticker")\ \] _await_ subscriptions(_limit\=None_, _with\_inactive\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.subscriptions "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all the subscriptions on your account. New in version 2.0. Parameters * **limit** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The maximum number of subscriptions to retrieve. Defaults to all subscriptions. * **with\_inactive** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to include inactive subscriptions. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the subscriptions failed. Returns Your account’s subscriptions. Return type List\[[`Subscription`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Subscription "discord.Subscription")\ \] _await_ teams(_\*_, _with\_payout\_account\_status\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.teams "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves all the teams you’re a part of. New in version 2.0. Parameters **with\_payout\_account\_status** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to return the payout account status of the teams. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the teams failed. Returns The teams you’re a part of. Return type List\[[`Team`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Team "discord.Team")\ \] _property_ tracking\_settings[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.tracking_settings "Permalink to this definition") Returns your tracking consents, if available. New in version 2.0. Type Optional\[[`TrackingSettings`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TrackingSettings "discord.TrackingSettings")\ \] _await_ trial\_offer()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.trial_offer "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the current trial offer for your account. New in version 2.0. Deprecated since version 2.1: This method is deprecated and will be removed in a future version. Use [`user_offer()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.user_offer "discord.ext.commands.Bot.user_offer") instead. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – You do not have a trial offer. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the trial offer failed. Returns The trial offer for your account. Return type [`TrialOffer`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.TrialOffer "discord.TrialOffer") _property_ tutorial[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.tutorial "Permalink to this definition") The tutorial state of the connected client. New in version 2.1. Type [`Tutorial`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Tutorial "discord.Tutorial") _await_ unload\_extension(_name_, _\*_, _package\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.unload_extension "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Unloads an extension. When the extension is unloaded, all commands, listeners, and cogs are removed from the bot and the module is un-imported. The extension can provide an optional global function, `teardown`, to do miscellaneous clean-up if necessary. This function takes a single parameter, the `bot`, similar to `setup` from [`load_extension()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.load_extension "discord.ext.commands.Bot.load_extension") . Changed in version 2.0: This method is now a [coroutine](https://docs.python.org/3/glossary.html#term-coroutine "(in Python v3.14)") . Parameters * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The extension name to unload. It must be dot separated like regular Python imports if accessing a sub-module. e.g. `foo.test` if you want to import `foo/test.py`. * **package** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The package name to resolve relative imports with. This is required when unloading an extension using a relative path, e.g `.foo.test`. Defaults to `None`. New in version 1.7. Raises * [**ExtensionNotFound**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.ExtensionNotFound "discord.ext.commands.ExtensionNotFound") – The name of the extension could not be resolved using the provided `package` parameter. * [**ExtensionNotLoaded**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.ExtensionNotLoaded "discord.ext.commands.ExtensionNotLoaded") – The extension was not loaded. _property_ user[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.user "Permalink to this definition") Represents the connected client. `None` if not logged in. Type Optional\[[`ClientUser`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientUser "discord.ClientUser")\ \] _await_ user\_affinities()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.user_affinities "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the user affinities for the current user. User affinities are the users you interact with most frecently. New in version 2.0. Raises [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the user affinities failed. Returns The user affinities. Return type List\[[`UserAffinity`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserAffinity "discord.UserAffinity")\ \] _await_ user\_offer(_\*_, _discount\_id\=..._, _payment\_gateway\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.user_offer "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Retrieves the current user offer for your account. This includes the trial offer and discount offer. New in version 2.1. Parameters * **discount\_id** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The specific discount ID to fetch the offer of. * **payment\_gateway** (Optional\[[`PaymentGateway`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentGateway "discord.PaymentGateway")\ \]) – The payment gateway to fetch the user offer for. Used to fetch user offers for [`PaymentGateway.apple`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentGateway.apple "discord.PaymentGateway.apple") and [`PaymentGateway.google`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.PaymentGateway.google "discord.PaymentGateway.google") mobile platforms. Raises * [**NotFound**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.NotFound "discord.NotFound") – You do not have a user offer. * [**HTTPException**](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.HTTPException "discord.HTTPException") – Retrieving the user offer failed. Returns The user offer for your account. Return type [`UserOffer`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.UserOffer "discord.UserOffer") _property_ users[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.users "Permalink to this definition") Returns a list of all the users the current user can see. Type List\[[`User`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.User "discord.User")\ \] _property_ voice\_client[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.voice_client "Permalink to this definition") Returns the [`VoiceProtocol`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.VoiceProtocol "discord.VoiceProtocol") associated with private calls, if any. Type Optional\[[`VoiceProtocol`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.VoiceProtocol "discord.VoiceProtocol")\ \] _property_ voice\_clients[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.voice_clients "Permalink to this definition") Represents a list of voice connections. These are usually [`VoiceClient`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.VoiceClient "discord.VoiceClient") instances. Type List\[[`VoiceProtocol`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.VoiceProtocol "discord.VoiceProtocol")\ \] wait\_for(_event_, _/_, _\*_, _check\=None_, _timeout\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.wait_for "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Waits for a WebSocket event to be dispatched. This could be used to wait for a user to reply to a message, or to react to a message, or to edit a message in a self-contained way. The `timeout` parameter is passed onto [`asyncio.wait_for()`](https://docs.python.org/3/library/asyncio-task.html#asyncio.wait_for "(in Python v3.14)") . By default, it does not timeout. Note that this does propagate the [`asyncio.TimeoutError`](https://docs.python.org/3/library/asyncio-exceptions.html#asyncio.TimeoutError "(in Python v3.14)") for you in case of timeout and is provided for ease of use. In case the event returns multiple arguments, a [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.14)") containing those arguments is returned instead. Please check the [documentation](https://discordpy-self.readthedocs.io/en/latest/api.html#discord-api-events) for a list of events and their parameters. This function returns the **first event that meets the requirements**. Examples Waiting for a user reply: content\_copy @client.event async def on\_message(message): if message.content.startswith('$greet'): channel \= message.channel await channel.send('Say hello!') def check(m): return m.content \== 'hello' and m.channel \== channel msg \= await client.wait\_for('message', check\=check) await channel.send(f'Hello {msg.author}!') Waiting for a thumbs up reaction from the message author: content\_copy @client.event async def on\_message(message): if message.content.startswith('$thumb'): channel \= message.channel await channel.send('Send me that 👍 reaction, mate') def check(reaction, user): return user \== message.author and str(reaction.emoji) \== '👍' try: reaction, user \= await client.wait\_for('reaction\_add', timeout\=60.0, check\=check) except asyncio.TimeoutError: await channel.send('👎') else: await channel.send('👍') Changed in version 2.0: `event` parameter is now positional-only. Parameters * **event** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The event name, similar to the [event reference](https://discordpy-self.readthedocs.io/en/latest/api.html#discord-api-events) , but without the `on_` prefix, to wait for. * **check** (Optional\[Callable\[…, [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)")\ \]\]) – A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for. * **timeout** (Optional\[[`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)")\ \]) – The number of seconds to wait before timing out and raising [`asyncio.TimeoutError`](https://docs.python.org/3/library/asyncio-exceptions.html#asyncio.TimeoutError "(in Python v3.14)") . Raises [**asyncio.TimeoutError**](https://docs.python.org/3/library/asyncio-exceptions.html#asyncio.TimeoutError "(in Python v3.14)") – If a timeout is provided and it was reached. Returns Returns no arguments, a single argument, or a [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.14)") of multiple arguments that mirrors the parameters passed in the [event reference](https://discordpy-self.readthedocs.io/en/latest/api.html#discord-api-events) . Return type Any _await_ wait\_until\_ready()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.wait_until_ready "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Waits until the client’s internal cache is all ready. Warning Calling this inside [`setup_hook()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.setup_hook "discord.ext.commands.Bot.setup_hook") can lead to a deadlock. _for ... in_ walk\_commands()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.walk_commands "Permalink to this definition") An iterator that recursively walks through all commands and subcommands. Changed in version 1.4: Duplicates due to aliases are no longer returned Yields Union\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ , [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] – A command or group from the internal list of commands. Prefix Helpers[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#prefix-helpers "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------------------- discord.ext.commands.when\_mentioned(_bot_, _msg_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.when_mentioned "Permalink to this definition") A callable that implements a command prefix equivalent to being mentioned. These are meant to be passed into the [`Bot.command_prefix`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.command_prefix "discord.ext.commands.Bot.command_prefix") attribute. > Changed in version 2.0: `bot` and `msg` parameters are now positional-only. discord.ext.commands.when\_mentioned\_or(_\*prefixes_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.when_mentioned_or "Permalink to this definition") A callable that implements when mentioned or other prefixes provided. These are meant to be passed into the [`Bot.command_prefix`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.command_prefix "discord.ext.commands.Bot.command_prefix") attribute. Example content\_copy bot \= commands.Bot(command\_prefix\=commands.when\_mentioned\_or('!')) Note This callable returns another callable, so if this is done inside a custom callable, you must call the returned callable, for example: content\_copy async def get\_prefix(bot, message): extras \= await prefixes\_for(message.guild) \# returns a list return commands.when\_mentioned\_or(\*extras)(bot, message) See also [`when_mentioned()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.when_mentioned "discord.ext.commands.when_mentioned") Event Reference[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#event-reference "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------------------------- These events function similar to [the regular events](https://discordpy-self.readthedocs.io/en/latest/api.html#discord-api-events) , except they are custom to the command extension module. discord.ext.commands.on\_command\_error(_ctx_, _error_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "Permalink to this definition") An error handler that is called when an error is raised inside a command either through user input error, check failure, or an error in your own code. A default one is provided ([`Bot.on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.on_command_error "discord.ext.commands.Bot.on_command_error") ). Parameters * **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context. * **error** ([`CommandError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") derived) – The error that was raised. discord.ext.commands.on\_command(_ctx_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command "Permalink to this definition") An event that is called when a command is found and is about to be invoked. This event is called regardless of whether the command itself succeeds via error or completes. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context. discord.ext.commands.on\_command\_completion(_ctx_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_completion "Permalink to this definition") An event that is called when a command has completed its invocation. This event is called only if the command succeeded, i.e. all checks have passed and the user input it correctly. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context. Commands[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#commands "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------------- ### Decorators[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#decorators "Permalink to this headline") @discord.ext.commands.command(_name\=..._, _cls\=..._, _\*\*attrs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.command "Permalink to this definition") A decorator that transforms a function into a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") or if called with [`group()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.group "discord.ext.commands.group") , [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") . By default the `help` attribute is received automatically from the docstring of the function and is cleaned up with the use of `inspect.cleandoc`. If the docstring is `bytes`, then it is decoded into [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") using utf-8 encoding. All checks added using the [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") & co. decorators are added into the function. There is no way to supply your own checks through this decorator. Parameters * **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name to create the command with. By default this uses the function name unchanged. * **cls** – The class to construct with. By default this is [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") . You usually do not change this. * **attrs** – Keyword arguments to pass into the construction of the class denoted by `cls`. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – If the function is not a coroutine or is already a command. @discord.ext.commands.group(_name\=..._, _cls\=..._, _\*\*attrs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.group "Permalink to this definition") A decorator that transforms a function into a [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") . This is similar to the [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.command "discord.ext.commands.command") decorator but the `cls` parameter is set to [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") by default. Changed in version 1.1: The `cls` parameter can now be passed. ### Command[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#command "Permalink to this headline") _class_ discord.ext.commands.Command(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "Permalink to this definition") Attributes * [aliases](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.aliases) * [brief](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.brief) * [callback](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.callback) * [checks](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks) * [clean\_params](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.clean_params) * [cog](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.cog) * [cog\_name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.cog_name) * [cooldown](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.cooldown) * [cooldown\_after\_parsing](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.cooldown_after_parsing) * [description](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.description) * [enabled](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.enabled) * [extras](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.extras) * [full\_parent\_name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.full_parent_name) * [help](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.help) * [hidden](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.hidden) * [ignore\_extra](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.ignore_extra) * [invoked\_subcommand](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.invoked_subcommand) * [name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.name) * [parent](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.parent) * [parents](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.parents) * [qualified\_name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.qualified_name) * [require\_var\_positional](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.require_var_positional) * [rest\_is\_raw](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.rest_is_raw) * [root\_parent](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.root_parent) * [short\_doc](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.short_doc) * [signature](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.signature) * [usage](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.usage) Methods * async[\_\_call\_\_](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.__call__) * def[add\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.add_check) * @[after\_invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.after_invoke) * @[before\_invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.before_invoke) * async[can\_run](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.can_run) * def[copy](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.copy) * @[error](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.error) * def[get\_cooldown\_retry\_after](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.get_cooldown_retry_after) * def[has\_error\_handler](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.has_error_handler) * def[is\_on\_cooldown](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.is_on_cooldown) * def[remove\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.remove_check) * def[reset\_cooldown](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.reset_cooldown) * def[update](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.update) A class that implements the protocol for a bot text command. These are not created manually, instead they are created via the decorator or functional interface. name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.name "Permalink to this definition") The name of the command. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") callback[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.callback "Permalink to this definition") The coroutine that is executed when the command is called. Type [coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") help[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.help "Permalink to this definition") The long help text for the command. Type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] brief[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.brief "Permalink to this definition") The short help text for the command. Type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] usage[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.usage "Permalink to this definition") A replacement for arguments in the default help text. Type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] aliases[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.aliases "Permalink to this definition") The list of aliases the command can be invoked under. Type Union\[List\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \], Tuple\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]\] enabled[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.enabled "Permalink to this definition") A boolean that indicates if the command is currently enabled. If the command is invoked while it is disabled, then [`DisabledCommand`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DisabledCommand "discord.ext.commands.DisabledCommand") is raised to the [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") event. Defaults to `True`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") parent[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.parent "Permalink to this definition") The parent group that this command belongs to. `None` if there isn’t one. Type Optional\[[`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] cog[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.cog "Permalink to this definition") The cog that this command belongs to. `None` if there isn’t one. Type Optional\[[`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog")\ \] checks[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks "Permalink to this definition") A list of predicates that verifies if the command could be executed with the given [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") as the sole parameter. If an exception is necessary to be thrown to signal failure, then one inherited from [`CommandError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") should be used. Note that if the checks fail then [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") exception is raised to the [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") event. Type List\[Callable\[\[[`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context")\ \], [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)")\ \]\] description[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.description "Permalink to this definition") The message prefixed into the default help command. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") hidden[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.hidden "Permalink to this definition") If `True`, the default help command does not show this in the help output. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") rest\_is\_raw[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.rest_is_raw "Permalink to this definition") If `False` and a keyword-only argument is provided then the keyword only argument is stripped and handled as if it was a regular argument that handles [`MissingRequiredArgument`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MissingRequiredArgument "discord.ext.commands.MissingRequiredArgument") and default values in a regular matter rather than passing the rest completely raw. If `True` then the keyword-only argument will pass in the rest of the arguments in a completely raw matter. Defaults to `False`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") invoked\_subcommand[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.invoked_subcommand "Permalink to this definition") The subcommand that was invoked, if any. Type Optional\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] require\_var\_positional[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.require_var_positional "Permalink to this definition") If `True` and a variadic positional argument is specified, requires the user to specify at least one argument. Defaults to `False`. New in version 1.5. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ignore\_extra[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.ignore_extra "Permalink to this definition") If `True`, ignores extraneous strings passed to a command if all its requirements are met (e.g. `?foo a b c` when only expecting `a` and `b`). Otherwise [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") and local error handlers are called with [`TooManyArguments`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.TooManyArguments "discord.ext.commands.TooManyArguments") . Defaults to `True`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") cooldown\_after\_parsing[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.cooldown_after_parsing "Permalink to this definition") If `True`, cooldown processing is done after argument parsing, which calls converters. If `False` then cooldown processing is done first and then the converters are called second. Defaults to `False`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") extras[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.extras "Permalink to this definition") A dict of user provided extras to attach to the Command. Note This object may be copied by the library. Type [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") New in version 2.0. @after\_invoke[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.after_invoke "Permalink to this definition") A decorator that registers a coroutine as a post-invoke hook. A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required. This post-invoke hook takes a sole parameter, a [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . See [`Bot.after_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.after_invoke "discord.ext.commands.Bot.after_invoke") for more info. Changed in version 2.0: `coro` parameter is now positional-only. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register as the post-invoke hook. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. @before\_invoke[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.before_invoke "Permalink to this definition") A decorator that registers a coroutine as a pre-invoke hook. A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required. This pre-invoke hook takes a sole parameter, a [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . See [`Bot.before_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.before_invoke "discord.ext.commands.Bot.before_invoke") for more info. Changed in version 2.0: `coro` parameter is now positional-only. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register as the pre-invoke hook. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. @error[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.error "Permalink to this definition") A decorator that registers a coroutine as a local error handler. A local error handler is an [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") event limited to a single command. However, the [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") is still invoked afterwards as the catch-all. Changed in version 2.0: `coro` parameter is now positional-only. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register as the local error handler. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. add\_check(_func_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.add_check "Permalink to this definition") Adds a check to the command. This is the non-decorator interface to [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") . New in version 1.3. Changed in version 2.0: `func` parameter is now positional-only. Parameters **func** – The function that will be used as a check. remove\_check(_func_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.remove_check "Permalink to this definition") Removes a check from the command. This function is idempotent and will not raise an exception if the function is not in the command’s checks. New in version 1.3. Changed in version 2.0: `func` parameter is now positional-only. Parameters **func** – The function to remove from the checks. update(_\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.update "Permalink to this definition") Updates [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") instance with updated attribute. This works similarly to the [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.command "discord.ext.commands.command") decorator in terms of parameters in that they are passed to the [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") or subclass constructors, sans the name and callback. _await_ \_\_call\_\_(_context_, _/_, _\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.__call__ "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Calls the internal callback that the command holds. Note This bypasses all mechanisms – including checks, converters, invoke hooks, cooldowns, etc. You must take care to pass the proper arguments and types to this function. New in version 1.3. Changed in version 2.0: `context` parameter is now positional-only. copy()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.copy "Permalink to this definition") Creates a copy of this command. Returns A new instance of this command. Return type [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") _property_ clean\_params[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.clean_params "Permalink to this definition") Dict\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , [`Parameter`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter "discord.ext.commands.Parameter")\ \]: Retrieves the parameter dictionary without the context or self parameters. Useful for inspecting signature. _property_ cooldown[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.cooldown "Permalink to this definition") The cooldown of a command when invoked or `None` if the command doesn’t have a registered cooldown. New in version 2.0. Type Optional\[[`Cooldown`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cooldown "discord.ext.commands.Cooldown")\ \] _property_ full\_parent\_name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.full_parent_name "Permalink to this definition") Retrieves the fully qualified parent command name. This the base command name required to execute it. For example, in `?one two three` the parent name would be `one two`. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _property_ parents[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.parents "Permalink to this definition") Retrieves the parents of this command. If the command has no parents then it returns an empty [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") . For example in commands `?a b c test`, the parents are `[c, b, a]`. New in version 1.1. Type List\[[`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] _property_ root\_parent[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.root_parent "Permalink to this definition") Retrieves the root parent of this command. If the command has no parents then it returns `None`. For example in commands `?a b c test`, the root parent is `a`. Type Optional\[[`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] _property_ qualified\_name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.qualified_name "Permalink to this definition") Retrieves the fully qualified command name. This is the full parent name with the command name as well. For example, in `?one two three` the qualified name would be `one two three`. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") is\_on\_cooldown(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.is_on_cooldown "Permalink to this definition") Checks whether the command is currently on cooldown. Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context to use when checking the commands cooldown status. Returns A boolean indicating if the command is on cooldown. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") reset\_cooldown(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.reset_cooldown "Permalink to this definition") Resets the cooldown on this command. Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context to reset the cooldown under. get\_cooldown\_retry\_after(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.get_cooldown_retry_after "Permalink to this definition") Retrieves the amount of seconds before this command can be tried again. New in version 1.4. Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context to retrieve the cooldown from. Returns The amount of time left on this command’s cooldown in seconds. If this is `0.0` then the command isn’t on cooldown. Return type [`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") has\_error\_handler()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.has_error_handler "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Checks whether the command has an error handler registered. New in version 1.7. _property_ cog\_name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.cog_name "Permalink to this definition") The name of the cog this command belongs to, if any. Type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] _property_ short\_doc[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.short_doc "Permalink to this definition") Gets the “short” documentation of a command. By default, this is the [`brief`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.brief "discord.ext.commands.Command.brief") attribute. If that lookup leads to an empty string then the first line of the [`help`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.help "discord.ext.commands.Command.help") attribute is used instead. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _property_ signature[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.signature "Permalink to this definition") Returns a POSIX-like signature useful for help command output. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _await_ can\_run(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.can_run "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Checks if the command can be executed by checking all the predicates inside the [`checks`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks "discord.ext.commands.Command.checks") attribute. This also checks whether the command is disabled. Changed in version 1.3: Checks whether the command is disabled or not Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The ctx of the command currently being invoked. Raises [**CommandError**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") – Any command error that was raised during a check call will be propagated by this function. Returns A boolean indicating if the command can be invoked. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ### Group[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#group "Permalink to this headline") _class_ discord.ext.commands.Group(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "Permalink to this definition") Attributes * [case\_insensitive](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.case_insensitive) * [clean\_params](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.clean_params) * [cog\_name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.cog_name) * [commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.commands) * [cooldown](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.cooldown) * [full\_parent\_name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.full_parent_name) * [invoke\_without\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.invoke_without_command) * [parents](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.parents) * [qualified\_name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.qualified_name) * [root\_parent](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.root_parent) * [short\_doc](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.short_doc) * [signature](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.signature) Methods * def[add\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.add_check) * def[add\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.add_command) * @[after\_invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.after_invoke) * @[before\_invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.before_invoke) * async[can\_run](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.can_run) * @[command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.command) * def[copy](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.copy) * @[error](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.error) * def[get\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.get_command) * def[get\_cooldown\_retry\_after](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.get_cooldown_retry_after) * @[group](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.group) * def[has\_error\_handler](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.has_error_handler) * def[is\_on\_cooldown](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.is_on_cooldown) * def[remove\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.remove_check) * def[remove\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.remove_command) * def[reset\_cooldown](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.reset_cooldown) * def[update](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.update) * def[walk\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.walk_commands) A class that implements a grouping protocol for commands to be executed as subcommands. This class is a subclass of [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") and thus all options valid in [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") are valid in here as well. invoke\_without\_command[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.invoke_without_command "Permalink to this definition") Indicates if the group callback should begin parsing and invocation only if no subcommand was found. Useful for making it an error handling function to tell the user that no subcommand was found or to have different functionality in case no subcommand was found. If this is `False`, then the group callback will always be invoked first. This means that the checks and the parsing dictated by its parameters will be executed. Defaults to `False`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") case\_insensitive[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.case_insensitive "Permalink to this definition") Indicates if the group’s commands should be case insensitive. Defaults to `False`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") @after\_invoke[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.after_invoke "Permalink to this definition") A decorator that registers a coroutine as a post-invoke hook. A post-invoke hook is called directly after the command is called. This makes it a useful function to clean-up database connections or any type of clean up required. This post-invoke hook takes a sole parameter, a [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . See [`Bot.after_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.after_invoke "discord.ext.commands.Bot.after_invoke") for more info. Changed in version 2.0: `coro` parameter is now positional-only. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register as the post-invoke hook. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. @before\_invoke[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.before_invoke "Permalink to this definition") A decorator that registers a coroutine as a pre-invoke hook. A pre-invoke hook is called directly before the command is called. This makes it a useful function to set up database connections or any type of set up required. This pre-invoke hook takes a sole parameter, a [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . See [`Bot.before_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.before_invoke "discord.ext.commands.Bot.before_invoke") for more info. Changed in version 2.0: `coro` parameter is now positional-only. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register as the pre-invoke hook. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. @command(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.command "Permalink to this definition") A shortcut decorator that invokes [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.command "discord.ext.commands.command") and adds it to the internal command list via [`add_command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.add_command "discord.ext.commands.GroupMixin.add_command") . Returns A decorator that converts the provided method into a Command, adds it to the bot, then returns it. Return type Callable\[…, [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] @error[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.error "Permalink to this definition") A decorator that registers a coroutine as a local error handler. A local error handler is an [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") event limited to a single command. However, the [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") is still invoked afterwards as the catch-all. Changed in version 2.0: `coro` parameter is now positional-only. Parameters **coro** ([coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)") ) – The coroutine to register as the local error handler. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The coroutine passed is not actually a coroutine. @group(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.group "Permalink to this definition") A shortcut decorator that invokes [`group()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.group "discord.ext.commands.group") and adds it to the internal command list via [`add_command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.add_command "discord.ext.commands.GroupMixin.add_command") . Returns A decorator that converts the provided method into a Group, adds it to the bot, then returns it. Return type Callable\[…, [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] copy()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.copy "Permalink to this definition") Creates a copy of this [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") . Returns A new instance of this group. Return type [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") add\_check(_func_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.add_check "Permalink to this definition") Adds a check to the command. This is the non-decorator interface to [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") . New in version 1.3. Changed in version 2.0: `func` parameter is now positional-only. Parameters **func** – The function that will be used as a check. add\_command(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.add_command "Permalink to this definition") Adds a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") into the internal list of commands. This is usually not called, instead the [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.command "discord.ext.commands.GroupMixin.command") or [`group()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.group "discord.ext.commands.GroupMixin.group") shortcut decorators are used instead. Changed in version 1.4: Raise [`CommandRegistrationError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandRegistrationError "discord.ext.commands.CommandRegistrationError") instead of generic [`ClientException`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientException "discord.ClientException") Changed in version 2.0: `command` parameter is now positional-only. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to add. Raises * [**CommandRegistrationError**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandRegistrationError "discord.ext.commands.CommandRegistrationError") – If the command or its alias is already registered by different command. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – If the command passed is not a subclass of [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") . _await_ can\_run(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.can_run "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Checks if the command can be executed by checking all the predicates inside the [`checks`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks "discord.ext.commands.Command.checks") attribute. This also checks whether the command is disabled. Changed in version 1.3: Checks whether the command is disabled or not Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The ctx of the command currently being invoked. Raises [**CommandError**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") – Any command error that was raised during a check call will be propagated by this function. Returns A boolean indicating if the command can be invoked. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") _property_ clean\_params[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.clean_params "Permalink to this definition") Dict\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , [`Parameter`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter "discord.ext.commands.Parameter")\ \]: Retrieves the parameter dictionary without the context or self parameters. Useful for inspecting signature. _property_ cog\_name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.cog_name "Permalink to this definition") The name of the cog this command belongs to, if any. Type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] _property_ commands[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.commands "Permalink to this definition") A unique set of commands without aliases that are registered. Type Set\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] _property_ cooldown[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.cooldown "Permalink to this definition") The cooldown of a command when invoked or `None` if the command doesn’t have a registered cooldown. New in version 2.0. Type Optional\[[`Cooldown`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cooldown "discord.ext.commands.Cooldown")\ \] _property_ full\_parent\_name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.full_parent_name "Permalink to this definition") Retrieves the fully qualified parent command name. This the base command name required to execute it. For example, in `?one two three` the parent name would be `one two`. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") get\_command(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.get_command "Permalink to this definition") Get a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") from the internal list of commands. This could also be used as a way to get aliases. The name could be fully qualified (e.g. `'foo bar'`) will get the subcommand `bar` of the group command `foo`. If a subcommand is not found then `None` is returned just as usual. Changed in version 2.0: `name` parameter is now positional-only. Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the command to get. Returns The command that was requested. If not found, returns `None`. Return type Optional\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] get\_cooldown\_retry\_after(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.get_cooldown_retry_after "Permalink to this definition") Retrieves the amount of seconds before this command can be tried again. New in version 1.4. Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context to retrieve the cooldown from. Returns The amount of time left on this command’s cooldown in seconds. If this is `0.0` then the command isn’t on cooldown. Return type [`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") has\_error\_handler()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.has_error_handler "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Checks whether the command has an error handler registered. New in version 1.7. is\_on\_cooldown(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.is_on_cooldown "Permalink to this definition") Checks whether the command is currently on cooldown. Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context to use when checking the commands cooldown status. Returns A boolean indicating if the command is on cooldown. Return type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") _property_ parents[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.parents "Permalink to this definition") Retrieves the parents of this command. If the command has no parents then it returns an empty [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") . For example in commands `?a b c test`, the parents are `[c, b, a]`. New in version 1.1. Type List\[[`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] _property_ qualified\_name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.qualified_name "Permalink to this definition") Retrieves the fully qualified command name. This is the full parent name with the command name as well. For example, in `?one two three` the qualified name would be `one two three`. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") remove\_check(_func_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.remove_check "Permalink to this definition") Removes a check from the command. This function is idempotent and will not raise an exception if the function is not in the command’s checks. New in version 1.3. Changed in version 2.0: `func` parameter is now positional-only. Parameters **func** – The function to remove from the checks. remove\_command(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.remove_command "Permalink to this definition") Remove a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") from the internal list of commands. This could also be used as a way to remove aliases. Changed in version 2.0: `name` parameter is now positional-only. Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the command to remove. Returns The command that was removed. If the name is not valid then `None` is returned instead. Return type Optional\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] reset\_cooldown(_ctx_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.reset_cooldown "Permalink to this definition") Resets the cooldown on this command. Changed in version 2.0: `ctx` parameter is now positional-only. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context to reset the cooldown under. _property_ root\_parent[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.root_parent "Permalink to this definition") Retrieves the root parent of this command. If the command has no parents then it returns `None`. For example in commands `?a b c test`, the root parent is `a`. Type Optional\[[`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] _property_ short\_doc[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.short_doc "Permalink to this definition") Gets the “short” documentation of a command. By default, this is the [`brief`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.brief "discord.ext.commands.Command.brief") attribute. If that lookup leads to an empty string then the first line of the [`help`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.help "discord.ext.commands.Command.help") attribute is used instead. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _property_ signature[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.signature "Permalink to this definition") Returns a POSIX-like signature useful for help command output. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") update(_\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.update "Permalink to this definition") Updates [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") instance with updated attribute. This works similarly to the [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.command "discord.ext.commands.command") decorator in terms of parameters in that they are passed to the [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") or subclass constructors, sans the name and callback. _for ... in_ walk\_commands()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.walk_commands "Permalink to this definition") An iterator that recursively walks through all commands and subcommands. Changed in version 1.4: Duplicates due to aliases are no longer returned Yields Union\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ , [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] – A command or group from the internal list of commands. ### GroupMixin[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#groupmixin "Permalink to this headline") _class_ discord.ext.commands.GroupMixin(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin "Permalink to this definition") Attributes * [all\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.all_commands) * [case\_insensitive](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.case_insensitive) * [commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.commands) Methods * def[add\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.add_command) * @[command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.command) * def[get\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.get_command) * @[group](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.group) * def[remove\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.remove_command) * def[walk\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.walk_commands) A mixin that implements common functionality for classes that behave similar to [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") and are allowed to register commands. all\_commands[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.all_commands "Permalink to this definition") A mapping of command name to [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") objects. Type [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") case\_insensitive[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.case_insensitive "Permalink to this definition") Whether the commands should be case insensitive. Defaults to `False`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") @command(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.command "Permalink to this definition") A shortcut decorator that invokes [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.command "discord.ext.commands.command") and adds it to the internal command list via [`add_command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.add_command "discord.ext.commands.GroupMixin.add_command") . Returns A decorator that converts the provided method into a Command, adds it to the bot, then returns it. Return type Callable\[…, [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] @group(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.group "Permalink to this definition") A shortcut decorator that invokes [`group()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.group "discord.ext.commands.group") and adds it to the internal command list via [`add_command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.add_command "discord.ext.commands.GroupMixin.add_command") . Returns A decorator that converts the provided method into a Group, adds it to the bot, then returns it. Return type Callable\[…, [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] _property_ commands[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.commands "Permalink to this definition") A unique set of commands without aliases that are registered. Type Set\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] add\_command(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.add_command "Permalink to this definition") Adds a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") into the internal list of commands. This is usually not called, instead the [`command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.command "discord.ext.commands.GroupMixin.command") or [`group()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.group "discord.ext.commands.GroupMixin.group") shortcut decorators are used instead. Changed in version 1.4: Raise [`CommandRegistrationError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandRegistrationError "discord.ext.commands.CommandRegistrationError") instead of generic [`ClientException`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.ClientException "discord.ClientException") Changed in version 2.0: `command` parameter is now positional-only. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to add. Raises * [**CommandRegistrationError**](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandRegistrationError "discord.ext.commands.CommandRegistrationError") – If the command or its alias is already registered by different command. * [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – If the command passed is not a subclass of [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") . remove\_command(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.remove_command "Permalink to this definition") Remove a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") from the internal list of commands. This could also be used as a way to remove aliases. Changed in version 2.0: `name` parameter is now positional-only. Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the command to remove. Returns The command that was removed. If the name is not valid then `None` is returned instead. Return type Optional\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] _for ... in_ walk\_commands()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.walk_commands "Permalink to this definition") An iterator that recursively walks through all commands and subcommands. Changed in version 1.4: Duplicates due to aliases are no longer returned Yields Union\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ , [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] – A command or group from the internal list of commands. get\_command(_name_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.GroupMixin.get_command "Permalink to this definition") Get a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") from the internal list of commands. This could also be used as a way to get aliases. The name could be fully qualified (e.g. `'foo bar'`) will get the subcommand `bar` of the group command `foo`. If a subcommand is not found then `None` is returned just as usual. Changed in version 2.0: `name` parameter is now positional-only. Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the command to get. Returns The command that was requested. If not found, returns `None`. Return type Optional\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] Cogs[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#cogs "Permalink to this headline") ----------------------------------------------------------------------------------------------------------------- ### Cog[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#cog "Permalink to this headline") _class_ discord.ext.commands.Cog(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "Permalink to this definition") Attributes * [description](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.description) * [qualified\_name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.qualified_name) Methods * cls[Cog.listener](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.listener) * def[bot\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.bot_check) * def[bot\_check\_once](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.bot_check_once) * async[cog\_after\_invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_after_invoke) * async[cog\_before\_invoke](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_before_invoke) * def[cog\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_check) * async[cog\_command\_error](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_command_error) * async[cog\_load](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_load) * async[cog\_unload](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_unload) * def[get\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.get_commands) * def[get\_listeners](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.get_listeners) * def[has\_error\_handler](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.has_error_handler) * def[walk\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.walk_commands) The base class that all cogs must inherit from. A cog is a collection of commands, listeners, and optional state to help group commands together. More information on them can be found on the [Cogs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/cogs.html#ext-commands-cogs) page. When inheriting from this class, the options shown in [`CogMeta`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CogMeta "discord.ext.commands.CogMeta") are equally valid here. get\_commands()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.get_commands "Permalink to this definition") Returns A [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") s that are defined inside this cog. Note This does not include subcommands. Return type List\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] _property_ qualified\_name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.qualified_name "Permalink to this definition") Returns the cog’s specified name, not the class name. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _property_ description[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.description "Permalink to this definition") Returns the cog’s description, typically the cleaned docstring. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _for ... in_ walk\_commands()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.walk_commands "Permalink to this definition") An iterator that recursively walks through this cog’s commands and subcommands. Yields Union\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ , [`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group")\ \] – A command or group from the cog. get\_listeners()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.get_listeners "Permalink to this definition") Returns a [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.14)") of (name, function) listener pairs that are defined in this cog. Returns The listeners defined in this cog. Return type List\[Tuple\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , [coroutine](https://docs.python.org/3/library/asyncio-task.html#coroutine "(in Python v3.14)")\ \]\] _classmethod_ listener(_name\=..._)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.listener "Permalink to this definition") A decorator that marks a function as a listener. This is the cog equivalent of [`Bot.listen()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.listen "discord.ext.commands.Bot.listen") . Parameters **name** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The name of the event being listened to. If not provided, it defaults to the function’s name. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – The function is not a coroutine function or a string was not passed as the name. has\_error\_handler()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.has_error_handler "Permalink to this definition") [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") : Checks whether the cog has an error handler. New in version 1.7. _await_ cog\_load()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_load "Permalink to this definition") This function _could be a_ [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A special method that is called when the cog gets loaded. Subclasses must replace this if they want special asynchronous loading behaviour. Note that the `__init__` special method does not allow asynchronous code to run inside it, thus this is helpful for setting up code that needs to be asynchronous. New in version 2.0. _await_ cog\_unload()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_unload "Permalink to this definition") This function _could be a_ [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A special method that is called when the cog gets removed. Subclasses must replace this if they want special unloading behaviour. Exceptions raised in this method are ignored during extension unloading. Changed in version 2.0: This method can now be a [coroutine](https://docs.python.org/3/glossary.html#term-coroutine "(in Python v3.14)") . bot\_check\_once(_ctx_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.bot_check_once "Permalink to this definition") A special method that registers as a [`Bot.check_once()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check_once "discord.ext.commands.Bot.check_once") check. This function **can** be a coroutine and must take a sole parameter, `ctx`, to represent the [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . bot\_check(_ctx_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.bot_check "Permalink to this definition") A special method that registers as a [`Bot.check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Bot.check "discord.ext.commands.Bot.check") check. This function **can** be a coroutine and must take a sole parameter, `ctx`, to represent the [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . cog\_check(_ctx_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_check "Permalink to this definition") A special method that registers as a [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") for every command and subcommand in this cog. This function **can** be a coroutine and must take a sole parameter, `ctx`, to represent the [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . _await_ cog\_command\_error(_ctx_, _error_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_command_error "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A special method that is called whenever an error is dispatched inside this cog. This is similar to [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") except only applying to the commands inside this cog. This **must** be a coroutine. Parameters * **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context where the error happened. * **error** ([`CommandError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") ) – The error that happened. _await_ cog\_before\_invoke(_ctx_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_before_invoke "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A special method that acts as a cog local pre-invoke hook. This is similar to [`Command.before_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.before_invoke "discord.ext.commands.Command.before_invoke") . This **must** be a coroutine. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context. _await_ cog\_after\_invoke(_ctx_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.cog_after_invoke "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A special method that acts as a cog local post-invoke hook. This is similar to [`Command.after_invoke()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.after_invoke "discord.ext.commands.Command.after_invoke") . This **must** be a coroutine. Parameters **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context. ### CogMeta[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#cogmeta "Permalink to this headline") _class_ discord.ext.commands.CogMeta(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CogMeta "Permalink to this definition") Attributes * [command\_attrs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CogMeta.command_attrs) * [description](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CogMeta.description) * [name](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CogMeta.name) A metaclass for defining a cog. Note that you should probably not use this directly. It is exposed purely for documentation purposes along with making custom metaclasses to intermix with other metaclasses such as the [`abc.ABCMeta`](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.14)") metaclass. For example, to create an abstract cog mixin class, the following would be done. content\_copy import abc class CogABCMeta(commands.CogMeta, abc.ABCMeta): pass class SomeMixin(metaclass\=abc.ABCMeta): pass class SomeCogMixin(SomeMixin, commands.Cog, metaclass\=CogABCMeta): pass Note When passing an attribute of a metaclass that is documented below, note that you must pass it as a keyword-only argument to the class creation like the following example: content\_copy class MyCog(commands.Cog, name\='My Cog'): pass name[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CogMeta.name "Permalink to this definition") The cog name. By default, it is the name of the class with no modification. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") description[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CogMeta.description "Permalink to this definition") The cog description. By default, it is the cleaned docstring of the class. New in version 1.6. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") command\_attrs[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CogMeta.command_attrs "Permalink to this definition") A list of attributes to apply to every command inside this cog. The dictionary is passed into the [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") options at `__init__`. If you specify attributes inside the command attribute in the class, it will override the one specified inside this attribute. For example: content\_copy class MyCog(commands.Cog, command\_attrs\=dict(hidden\=True)): @commands.command() async def foo(self, ctx): pass \# hidden -> True @commands.command(hidden\=False) async def bar(self, ctx): pass \# hidden -> False Type [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") Help Commands[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#help-commands "Permalink to this headline") ----------------------------------------------------------------------------------------------------------------------------------- ### HelpCommand[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#helpcommand "Permalink to this headline") _class_ discord.ext.commands.HelpCommand(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand "Permalink to this definition") Attributes * [cog](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.cog) * [command\_attrs](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_attrs) * [context](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.context) * [invoked\_with](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.invoked_with) * [show\_hidden](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.show_hidden) * [verify\_checks](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.verify_checks) Methods * def[add\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.add_check) * async[command\_callback](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_callback) * def[command\_not\_found](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_not_found) * async[filter\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.filter_commands) * def[get\_bot\_mapping](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_bot_mapping) * def[get\_command\_signature](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_command_signature) * def[get\_destination](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_destination) * def[get\_max\_size](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_max_size) * async[on\_help\_command\_error](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.on_help_command_error) * async[prepare\_help\_command](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.prepare_help_command) * def[remove\_check](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.remove_check) * def[remove\_mentions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.remove_mentions) * async[send\_bot\_help](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_bot_help) * async[send\_cog\_help](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_cog_help) * async[send\_command\_help](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_command_help) * async[send\_error\_message](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_error_message) * async[send\_group\_help](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_group_help) * def[subcommand\_not\_found](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.subcommand_not_found) The base implementation for help command formatting. Note Internally instances of this class are deep copied every time the command itself is invoked to prevent a race condition mentioned in [GH-2123](https://github.com/dolfies/discord.py-self/issues/2123) . This means that relying on the state of this class to be the same between command invocations would not work as expected. context[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.context "Permalink to this definition") The context that invoked this help formatter. This is generally set after the help command assigned, [`command_callback()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_callback "discord.ext.commands.HelpCommand.command_callback") , has been called. Type Optional\[[`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context")\ \] show\_hidden[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.show_hidden "Permalink to this definition") Specifies if hidden commands should be shown in the output. Defaults to `False`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") verify\_checks[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.verify_checks "Permalink to this definition") Specifies if commands should have their [`Command.checks`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks "discord.ext.commands.Command.checks") called and verified. If `True`, always calls [`Command.checks`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks "discord.ext.commands.Command.checks") . If `None`, only calls [`Command.checks`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks "discord.ext.commands.Command.checks") in a guild setting. If `False`, never calls [`Command.checks`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks "discord.ext.commands.Command.checks") . Defaults to `True`. Changed in version 1.7. Type Optional\[[`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)")\ \] command\_attrs[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_attrs "Permalink to this definition") A dictionary of options to pass in for the construction of the help command. This allows you to change the command behaviour without actually changing the implementation of the command. The attributes will be the same as the ones passed in the [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") constructor. Type [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.14)") add\_check(_func_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.add_check "Permalink to this definition") Adds a check to the help command. New in version 1.4. Changed in version 2.0: `func` parameter is now positional-only. Parameters **func** – The function that will be used as a check. remove\_check(_func_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.remove_check "Permalink to this definition") Removes a check from the help command. This function is idempotent and will not raise an exception if the function is not in the command’s checks. New in version 1.4. Changed in version 2.0: `func` parameter is now positional-only. Parameters **func** – The function to remove from the checks. get\_bot\_mapping()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_bot_mapping "Permalink to this definition") Retrieves the bot mapping passed to [`send_bot_help()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_bot_help "discord.ext.commands.HelpCommand.send_bot_help") . _property_ invoked\_with[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.invoked_with "Permalink to this definition") Similar to [`Context.invoked_with`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context.invoked_with "discord.ext.commands.Context.invoked_with") except properly handles the case where [`Context.send_help()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context.send_help "discord.ext.commands.Context.send_help") is used. If the help command was used regularly then this returns the [`Context.invoked_with`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context.invoked_with "discord.ext.commands.Context.invoked_with") attribute. Otherwise, if it the help command was called using [`Context.send_help()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context.send_help "discord.ext.commands.Context.send_help") then it returns the internal command name of the help command. Returns The command name that triggered this invocation. Return type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] get\_command\_signature(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_command_signature "Permalink to this definition") Retrieves the signature portion of the help page. Changed in version 2.0: `command` parameter is now positional-only. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to get the signature of. Returns The signature for the command. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") remove\_mentions(_string_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.remove_mentions "Permalink to this definition") Removes mentions from the string to prevent abuse. This includes `@everyone`, `@here`, member mentions and role mentions. Changed in version 2.0: `string` parameter is now positional-only. Returns The string with mentions removed. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _property_ cog[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.cog "Permalink to this definition") A property for retrieving or setting the cog for the help command. When a cog is set for the help command, it is as-if the help command belongs to that cog. All cog special methods will apply to the help command and it will be automatically unset on unload. To unbind the cog from the help command, you can set it to `None`. Returns The cog that is currently set for the help command. Return type Optional\[[`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog")\ \] command\_not\_found(_string_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_not_found "Permalink to this definition") This function _could be a_ [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A method called when a command is not found in the help command. This is useful to override for i18n. Defaults to `No command called {0} found.` Changed in version 2.0: `string` parameter is now positional-only. Parameters **string** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The string that contains the invalid command. Note that this has had mentions removed to prevent abuse. Returns The string to use when a command has not been found. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") subcommand\_not\_found(_command_, _string_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.subcommand_not_found "Permalink to this definition") This function _could be a_ [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A method called when a command did not have a subcommand requested in the help command. This is useful to override for i18n. Defaults to either: * `'Command "{command.qualified_name}" has no subcommands.'` * If there is no subcommand in the `command` parameter. * `'Command "{command.qualified_name}" has no subcommand named {string}'` * If the `command` parameter has subcommands but not one named `string`. Changed in version 2.0: `command` and `string` parameters are now positional-only. Parameters * **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command that did not have the subcommand requested. * **string** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The string that contains the invalid subcommand. Note that this has had mentions removed to prevent abuse. Returns The string to use when the command did not have the subcommand requested. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") _await_ filter\_commands(_commands_, _/_, _\*_, _sort\=False_, _key\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.filter_commands "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Returns a filtered list of commands and optionally sorts them. This takes into account the [`verify_checks`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.verify_checks "discord.ext.commands.HelpCommand.verify_checks") and [`show_hidden`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.show_hidden "discord.ext.commands.HelpCommand.show_hidden") attributes. Changed in version 2.0: `commands` parameter is now positional-only. Parameters * **commands** (Iterable\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \]) – An iterable of commands that are getting filtered. * **sort** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether to sort the result. * **key** (Optional\[Callable\[\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \], Any\]\]) – An optional key function to pass to [`sorted()`](https://docs.python.org/3/library/functions.html#sorted "(in Python v3.14)") that takes a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") as its sole parameter. If `sort` is passed as `True` then this will default as the command name. Returns A list of commands that passed the filter. Return type List\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \] get\_max\_size(_commands_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_max_size "Permalink to this definition") Returns the largest name length of the specified command list. Changed in version 2.0: `commands` parameter is now positional-only. Parameters **commands** (Sequence\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \]) – A sequence of commands to check for the largest size. Returns The maximum width of the commands. Return type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") get\_destination()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_destination "Permalink to this definition") Returns the [`Messageable`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable "discord.abc.Messageable") where the help command will be output. You can override this method to customise the behaviour. By default this returns the context’s channel. Returns The destination where the help command will be output. Return type [`abc.Messageable`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable "discord.abc.Messageable") _await_ send\_error\_message(_error_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_error_message "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Handles the implementation when an error happens in the help command. For example, the result of [`command_not_found()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_not_found "discord.ext.commands.HelpCommand.command_not_found") will be passed here. You can override this method to customise the behaviour. By default, this sends the error message to the destination specified by [`get_destination()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_destination "discord.ext.commands.HelpCommand.get_destination") . Note You can access the invocation context with [`HelpCommand.context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.context "discord.ext.commands.HelpCommand.context") . Changed in version 2.0: `error` parameter is now positional-only. Parameters **error** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The error message to display to the user. Note that this has had mentions removed to prevent abuse. _await_ on\_help\_command\_error(_ctx_, _error_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.on_help_command_error "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . The help command’s error handler, as specified by [Error Handling](https://discordpy-self.readthedocs.io/en/latest/ext/commands/commands.html#ext-commands-error-handler) . Useful to override if you need some specific behaviour when the error handler is called. By default this method does nothing and just propagates to the default error handlers. Changed in version 2.0: `ctx` and `error` parameters are now positional-only. Parameters * **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context. * **error** ([`CommandError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") ) – The error that was raised. _await_ send\_bot\_help(_mapping_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_bot_help "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Handles the implementation of the bot command page in the help command. This function is called when the help command is called with no arguments. It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use [`get_destination()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_destination "discord.ext.commands.HelpCommand.get_destination") to know where to send, as this is a customisation point for other users. You can override this method to customise the behaviour. Note You can access the invocation context with [`HelpCommand.context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.context "discord.ext.commands.HelpCommand.context") . Also, the commands in the mapping are not filtered. To do the filtering you will have to call [`filter_commands()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.filter_commands "discord.ext.commands.HelpCommand.filter_commands") yourself. Changed in version 2.0: `mapping` parameter is now positional-only. Parameters **mapping** (Mapping\[Optional\[[`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog")\ \], List\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \]\]) – A mapping of cogs to commands that have been requested by the user for help. The key of the mapping is the [`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") that the command belongs to, or `None` if there isn’t one, and the value is a list of commands that belongs to that cog. _await_ send\_cog\_help(_cog_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_cog_help "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Handles the implementation of the cog page in the help command. This function is called when the help command is called with a cog as the argument. It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use [`get_destination()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_destination "discord.ext.commands.HelpCommand.get_destination") to know where to send, as this is a customisation point for other users. You can override this method to customise the behaviour. Note You can access the invocation context with [`HelpCommand.context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.context "discord.ext.commands.HelpCommand.context") . To get the commands that belong to this cog see [`Cog.get_commands()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog.get_commands "discord.ext.commands.Cog.get_commands") . The commands returned not filtered. To do the filtering you will have to call [`filter_commands()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.filter_commands "discord.ext.commands.HelpCommand.filter_commands") yourself. Changed in version 2.0: `cog` parameter is now positional-only. Parameters **cog** ([`Cog`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cog "discord.ext.commands.Cog") ) – The cog that was requested for help. _await_ send\_group\_help(_group_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_group_help "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Handles the implementation of the group page in the help command. This function is called when the help command is called with a group as the argument. It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use [`get_destination()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_destination "discord.ext.commands.HelpCommand.get_destination") to know where to send, as this is a customisation point for other users. You can override this method to customise the behaviour. Note You can access the invocation context with [`HelpCommand.context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.context "discord.ext.commands.HelpCommand.context") . To get the commands that belong to this group without aliases see [`Group.commands`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group.commands "discord.ext.commands.Group.commands") . The commands returned not filtered. To do the filtering you will have to call [`filter_commands()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.filter_commands "discord.ext.commands.HelpCommand.filter_commands") yourself. Changed in version 2.0: `group` parameter is now positional-only. Parameters **group** ([`Group`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Group "discord.ext.commands.Group") ) – The group that was requested for help. _await_ send\_command\_help(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_command_help "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . Handles the implementation of the single command page in the help command. It should be noted that this method does not return anything – rather the actual message sending should be done inside this method. Well behaved subclasses should use [`get_destination()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_destination "discord.ext.commands.HelpCommand.get_destination") to know where to send, as this is a customisation point for other users. You can override this method to customise the behaviour. Note You can access the invocation context with [`HelpCommand.context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.context "discord.ext.commands.HelpCommand.context") . Showing Help There are certain attributes and methods that are helpful for a help command to show such as the following: * [`Command.help`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.help "discord.ext.commands.Command.help") * [`Command.brief`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.brief "discord.ext.commands.Command.brief") * [`Command.short_doc`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.short_doc "discord.ext.commands.Command.short_doc") * [`Command.description`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.description "discord.ext.commands.Command.description") * [`get_command_signature()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_command_signature "discord.ext.commands.HelpCommand.get_command_signature") There are more than just these attributes but feel free to play around with these to help you get started to get the output that you want. Changed in version 2.0: `command` parameter is now positional-only. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command that was requested for help. _await_ prepare\_help\_command(_ctx_, _command\=None_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.prepare_help_command "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A low level method that can be used to prepare the help command before it does anything. For example, if you need to prepare some state in your subclass before the command does its processing then this would be the place to do it. The default implementation does nothing. Note This is called _inside_ the help command callback body. So all the usual rules that happen inside apply here as well. Changed in version 2.0: `ctx` and `command` parameters are now positional-only. Parameters * **ctx** ([`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") ) – The invocation context. * **command** (Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The argument passed to the help command. _await_ command\_callback(_ctx_, _/_, _\*_, _command\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_callback "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . The actual implementation of the help command. It is not recommended to override this method and instead change the behaviour through the methods that actually get dispatched. * [`send_bot_help()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_bot_help "discord.ext.commands.HelpCommand.send_bot_help") * [`send_cog_help()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_cog_help "discord.ext.commands.HelpCommand.send_cog_help") * [`send_group_help()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_group_help "discord.ext.commands.HelpCommand.send_group_help") * [`send_command_help()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_command_help "discord.ext.commands.HelpCommand.send_command_help") * [`get_destination()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_destination "discord.ext.commands.HelpCommand.get_destination") * [`command_not_found()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.command_not_found "discord.ext.commands.HelpCommand.command_not_found") * [`subcommand_not_found()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.subcommand_not_found "discord.ext.commands.HelpCommand.subcommand_not_found") * [`send_error_message()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.send_error_message "discord.ext.commands.HelpCommand.send_error_message") * [`on_help_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.on_help_command_error "discord.ext.commands.HelpCommand.on_help_command_error") * [`prepare_help_command()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.prepare_help_command "discord.ext.commands.HelpCommand.prepare_help_command") Changed in version 2.0: `ctx` parameter is now positional-only. ### DefaultHelpCommand[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#defaulthelpcommand "Permalink to this headline") _class_ discord.ext.commands.DefaultHelpCommand(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand "Permalink to this definition") Attributes * [arguments\_heading](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.arguments_heading) * [commands\_heading](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.commands_heading) * [default\_argument\_description](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.default_argument_description) * [dm\_help](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.dm_help) * [dm\_help\_threshold](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.dm_help_threshold) * [indent](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.indent) * [no\_category](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.no_category) * [paginator](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.paginator) * [show\_parameter\_descriptions](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.show_parameter_descriptions) * [sort\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.sort_commands) * [width](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.width) Methods * def[add\_command\_arguments](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.add_command_arguments) * def[add\_command\_formatting](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.add_command_formatting) * def[add\_indented\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.add_indented_commands) * def[get\_command\_signature](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.get_command_signature) * def[get\_destination](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.get_destination) * def[get\_ending\_note](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.get_ending_note) * async[send\_pages](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.send_pages) * def[shorten\_text](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.shorten_text) The implementation of the default help command. This inherits from [`HelpCommand`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand "discord.ext.commands.HelpCommand") . It extends it with the following attributes. width[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.width "Permalink to this definition") The maximum number of characters that fit in a line. Defaults to 80. Type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") sort\_commands[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.sort_commands "Permalink to this definition") Whether to sort the commands in the output alphabetically. Defaults to `True`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") dm\_help[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.dm_help "Permalink to this definition") A tribool that indicates if the help command should DM the user instead of sending it to the channel it received it from. If the boolean is set to `True`, then all help output is DM’d. If `False`, none of the help output is DM’d. If `None`, then the bot will only DM when the help message becomes too long (dictated by more than [`dm_help_threshold`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.dm_help_threshold "discord.ext.commands.DefaultHelpCommand.dm_help_threshold") characters). Defaults to `False`. Type Optional\[[`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)")\ \] dm\_help\_threshold[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.dm_help_threshold "Permalink to this definition") The number of characters the paginator must accumulate before getting DM’d to the user if [`dm_help`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.dm_help "discord.ext.commands.DefaultHelpCommand.dm_help") is set to `None`. Defaults to 1000. Type Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \] indent[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.indent "Permalink to this definition") How much to indent the commands from a heading. Defaults to `2`. Type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") arguments\_heading[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.arguments_heading "Permalink to this definition") The arguments list’s heading string used when the help command is invoked with a command name. Useful for i18n. Defaults to `"Arguments:"`. Shown when [`show_parameter_descriptions`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.show_parameter_descriptions "discord.ext.commands.DefaultHelpCommand.show_parameter_descriptions") is `True`. New in version 2.0. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") show\_parameter\_descriptions[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.show_parameter_descriptions "Permalink to this definition") Whether to show the parameter descriptions. Defaults to `True`. Setting this to `False` will revert to showing the [`signature`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.signature "discord.ext.commands.Command.signature") instead. New in version 2.0. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") commands\_heading[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.commands_heading "Permalink to this definition") The command list’s heading string used when the help command is invoked with a category name. Useful for i18n. Defaults to `"Commands:"` Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") default\_argument\_description[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.default_argument_description "Permalink to this definition") The default argument description string used when the argument’s [`description`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter.description "discord.ext.commands.Parameter.description") is `None`. Useful for i18n. Defaults to `"No description given."` New in version 2.0. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") no\_category[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.no_category "Permalink to this definition") The string used when there is a command which does not belong to any category(cog). Useful for i18n. Defaults to `"No Category"` Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") paginator[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.paginator "Permalink to this definition") The paginator used to paginate the help command output. Type [`Paginator`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator "discord.ext.commands.Paginator") shorten\_text(_text_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.shorten_text "Permalink to this definition") [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") : Shortens text to fit into the [`width`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.width "discord.ext.commands.DefaultHelpCommand.width") . Changed in version 2.0: `text` parameter is now positional-only. get\_ending\_note()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.get_ending_note "Permalink to this definition") [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") : Returns help command’s ending note. This is mainly useful to override for i18n purposes. get\_command\_signature(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.get_command_signature "Permalink to this definition") Retrieves the signature portion of the help page. Calls [`get_command_signature()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_command_signature "discord.ext.commands.HelpCommand.get_command_signature") if [`show_parameter_descriptions`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.show_parameter_descriptions "discord.ext.commands.DefaultHelpCommand.show_parameter_descriptions") is `False` else returns a modified signature where the command parameters are not shown. New in version 2.0. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to get the signature of. Returns The signature for the command. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") add\_indented\_commands(_commands_, _/_, _\*_, _heading_, _max\_size\=None_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.add_indented_commands "Permalink to this definition") Indents a list of commands after the specified heading. The formatting is added to the [`paginator`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.paginator "discord.ext.commands.DefaultHelpCommand.paginator") . The default implementation is the command name indented by [`indent`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.indent "discord.ext.commands.DefaultHelpCommand.indent") spaces, padded to `max_size` followed by the command’s [`Command.short_doc`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.short_doc "discord.ext.commands.Command.short_doc") and then shortened to fit into the [`width`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.width "discord.ext.commands.DefaultHelpCommand.width") . Changed in version 2.0: `commands` parameter is now positional-only. Parameters * **commands** (Sequence\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \]) – A list of commands to indent for output. * **heading** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The heading to add to the output. This is only added if the list of commands is greater than 0. * **max\_size** (Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]) – The max size to use for the gap between indents. If unspecified, calls [`get_max_size()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_max_size "discord.ext.commands.HelpCommand.get_max_size") on the commands parameter. add\_command\_arguments(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.add_command_arguments "Permalink to this definition") Indents a list of command arguments after the [`arguments_heading`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.arguments_heading "discord.ext.commands.DefaultHelpCommand.arguments_heading") . The default implementation is the argument [`name`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter.name "discord.ext.commands.Parameter.name") indented by [`indent`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.indent "discord.ext.commands.DefaultHelpCommand.indent") spaces, padded to `max_size` using [`get_max_size()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand.get_max_size "discord.ext.commands.HelpCommand.get_max_size") followed by the argument’s [`description`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter.description "discord.ext.commands.Parameter.description") or [`default_argument_description`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.default_argument_description "discord.ext.commands.DefaultHelpCommand.default_argument_description") and then shortened to fit into the [`width`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.width "discord.ext.commands.DefaultHelpCommand.width") and then [`displayed_default`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Parameter.displayed_default "discord.ext.commands.Parameter.displayed_default") between () if one is present after that. New in version 2.0. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to list the arguments for. _await_ send\_pages()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.send_pages "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A helper utility to send the page output from [`paginator`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.paginator "discord.ext.commands.DefaultHelpCommand.paginator") to the destination. add\_command\_formatting(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.add_command_formatting "Permalink to this definition") A utility function to format the non-indented block of commands and groups. Changed in version 2.0: `command` parameter is now positional-only. Changed in version 2.0: [`add_command_arguments()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.add_command_arguments "discord.ext.commands.DefaultHelpCommand.add_command_arguments") is now called if [`show_parameter_descriptions`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.show_parameter_descriptions "discord.ext.commands.DefaultHelpCommand.show_parameter_descriptions") is `True`. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to format. get\_destination()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.DefaultHelpCommand.get_destination "Permalink to this definition") Returns the [`Messageable`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable "discord.abc.Messageable") where the help command will be output. You can override this method to customise the behaviour. By default this returns the context’s channel. Returns The destination where the help command will be output. Return type [`abc.Messageable`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable "discord.abc.Messageable") ### MinimalHelpCommand[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#minimalhelpcommand "Permalink to this headline") _class_ discord.ext.commands.MinimalHelpCommand(_\*args_, _\*\*kwargs_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand "Permalink to this definition") Attributes * [aliases\_heading](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.aliases_heading) * [commands\_heading](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.commands_heading) * [dm\_help](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.dm_help) * [dm\_help\_threshold](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.dm_help_threshold) * [no\_category](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.no_category) * [paginator](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.paginator) * [sort\_commands](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.sort_commands) Methods * def[add\_aliases\_formatting](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.add_aliases_formatting) * def[add\_bot\_commands\_formatting](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.add_bot_commands_formatting) * def[add\_command\_formatting](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.add_command_formatting) * def[add\_subcommand\_formatting](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.add_subcommand_formatting) * def[get\_command\_signature](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.get_command_signature) * def[get\_destination](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.get_destination) * def[get\_ending\_note](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.get_ending_note) * def[get\_opening\_note](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.get_opening_note) * async[send\_pages](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.send_pages) An implementation of a help command with minimal output. This inherits from [`HelpCommand`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.HelpCommand "discord.ext.commands.HelpCommand") . sort\_commands[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.sort_commands "Permalink to this definition") Whether to sort the commands in the output alphabetically. Defaults to `True`. Type [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") commands\_heading[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.commands_heading "Permalink to this definition") The command list’s heading string used when the help command is invoked with a category name. Useful for i18n. Defaults to `"Commands"` Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") aliases\_heading[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.aliases_heading "Permalink to this definition") The alias list’s heading string used to list the aliases of the command. Useful for i18n. Defaults to `"Aliases:"`. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") dm\_help[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.dm_help "Permalink to this definition") A tribool that indicates if the help command should DM the user instead of sending it to the channel it received it from. If the boolean is set to `True`, then all help output is DM’d. If `False`, none of the help output is DM’d. If `None`, then the bot will only DM when the help message becomes too long (dictated by more than [`dm_help_threshold`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.dm_help_threshold "discord.ext.commands.MinimalHelpCommand.dm_help_threshold") characters). Defaults to `False`. Type Optional\[[`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)")\ \] dm\_help\_threshold[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.dm_help_threshold "Permalink to this definition") The number of characters the paginator must accumulate before getting DM’d to the user if [`dm_help`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.dm_help "discord.ext.commands.MinimalHelpCommand.dm_help") is set to `None`. Defaults to 1000. Type Optional\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \] no\_category[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.no_category "Permalink to this definition") The string used when there is a command which does not belong to any category(cog). Useful for i18n. Defaults to `"No Category"` Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") paginator[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.paginator "Permalink to this definition") The paginator used to paginate the help command output. Type [`Paginator`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator "discord.ext.commands.Paginator") _await_ send\_pages()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.send_pages "Permalink to this definition") This function is a [_coroutine_](https://docs.python.org/3/library/asyncio-task.html#coroutine) . A helper utility to send the page output from [`paginator`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.paginator "discord.ext.commands.MinimalHelpCommand.paginator") to the destination. get\_opening\_note()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.get_opening_note "Permalink to this definition") Returns help command’s opening note. This is mainly useful to override for i18n purposes. The default implementation returns content\_copy Use \`{prefix}{command\_name} \[command\]\` for more info on a command. You can also use \`{prefix}{command\_name} \[category\]\` for more info on a category. Returns The help command opening note. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") get\_command\_signature(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.get_command_signature "Permalink to this definition") Retrieves the signature portion of the help page. Changed in version 2.0: `command` parameter is now positional-only. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to get the signature of. Returns The signature for the command. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") get\_ending\_note()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.get_ending_note "Permalink to this definition") Return the help command’s ending note. This is mainly useful to override for i18n purposes. The default implementation does nothing. Returns The help command ending note. Return type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") add\_bot\_commands\_formatting(_commands_, _heading_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.add_bot_commands_formatting "Permalink to this definition") Adds the minified bot heading with commands to the output. The formatting should be added to the [`paginator`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.paginator "discord.ext.commands.MinimalHelpCommand.paginator") . The default implementation is a bold underline heading followed by commands separated by an EN SPACE (U+2002) in the next line. Changed in version 2.0: `commands` and `heading` parameters are now positional-only. Parameters * **commands** (Sequence\[[`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command")\ \]) – A list of commands that belong to the heading. * **heading** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The heading to add to the line. add\_subcommand\_formatting(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.add_subcommand_formatting "Permalink to this definition") Adds formatting information on a subcommand. The formatting should be added to the [`paginator`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.paginator "discord.ext.commands.MinimalHelpCommand.paginator") . The default implementation is the prefix and the [`Command.qualified_name`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.qualified_name "discord.ext.commands.Command.qualified_name") optionally followed by an En dash and the command’s [`Command.short_doc`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.short_doc "discord.ext.commands.Command.short_doc") . Changed in version 2.0: `command` parameter is now positional-only. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to show information of. add\_aliases\_formatting(_aliases_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.add_aliases_formatting "Permalink to this definition") Adds the formatting information on a command’s aliases. The formatting should be added to the [`paginator`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.paginator "discord.ext.commands.MinimalHelpCommand.paginator") . The default implementation is the [`aliases_heading`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.aliases_heading "discord.ext.commands.MinimalHelpCommand.aliases_heading") bolded followed by a comma separated list of aliases. This is not called if there are no aliases to format. Changed in version 2.0: `aliases` parameter is now positional-only. Parameters **aliases** (Sequence\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – A list of aliases to format. add\_command\_formatting(_command_, _/_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.add_command_formatting "Permalink to this definition") A utility function to format commands and groups. Changed in version 2.0: `command` parameter is now positional-only. Parameters **command** ([`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") ) – The command to format. get\_destination()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MinimalHelpCommand.get_destination "Permalink to this definition") Returns the [`Messageable`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable "discord.abc.Messageable") where the help command will be output. You can override this method to customise the behaviour. By default this returns the context’s channel. Returns The destination where the help command will be output. Return type [`abc.Messageable`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.abc.Messageable "discord.abc.Messageable") ### Paginator[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#paginator "Permalink to this headline") _class_ discord.ext.commands.Paginator(_prefix\='\`\`\`'_, _suffix\='\`\`\`'_, _max\_size\=2000_, _linesep\='\\n'_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator "Permalink to this definition") Attributes * [linesep](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.linesep) * [max\_size](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.max_size) * [pages](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.pages) * [prefix](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.prefix) * [suffix](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.suffix) Methods * def[add\_line](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.add_line) * def[clear](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.clear) * def[close\_page](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.close_page) A class that aids in paginating code blocks for Discord messages. len(x) Returns the total number of characters in the paginator. prefix[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.prefix "Permalink to this definition") The prefix inserted to every page. e.g. three backticks, if any. Type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] suffix[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.suffix "Permalink to this definition") The suffix appended at the end of every page. e.g. three backticks, if any. Type Optional\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] max\_size[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.max_size "Permalink to this definition") The maximum amount of codepoints allowed in a page. Type [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") linesep[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.linesep "Permalink to this definition") The character string inserted between lines. e.g. a newline character. New in version 1.7. Type [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") clear()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.clear "Permalink to this definition") Clears the paginator to have no pages. add\_line(_line\=''_, _\*_, _empty\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.add_line "Permalink to this definition") Adds a line to the current page. If the line exceeds the [`max_size`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.max_size "discord.ext.commands.Paginator.max_size") then an exception is raised. Parameters * **line** ([`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)") ) – The line to add. * **empty** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Indicates if another empty line should be added. Raises [**RuntimeError**](https://docs.python.org/3/library/exceptions.html#RuntimeError "(in Python v3.14)") – The line was too big for the current [`max_size`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.max_size "discord.ext.commands.Paginator.max_size") . close\_page()[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.close_page "Permalink to this definition") Prematurely terminate a page. _property_ pages[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Paginator.pages "Permalink to this definition") Returns the rendered list of pages. Type List\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \] Enums[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#enums "Permalink to this headline") ------------------------------------------------------------------------------------------------------------------- _class_ discord.ext.commands.BucketType[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType "Permalink to this definition") Specifies a type of bucket for, e.g. a cooldown. default[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType.default "Permalink to this definition") The default bucket operates on a global basis. user[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType.user "Permalink to this definition") The user bucket operates on a per-user basis. guild[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType.guild "Permalink to this definition") The guild bucket operates on a per-guild basis. channel[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType.channel "Permalink to this definition") The channel bucket operates on a per-channel basis. member[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType.member "Permalink to this definition") The member bucket operates on a per-member basis. category[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType.category "Permalink to this definition") The category bucket operates on a per-category basis. role[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType.role "Permalink to this definition") The role bucket operates on a per-role basis. New in version 1.3. Checks[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#checks "Permalink to this headline") --------------------------------------------------------------------------------------------------------------------- @discord.ext.commands.check(_predicate_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "Permalink to this definition") A decorator that adds a check to the [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") or its subclasses. These checks could be accessed via [`Command.checks`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command.checks "discord.ext.commands.Command.checks") . These checks should be predicates that take in a single parameter taking a [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") . If the check returns a `False`\-like value then during invocation a [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") exception is raised and sent to the [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") event. If an exception should be thrown in the predicate then it should be a subclass of [`CommandError`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandError "discord.ext.commands.CommandError") . Any exception not subclassed from it will be propagated while those subclassed will be sent to [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") . A special attribute named `predicate` is bound to the value returned by this decorator to retrieve the predicate passed to the decorator. This allows the following introspection and chaining to be done: content\_copy def owner\_or\_permissions(\*\*perms): original \= commands.has\_permissions(\*\*perms).predicate async def extended\_check(ctx): if ctx.guild is None: return False return ctx.guild.owner\_id \== ctx.author.id or await original(ctx) return commands.check(extended\_check) Note The function returned by `predicate` is **always** a coroutine, even if the original function was not a coroutine. Changed in version 1.3: The `predicate` attribute was added. Examples Creating a basic check to see if the command invoker is you. content\_copy def check\_if\_it\_is\_me(ctx): return ctx.message.author.id \== 85309593344815104 @bot.command() @commands.check(check\_if\_it\_is\_me) async def only\_for\_me(ctx): await ctx.send('I know you!') Transforming common checks into its own decorator: content\_copy def is\_me(): def predicate(ctx): return ctx.message.author.id \== 85309593344815104 return commands.check(predicate) @bot.command() @is\_me() async def only\_me(ctx): await ctx.send('Only you!') Changed in version 2.0: `predicate` parameter is now positional-only. Parameters **predicate** (Callable\[\[[`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context")\ \], [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)")\ \]) – The predicate to check if the command should be invoked. @discord.ext.commands.check\_any(_\*checks_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check_any "Permalink to this definition") A [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") that is added that checks if any of the checks passed will pass, i.e. using logical OR. If all checks fail then [`CheckAnyFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckAnyFailure "discord.ext.commands.CheckAnyFailure") is raised to signal the failure. It inherits from [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") . Note The `predicate` attribute for this function **is** a coroutine. New in version 1.3. Parameters **\*checks** (Callable\[\[[`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context")\ \], [`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)")\ \]) – An argument list of checks that have been decorated with the [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") decorator. Raises [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.14)") – A check passed has not been decorated with the [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") decorator. Examples Creating a basic check to see if it’s the bot owner or the server owner: content\_copy def is\_guild\_owner(): def predicate(ctx): return ctx.guild is not None and ctx.guild.owner\_id \== ctx.author.id return commands.check(predicate) @bot.command() @commands.check\_any(commands.is\_owner(), is\_guild\_owner()) async def only\_for\_owners(ctx): await ctx.send('Hello mister owner!') @discord.ext.commands.has\_role(_item_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_role "Permalink to this definition") A [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") that is added that checks if the member invoking the command has the role specified via the name or ID specified. If a string is specified, you must give the exact name of the role, including caps and spelling. If an integer is specified, you must give the exact snowflake ID of the role. If the message is invoked in a private message context then the check will return `False`. This check raises one of two special exceptions, [`MissingRole`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MissingRole "discord.ext.commands.MissingRole") if the user is missing a role, or [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") if it is used in a private message. Both inherit from [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") . Changed in version 1.1: Raise [`MissingRole`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MissingRole "discord.ext.commands.MissingRole") or [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") instead of generic [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") Changed in version 2.0: `item` parameter is now positional-only. Parameters **item** (Union\[[`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ , [`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ \]) – The name or ID of the role to check. @discord.ext.commands.has\_permissions(_\*\*perms_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_permissions "Permalink to this definition") A [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") that is added that checks if the member has all of the permissions necessary. Note that this check operates on the current channel permissions, not the guild wide permissions. The permissions passed in must be exactly like the properties shown under [`discord.Permissions`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Permissions "discord.Permissions") . This check raises a special exception, [`MissingPermissions`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MissingPermissions "discord.ext.commands.MissingPermissions") that is inherited from [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") . Parameters **perms** – An argument list of permissions to check for. Example content\_copy @bot.command() @commands.has\_permissions(manage\_messages\=True) async def test(ctx): await ctx.send('You can manage messages.') @discord.ext.commands.has\_guild\_permissions(_\*\*perms_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_guild_permissions "Permalink to this definition") Similar to [`has_permissions()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_permissions "discord.ext.commands.has_permissions") , but operates on guild wide permissions instead of the current channel permissions. If this check is called in a DM context, it will raise an exception, [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") . New in version 1.3. @discord.ext.commands.has\_any\_role(_\*items_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_any_role "Permalink to this definition") A [`check()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.check "discord.ext.commands.check") that is added that checks if the member invoking the command has **any** of the roles specified. This means that if they have one out of the three roles specified, then this check will return `True`. Similar to [`has_role()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_role "discord.ext.commands.has_role") , the names or IDs passed in must be exact. This check raises one of two special exceptions, [`MissingAnyRole`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MissingAnyRole "discord.ext.commands.MissingAnyRole") if the user is missing all roles, or [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") if it is used in a private message. Both inherit from [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") . Changed in version 1.1: Raise [`MissingAnyRole`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MissingAnyRole "discord.ext.commands.MissingAnyRole") or [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") instead of generic [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") Parameters **items** (List\[Union\[[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.14)")\ , [`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)")\ \]\]) – An argument list of names or IDs to check that the member has roles wise. Example content\_copy @bot.command() @commands.has\_any\_role('Library Devs', 'Moderators', 492212595072434186) async def cool(ctx): await ctx.send('You are cool indeed') @discord.ext.commands.bot\_has\_role(_item_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.bot_has_role "Permalink to this definition") Similar to [`has_role()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_role "discord.ext.commands.has_role") except checks if the bot itself has the role. This check raises one of two special exceptions, [`BotMissingRole`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BotMissingRole "discord.ext.commands.BotMissingRole") if the bot is missing the role, or [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") if it is used in a private message. Both inherit from [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") . Changed in version 1.1: Raise [`BotMissingRole`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BotMissingRole "discord.ext.commands.BotMissingRole") or [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") instead of generic [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") Changed in version 2.0: `item` parameter is now positional-only. @discord.ext.commands.bot\_has\_permissions(_\*\*perms_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.bot_has_permissions "Permalink to this definition") Similar to [`has_permissions()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_permissions "discord.ext.commands.has_permissions") except checks if the bot itself has the permissions listed. This check raises a special exception, [`BotMissingPermissions`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BotMissingPermissions "discord.ext.commands.BotMissingPermissions") that is inherited from [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") . @discord.ext.commands.bot\_has\_guild\_permissions(_\*\*perms_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.bot_has_guild_permissions "Permalink to this definition") Similar to [`has_guild_permissions()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_guild_permissions "discord.ext.commands.has_guild_permissions") , but checks the bot members guild permissions. New in version 1.3. @discord.ext.commands.bot\_has\_any\_role(_\*items_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.bot_has_any_role "Permalink to this definition") Similar to [`has_any_role()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.has_any_role "discord.ext.commands.has_any_role") except checks if the bot itself has any of the roles listed. This check raises one of two special exceptions, [`BotMissingAnyRole`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BotMissingAnyRole "discord.ext.commands.BotMissingAnyRole") if the bot is missing all roles, or [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") if it is used in a private message. Both inherit from [`CheckFailure`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CheckFailure "discord.ext.commands.CheckFailure") . Changed in version 1.1: Raise [`BotMissingAnyRole`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BotMissingAnyRole "discord.ext.commands.BotMissingAnyRole") or [`NoPrivateMessage`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.NoPrivateMessage "discord.ext.commands.NoPrivateMessage") instead of generic checkfailure @discord.ext.commands.cooldown(_rate_, _per_, _type\=discord.ext.commands.BucketType.default_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.cooldown "Permalink to this definition") A decorator that adds a cooldown to a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") A cooldown allows a command to only be used a specific amount of times in a specific time frame. These cooldowns can be based either on a per-guild, per-channel, per-user, per-role or global basis. Denoted by the third argument of `type` which must be of enum type [`BucketType`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType "discord.ext.commands.BucketType") . If a cooldown is triggered, then [`CommandOnCooldown`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandOnCooldown "discord.ext.commands.CommandOnCooldown") is triggered in [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") and the local error handler. A command can only have a single cooldown. Parameters * **rate** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The number of times a command can be used before triggering a cooldown. * **per** ([`float`](https://docs.python.org/3/library/functions.html#float "(in Python v3.14)") ) – The amount of seconds to wait for a cooldown when it’s been triggered. * **type** (Union\[[`BucketType`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType "discord.ext.commands.BucketType")\ , Callable\[\[[`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context")\ \], Any\]\]) – The type of cooldown to have. If callable, should return a key for the mapping. Changed in version 1.7: Callables are now supported for custom bucket types. Changed in version 2.0: When passing a callable, it now needs to accept [`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context") rather than [`Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") as its only argument. @discord.ext.commands.dynamic\_cooldown(_cooldown_, _type_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.dynamic_cooldown "Permalink to this definition") A decorator that adds a dynamic cooldown to a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") This differs from [`cooldown()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.cooldown "discord.ext.commands.cooldown") in that it takes a function that accepts a single parameter of type [`discord.Message`](https://discordpy-self.readthedocs.io/en/latest/api.html#discord.Message "discord.Message") and must return a [`Cooldown`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cooldown "discord.ext.commands.Cooldown") or `None`. If `None` is returned then that cooldown is effectively bypassed. A cooldown allows a command to only be used a specific amount of times in a specific time frame. These cooldowns can be based either on a per-guild, per-channel, per-user, per-role or global basis. Denoted by the third argument of `type` which must be of enum type [`BucketType`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType "discord.ext.commands.BucketType") . If a cooldown is triggered, then [`CommandOnCooldown`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.CommandOnCooldown "discord.ext.commands.CommandOnCooldown") is triggered in [`on_command_error()`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.discord.ext.commands.on_command_error "discord.discord.ext.commands.on_command_error") and the local error handler. A command can only have a single cooldown. New in version 2.0. Parameters * **cooldown** (Callable\[\[[`Context`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Context "discord.ext.commands.Context")\ \], Optional\[[`Cooldown`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Cooldown "discord.ext.commands.Cooldown")\ \]\]) – A function that takes a message and returns a cooldown that will apply to this invocation or `None` if the cooldown should be bypassed. * **type** ([`BucketType`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType "discord.ext.commands.BucketType") ) – The type of cooldown to have. @discord.ext.commands.max\_concurrency(_number_, _per\=discord.ext.commands.BucketType.default_, _\*_, _wait\=False_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.max_concurrency "Permalink to this definition") A decorator that adds a maximum concurrency to a [`Command`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.Command "discord.ext.commands.Command") or its subclasses. This enables you to only allow a certain number of command invocations at the same time, for example if a command takes too long or if only one user can use it at a time. This differs from a cooldown in that there is no set waiting period or token bucket – only a set number of people can run the command. New in version 1.3. Parameters * **number** ([`int`](https://docs.python.org/3/library/functions.html#int "(in Python v3.14)") ) – The maximum number of invocations of this command that can be running at the same time. * **per** ([`BucketType`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.BucketType "discord.ext.commands.BucketType") ) – The bucket that this concurrency is based on, e.g. `BucketType.guild` would allow it to be used up to `number` times per guild. * **wait** ([`bool`](https://docs.python.org/3/library/functions.html#bool "(in Python v3.14)") ) – Whether the command should wait for the queue to be over. If this is set to `False` then instead of waiting until the command can run again, the command raises [`MaxConcurrencyReached`](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.MaxConcurrencyReached "discord.ext.commands.MaxConcurrencyReached") to its error handler. If this is set to `True` then the command waits until it can be executed. @discord.ext.commands.before\_invoke(_coro_)[¶](https://discordpy-self.readthedocs.io/en/latest/ext/commands/api.html#discord.ext.commands.before_invoke "Permalink to this definition") A decorator that registers a coroutine as a pre-invoke hook. This allows you to refer to one before invoke hook for several commands that do not have to be within the same cog. New in version 1.4. Changed in version 2.0: `coro` parameter is now positional-only. Example content\_copy async def record\_usage(ctx): print(ctx.author, 'used', ctx.command, 'at', ctx.message.created\_at) @bot.command() @commands.before\_invoke(record\_usage) async def who(ctx): \# Output: used who at