Event Documentation#
You all probably already know that there are several events, internal and from Discord, that you can receive with your bot. This page will lead you through all dispatched internal events and a few from Discord.
How to listen for events#
Generally, you can listen to an event like this:
import interactions
bot = interactions.Client(...)
# possibility 1
@bot.event
async def on_xxx(...):
... # do smth
# possibility 2
@bot.event(name="on_xxx")
async def you_are_free_to_name_this_as_you_want(...):
... # do smth
bot.start()
xxx
represents the Discord event name - but with lowercase characters and any spaces replaced with _
.
For example:
READY
->on_ready
GUILD MEMBER ADD
->on_guild_member_add
(...)
represents the different arguments a function takes. Those arguments differ per event.
Now, let us have a look at different events and how they work, starting with internal events.
Internal Events#
All events mentioned in this section have the exact naming as they must be put into the function.
There are several different internal events:
raw_socket_create
on_start
on_interaction
on_command
on_command_error
on_component
on_autocomplete
on_modal
Lets now have a look at those events in detail:
Event: raw_socket_create
#
This event fires on any event sent by Discord, including Typing Start
and Voice State Update
.
Hello
, Resumed
, Reconnect
and Invalid Session
still will not be dispatched.
A function handling an event should take two arguments,
the first argument is the name of the event, the second is the data of that event with type dict
.
The value of the second argument will be the raw data sent from Discord, so it is not recommended to use that event as long as you don’t absolutely need it.
Event: on_start
#
This event fires only when the bot is started.
This function takes no arguments.
Attention
Unlike on_ready
, this event will never be dispatched more than once.
Event: on_interaction
#
This event fires on any interaction (commands, components, autocomplete and modals).
The function needs one argument. It will have the type CommandContext
or ComponentContext
.
Because you will have to check for everything, from the InteractionType
to any data inside the context, we do not
recommend using this event unless you have experience with it.
Event: on_command
#
This event fires on any Application Command (slash command + context menu command) used.
The function takes in one argument of the type CommandContext
.
Using this event, you will have to manually check everything, from name to whether the used commands have sub commands, options or anything else - everything will be in the raw context and you will have to search for it
Event: on_command_error
#
This event fires when the following conditions are met:
There is an error in the command (or subcommand within the command)
There is no error callback assigned to that command
The function takes in two arguments, one of the type CommandContext
, and the other contains the error.
Event: on_component
#
This event fires on any Component used (for now, those are Buttons and Select Menus).
The function takes in one argument of the type ComponentContext
.
Like on_command
, you will have to manually check for everything, i.e for custom id and component type.
Also, you will have to look through the argument to find the selected choices, if you have a select menu.
Event: on_autocomplete
#
This event fires on any autocomplete triggered.
The function takes in one argument of the type CommandContext
.
As already in the events above, you will have to get the important values yourself. Those values are here the autocompleted option and the user input.
Event: on_modal
#
This event fires on every modal that is submitted.
The function takes in one argument of the type CommandContext
.
You will have to get all values yourself and check what modal was used when using this event.
After this, let us look at events from the Discord API.
Discord API Events#
Events in this section do not match the name needed to put into the function. Please check above for how to get the correct name.
There are a lot of events dispatched by the Discord API. All of those can be found here.
The events HELLO
, RESUMED
, RECONNECT
, INVALID SESSION
and TYPING START
are not dispatched by the library.
TYPING START
will be included in the raw socket create event. You can
also listen for it if you choose to subclass the WebSocketClient
The event VOICE STATE UPDATE
can be only received with the voice extension.
Let’s now have a look at a few events:
Event: READY
#
This event fires whenever READY
is dispatched by Discord. This happens when connecting to the web socket server.
This function takes no arguments.
Attention
Due to the bot reconnecting during runtime, on_ready
will be dispatched multiple times. If you rely on
on_ready
to do certain things once, check against a global variable as shown below:
_ready: bool = False
bot = interactions.Client(...)
@bot.event
async def on_ready():
global _ready
if not _ready:
... # do stuff
_ready = True
Events: GUILD MEMBER UPDATE
and GUILD MEMBER ADD
#
These events fire whenever a member joins a guild or a member of a guild gets modified.
The function takes in one argument of the type GuildMember
.
The argument has the same methods as a normal Member
object, except the methods do not take in a guild id.
Please keep that in mind when using this event.