Bot Client#
- class interactions.client.bot.Client(token, cache_limits=None, intents=Intents.DEFAULT, shards=None, default_scope=None, presence=None, _logging=None, disable_sync=False, **kwargs)[source]#
A class representing the client connection to Discord’s gateway and API via. WebSocket and HTTP.
- Parameters:
token (str) – The token of the application for authentication and connection.
intents (Optional[Intents]) – Allows specific control of permissions the application has when connected. In order to use multiple intents, the
|
operator is recommended. Defaults toIntents.DEFAULT
.shards (Optional[List[Tuple[int]]]) – Dictates and controls the shards that the application connects under.
presence (Optional[ClientPresence]) – Sets an RPC-like presence on the application when connected to the Gateway.
default_scope (Optional[Union[int, Guild, List[int], List[Guild]]]) –
New in version 4.3.0.
Sets the default scope of all commands.
disable_sync (Optional[bool]) – Controls whether synchronization in the user-facing API should be automatic or not.
logging (Optional[Union[bool, logging.DEBUG, logging.INFO, logging.NOTSET, logging.WARNING, logging.ERROR, logging.CRITICAL]]) –
New in version 4.3.2.
Set to
True
to enable debug logging or set to a log level to use a specific level
- Variables:
me (Application) – The application representation of the client.
- async modify_nick_in_guild(guild_id, new_nick=<interactions.MISSING>)[source]#
New in version 4.4.0.
Sets a new nick in the specified guild.
- async wait_until_ready()[source]#
New in version 4.2.0.
Helper method that waits until the websocket is ready.
- event(coro=<interactions.MISSING>, *, name=<interactions.MISSING>)[source]#
A decorator for listening to events dispatched from the Gateway.
Documentation on how to listen to specific events can be found here.
- Parameters:
coro (Optional[Callable[..., Coroutine]]) – The coroutine of the event.
name (Optional[str]) – The name of the event. If not given, this defaults to the coroutine’s name.
- Returns:
A callable response.
- Return type:
Callable[…, Any]
- async change_presence(presence)[source]#
New in version 4.2.0.
A method that changes the current client’s presence on runtime.
Note
There is a ratelimit to using this method (5 per minute). As there’s no gateway ratelimiter yet, breaking this ratelimit will force your bot to disconnect.
- Parameters:
presence (ClientPresence) – The presence to change the bot to on identify.
- command(*, type=ApplicationCommandType.CHAT_INPUT, name=<interactions.MISSING>, description=<interactions.MISSING>, scope=<interactions.MISSING>, options=<interactions.MISSING>, name_localizations=<interactions.MISSING>, description_localizations=<interactions.MISSING>, default_member_permissions=<interactions.MISSING>, dm_permission=<interactions.MISSING>, default_scope=True)[source]#
A decorator for registering an application command to the Discord API, as well as being able to listen for
INTERACTION_CREATE
dispatched gateway events.The structure of a chat-input command:
@bot.command(name="command-name", description="this is a command.") async def command_name(ctx): ...
The
scope
kwarg field may also be used to designate the command in question applicable to a guild or set of guilds.To properly utilise the
default_member_permissions
kwarg, it requires OR’ing the permission values, similar to instantiating the client with Intents. For example:@bot.command(name="kick", description="Kick a user.", default_member_permissions=interactions.Permissions.BAN_MEMBERS | interactions.Permissions.KICK_MEMBERS) async def kick(ctx, user: interactions.Member): ...
Another example below for instance is an admin-only command:
@bot.command(name="sudo", description="this is an admin-only command.", default_member_permissions=interactions.Permissions.ADMINISTRATOR) async def sudo(ctx): ...
Note
If
default_member_permissions
is not given, this will default to anyone that is able to use the command.- Parameters:
type (Optional[Union[str, int, ApplicationCommandType]]) – The type of application command. Defaults to
ApplicationCommandType.CHAT_INPUT
.name (Optional[str]) – The name of the application command. This is required but kept optional to follow kwarg rules.
description (Optional[str]) – The description of the application command. This should be left blank if you are not using
CHAT_INPUT
.scope (Optional[Union[int, Guild, List[int], List[Guild]]]) – The “scope”/applicable guilds the application command applies to.
options (Optional[Union[Dict[str, Any], List[Dict[str, Any]], Option, List[Option]]]) – The “arguments”/options of an application command. This should be left blank if you are not using
CHAT_INPUT
.name_localizations (Optional[Dict[Union[str, Locale], str]]) –
New in version 4.2.0.
The dictionary of localization for the
name
field. This enforces the same restrictions as thename
field.description_localizations (Optional[Dict[Union[str, Locale], str]]) –
New in version 4.2.0.
The dictionary of localization for the
description
field. This enforces the same restrictions as thedescription
field.default_member_permissions (Optional[Union[int, Permissions]]) – The permissions bit value of
Permissions
. If not given, defaults toPermissions.USE_APPLICATION_COMMANDS
dm_permission (Optional[bool]) – The application permissions if executed in a Direct Message. Defaults to
True
.default_scope (Optional[bool]) –
New in version 4.3.0.
Whether the scope of the command is the default scope set in the client. Defaults to
True
.
- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Command]
- message_command(*, name=<interactions.MISSING>, scope=<interactions.MISSING>, name_localizations=<interactions.MISSING>, default_member_permissions=<interactions.MISSING>, dm_permission=<interactions.MISSING>, default_scope=True)[source]#
A decorator for registering a message context menu to the Discord API, as well as being able to listen for
INTERACTION_CREATE
dispatched gateway events.The structure of a message context menu:
@bot.message_command(name="Context menu name") async def context_menu_name(ctx): ...
The
scope
kwarg field may also be used to designate the command in question applicable to a guild or set of guilds.- Parameters:
name (Optional[str]) – The name of the application command.
scope (Optional[Union[int, Guild, List[int], List[Guild]]]) – The “scope”/applicable guilds the application command applies to. Defaults to
None
.name_localizations (Optional[Dict[Union[str, Locale], str]]) –
New in version 4.2.0.
The dictionary of localization for the
name
field. This enforces the same restrictions as thename
field.default_member_permissions (Optional[Union[int, Permissions]]) – The permissions bit value of
Permissions
. If not given, defaults toPermissions.USE_APPLICATION_COMMANDS
dm_permission (Optional[bool]) – The application permissions if executed in a Direct Message. Defaults to
True
.default_scope (Optional[bool]) –
New in version 4.3.0.
Whether the scope of the command is the default scope set in the client. Defaults to
True
.
- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Command]
- user_command(*, name=<interactions.MISSING>, scope=<interactions.MISSING>, name_localizations=<interactions.MISSING>, default_member_permissions=<interactions.MISSING>, dm_permission=<interactions.MISSING>, default_scope=True)[source]#
A decorator for registering a user context menu to the Discord API, as well as being able to listen for
INTERACTION_CREATE
dispatched gateway events.The structure of a user context menu:
@bot.user_command(name="Context menu name") async def context_menu_name(ctx): ...
The
scope
kwarg field may also be used to designate the command in question applicable to a guild or set of guilds.- Parameters:
name (Optional[str]) – The name of the application command.
scope (Optional[Union[int, Guild, List[int], List[Guild]]]) – The “scope”/applicable guilds the application command applies to. Defaults to
None
.name_localizations (Optional[Dict[Union[str, Locale], str]]) –
New in version 4.2.0.
The dictionary of localization for the
name
field. This enforces the same restrictions as thename
field.default_member_permissions (Optional[Union[int, Permissions]]) –
- Return type:
The permissions bit value of
Permissions
. If not given, defaults toPermissions.USE_APPLICATION_COMMANDS
:param Optional[bool] dm_permission: The application permissions if executed in a Direct Message. Defaults toTrue
. :param Optional[bool] default_scope:New in version 4.3.0.
Whether the scope of the command is the default scope set in the client. Defaults to
True
.- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Command]
- component(component)[source]#
A decorator for listening to
INTERACTION_CREATE
dispatched gateway events involving components.The structure for a component callback:
# Method 1 @bot.component(interactions.Button( style=interactions.ButtonStyle.PRIMARY, label="click me!", custom_id="click_me_button", )) async def button_response(ctx): ... # Method 2 @bot.component("custom_id") async def button_response(ctx): ...
The context of the component callback decorator inherits the same as of the command decorator.
- Parameters:
component (Union[str, Button, SelectMenu]) – The component you wish to callback for.
- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Callable[…, Coroutine]]
- autocomplete(command, name)[source]#
New in version 4.0.2.
A decorator for listening to
INTERACTION_CREATE
dispatched gateway events involving autocompletion fields.The structure for an autocomplete callback:
@bot.autocomplete(command="command_name", name="option_name") async def autocomplete_choice_list(ctx, user_input: str = ""): await ctx.populate([ interactions.Choice(...), interactions.Choice(...), ... ])
- Parameters:
command (Union[ApplicationCommand, int, str, Snowflake]) – The command, command ID, or command name with the option.
name (str) – The name of the option to autocomplete.
- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Callable[…, Coroutine]]
- modal(modal)[source]#
A decorator for listening to
INTERACTION_CREATE
dispatched gateway events involving modals.The structure for a modal callback:
@bot.modal(interactions.Modal( interactions.TextInput( style=interactions.TextStyleType.PARAGRAPH, custom_id="how_was_your_day_field", label="How has your day been?", placeholder="Well, so far...", ), )) async def modal_response(ctx, how_was_your_day_field: str): ...
The context of the modal callback decorator inherits the same as of the component decorator.
- load(name, package=None, *args, **kwargs)[source]#
New in version 4.1.0.
“Loads” an extension off of the current client by adding a new class which is imported from the library.
- Parameters:
- Returns:
The loaded extension.
- Return type:
Optional[Extension]
- remove(name, remove_commands=True, package=None)[source]#
New in version 4.1.0.
Removes an extension out of the current client from an import resolve.
- reload(name, package=None, remove_commands=True, *args, **kwargs)[source]#
New in version 4.1.0.
“Reloads” an extension off of current client from an import resolve.
Warning
This will remove and re-add application commands, counting towards your daily application command creation limit, as long as you have the
remove_commands
argument set toTrue
, which it is by default.- Parameters:
name (str) – The name of the extension
package (Optional[str]) – The package of the extension
remove_commands (Optional[bool]) – Whether to remove commands before reloading. Defaults to True
*args (tuple) – Optional arguments to pass to the extension
**kwargs (dict) – Optional keyword-only arguments to pass to the extension.
- Returns:
The reloaded extension.
- Return type:
Optional[Extension]
- async modify(username=<interactions.MISSING>, avatar=<interactions.MISSING>)[source]#
New in version 4.2.0.
Modify the bot user account settings.
- async request_guild_members(guild_id, limit=<interactions.MISSING>, query=<interactions.MISSING>, presences=<interactions.MISSING>, user_ids=<interactions.MISSING>, nonce=<interactions.MISSING>)[source]#
New in version 4.3.2.
Requests guild members via websocket.
- Parameters:
guild_id (Union[Guild, Snowflake, int, str]) – ID of the guild to get members for.
limit (Optional[int]) – Maximum number of members to send matching the ‘query’ parameter. Required when specifying ‘query’.
query (Optional[str]) – String that username starts with.
presences (Optional[bool]) – Used to specify if we want the presences of the matched members.
user_ids (Optional[Union[Snowflake, List[Snowflake]]]) – Used to specify which users you wish to fetch.
nonce (Optional[str]) – Nonce to identify the Guild Members Chunk response.
- async wait_for(name, check=None, timeout=None)[source]#
New in version 4.4.0.
Waits for an event once, and returns the result.
Unlike event decorators, this is not persistent, and can be used to only proceed in a command once an event happens.
- Parameters:
- Returns:
The value of the dispatched event
- Return type:
Any
- async wait_for_component(components=None, messages=None, check=None, timeout=None)[source]#
New in version 4.4.0.
Waits for a component to be interacted with, and returns the resulting context.
Note
If you are waiting for a select menu, you can find the selected values in
ctx.data.values
. Another possibility is using theClient.wait_for_select()
method.- Parameters:
components (Union[str, Button, SelectMenu, List[Union[str, Button, SelectMenu]]]) – The component(s) to wait for
messages (Union[Message, int, List[Union[Message, int]]]) – The message(s) to check for
check (Optional[Callable[[ComponentContext], Union[bool, Awaitable[bool]]]]) – A function or coroutine to call, which should return a truthy value if the data should be returned
timeout (float) – How long to wait for the event before raising an error
- Returns:
The ComponentContext of the dispatched event
- Return type:
- async wait_for_select(components=None, messages=None, check=None, timeout=None)[source]#
New in version 4.4.0.
Waits for a select menu to be interacted with, and returns the resulting context and a list of the selected values.
The method can be used like this:
ctx, values = await bot.wait_for_select(custom_id)
In this case
ctx
will be your normal context andvalues
will be a list ofstr
,Member
,User
,Channel
orRole
objects, depending on which select type you received.- Parameters:
components (Union[str, SelectMenu, List[Union[str, SelectMenu]]]) – The component(s) to wait for
messages (Union[Message, int, List[Union[Message, int]]]) – The message(s) to check for
check (Optional[Callable[[ComponentContext], Union[bool, Awaitable[bool]]]]) – A function or coroutine to call, which should return a truthy value if the data should be returned
timeout (float) – How long to wait for the event before raising an error
- Returns:
The ComponentContext and list of selections of the dispatched event
- Return type:
Tuple[ComponentContext, Union[List[str], List[Member], List[User], List[Channel], List[Role]]]
- async wait_for_modal(modals, check=None, timeout=None)[source]#
New in version 4.4.0.
Waits for a modal to be interacted with, and returns the resulting context and submitted data.
Note
This function returns both the context of the modal and the data the user input. The recommended way to use it is to do:
modal_ctx, fields = await bot.wait_for_modal(...)
Alternatively, to get the fields immediately, you can do:
modal_ctx, (field1, field2, ...) = await bot.wait_for_modal(...)
- Parameters:
modals (Union[Modal, str, List[Modal, str]]) – The modal(s) to wait for
check (Optional[Callable[[CommandContext], Union[bool, Awaitable[bool]]]]) – A function or coroutine to call, which should return a truthy value if the data should be returned
timeout (Optional[float]) – How long to wait for the event before raising an error
- Returns:
The context of the modal, followed by the data the user inputted
- Return type:
- class interactions.client.bot.Extension(client, *args, **kwargs)[source]#
New in version 4.1.0.
A class that allows you to represent “extensions” of your code, or essentially cogs that can be ran independent of the root file in an object-oriented structure.
The structure of an extension:
class CoolCode(interactions.Extension): def __init__(self, client): self.client = client @extension_user_command( name="User command in cog", ) async def cog_user_cmd(self, ctx): ... def setup(client): CoolCode(client)
- Return type:
- interactions.client.bot.extension_listener(self, coro=<interactions.MISSING>, *, name=<interactions.MISSING>)[source]#
A decorator for listening to events dispatched from the Gateway.
Documentation on how to listen to specific events can be found here.
- Parameters:
coro (Optional[Callable[..., Coroutine]]) – The coroutine of the event.
name (Optional[str]) – The name of the event. If not given, this defaults to the coroutine’s name.
- Returns:
A callable response.
- Return type:
Callable[…, Any]
- interactions.client.bot.extension_command(self, *, type=ApplicationCommandType.CHAT_INPUT, name=<interactions.MISSING>, description=<interactions.MISSING>, scope=<interactions.MISSING>, options=<interactions.MISSING>, name_localizations=<interactions.MISSING>, description_localizations=<interactions.MISSING>, default_member_permissions=<interactions.MISSING>, dm_permission=<interactions.MISSING>, default_scope=True)[source]#
A decorator for registering an application command to the Discord API, as well as being able to listen for
INTERACTION_CREATE
dispatched gateway events.The structure of a chat-input command:
@bot.command(name="command-name", description="this is a command.") async def command_name(ctx): ...
The
scope
kwarg field may also be used to designate the command in question applicable to a guild or set of guilds.To properly utilise the
default_member_permissions
kwarg, it requires OR’ing the permission values, similar to instantiating the client with Intents. For example:@bot.command(name="kick", description="Kick a user.", default_member_permissions=interactions.Permissions.BAN_MEMBERS | interactions.Permissions.KICK_MEMBERS) async def kick(ctx, user: interactions.Member): ...
Another example below for instance is an admin-only command:
@bot.command(name="sudo", description="this is an admin-only command.", default_member_permissions=interactions.Permissions.ADMINISTRATOR) async def sudo(ctx): ...
Note
If
default_member_permissions
is not given, this will default to anyone that is able to use the command.- Parameters:
type (Optional[Union[str, int, ApplicationCommandType]]) – The type of application command. Defaults to
ApplicationCommandType.CHAT_INPUT
.name (Optional[str]) – The name of the application command. This is required but kept optional to follow kwarg rules.
description (Optional[str]) – The description of the application command. This should be left blank if you are not using
CHAT_INPUT
.scope (Optional[Union[int, Guild, List[int], List[Guild]]]) – The “scope”/applicable guilds the application command applies to.
options (Optional[Union[Dict[str, Any], List[Dict[str, Any]], Option, List[Option]]]) – The “arguments”/options of an application command. This should be left blank if you are not using
CHAT_INPUT
.name_localizations (Optional[Dict[Union[str, Locale], str]]) –
New in version 4.2.0.
The dictionary of localization for the
name
field. This enforces the same restrictions as thename
field.description_localizations (Optional[Dict[Union[str, Locale], str]]) –
New in version 4.2.0.
The dictionary of localization for the
description
field. This enforces the same restrictions as thedescription
field.default_member_permissions (Optional[Union[int, Permissions]]) – The permissions bit value of
Permissions
. If not given, defaults toPermissions.USE_APPLICATION_COMMANDS
dm_permission (Optional[bool]) – The application permissions if executed in a Direct Message. Defaults to
True
.default_scope (Optional[bool]) –
New in version 4.3.0.
Whether the scope of the command is the default scope set in the client. Defaults to
True
.
- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Command]
- interactions.client.bot.extension_component(self, component)[source]#
A decorator for listening to
INTERACTION_CREATE
dispatched gateway events involving components.The structure for a component callback:
# Method 1 @bot.component(interactions.Button( style=interactions.ButtonStyle.PRIMARY, label="click me!", custom_id="click_me_button", )) async def button_response(ctx): ... # Method 2 @bot.component("custom_id") async def button_response(ctx): ...
The context of the component callback decorator inherits the same as of the command decorator.
- Parameters:
component (Union[str, Button, SelectMenu]) – The component you wish to callback for.
- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Callable[…, Coroutine]]
- interactions.client.bot.extension_modal(self, modal)[source]#
A decorator for listening to
INTERACTION_CREATE
dispatched gateway events involving modals.The structure for a modal callback:
@bot.modal(interactions.Modal( interactions.TextInput( style=interactions.TextStyleType.PARAGRAPH, custom_id="how_was_your_day_field", label="How has your day been?", placeholder="Well, so far...", ), )) async def modal_response(ctx, how_was_your_day_field: str): ...
The context of the modal callback decorator inherits the same as of the component decorator.
- interactions.client.bot.extension_autocomplete(self, command, name)[source]#
New in version 4.0.2.
A decorator for listening to
INTERACTION_CREATE
dispatched gateway events involving autocompletion fields.The structure for an autocomplete callback:
@bot.autocomplete(command="command_name", name="option_name") async def autocomplete_choice_list(ctx, user_input: str = ""): await ctx.populate([ interactions.Choice(...), interactions.Choice(...), ... ])
- Parameters:
command (Union[ApplicationCommand, int, str, Snowflake]) – The command, command ID, or command name with the option.
name (str) – The name of the option to autocomplete.
- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Callable[…, Coroutine]]
- interactions.client.bot.extension_user_command(self, *, name=<interactions.MISSING>, scope=<interactions.MISSING>, name_localizations=<interactions.MISSING>, default_member_permissions=<interactions.MISSING>, dm_permission=<interactions.MISSING>, default_scope=True)[source]#
A decorator for registering a user context menu to the Discord API, as well as being able to listen for
INTERACTION_CREATE
dispatched gateway events.The structure of a user context menu:
@bot.user_command(name="Context menu name") async def context_menu_name(ctx): ...
The
scope
kwarg field may also be used to designate the command in question applicable to a guild or set of guilds.- Parameters:
name (Optional[str]) – The name of the application command.
scope (Optional[Union[int, Guild, List[int], List[Guild]]]) – The “scope”/applicable guilds the application command applies to. Defaults to
None
.name_localizations (Optional[Dict[Union[str, Locale], str]]) –
New in version 4.2.0.
The dictionary of localization for the
name
field. This enforces the same restrictions as thename
field.default_member_permissions (Optional[Union[int, Permissions]]) –
- Return type:
The permissions bit value of
Permissions
. If not given, defaults toPermissions.USE_APPLICATION_COMMANDS
:param Optional[bool] dm_permission: The application permissions if executed in a Direct Message. Defaults toTrue
. :param Optional[bool] default_scope:New in version 4.3.0.
Whether the scope of the command is the default scope set in the client. Defaults to
True
.- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Command]
- interactions.client.bot.extension_message_command(self, *, name=<interactions.MISSING>, scope=<interactions.MISSING>, name_localizations=<interactions.MISSING>, default_member_permissions=<interactions.MISSING>, dm_permission=<interactions.MISSING>, default_scope=True)[source]#
A decorator for registering a message context menu to the Discord API, as well as being able to listen for
INTERACTION_CREATE
dispatched gateway events.The structure of a message context menu:
@bot.message_command(name="Context menu name") async def context_menu_name(ctx): ...
The
scope
kwarg field may also be used to designate the command in question applicable to a guild or set of guilds.- Parameters:
name (Optional[str]) – The name of the application command.
scope (Optional[Union[int, Guild, List[int], List[Guild]]]) – The “scope”/applicable guilds the application command applies to. Defaults to
None
.name_localizations (Optional[Dict[Union[str, Locale], str]]) –
New in version 4.2.0.
The dictionary of localization for the
name
field. This enforces the same restrictions as thename
field.default_member_permissions (Optional[Union[int, Permissions]]) – The permissions bit value of
Permissions
. If not given, defaults toPermissions.USE_APPLICATION_COMMANDS
dm_permission (Optional[bool]) – The application permissions if executed in a Direct Message. Defaults to
True
.default_scope (Optional[bool]) –
New in version 4.3.0.
Whether the scope of the command is the default scope set in the client. Defaults to
True
.
- Returns:
A callable response.
- Return type:
Callable[[Callable[…, Coroutine]], Command]