Events API Reference

Qord implements a rich interface for handling the events sent by Discord over gateway. These events are generally used to track the state of various entities.

The recommended way to register an event listener, is to use the qord.Client.event() decorator to decorate the callback coroutine. Example:

@client.event(qord.GatewayEvent.MESSAGE_CREATE)
async def on_message_create(event):
    pass

All event listeners must take a single event parameter that is an instance of qord.BaseEvent and represents the context of event and contains data relevant to the invoked event.

The qord.GatewayEvent enumeration details the event names that are sent over gateway.

Note

Toggling certain Intents flags will also disable or enable related events to that intent for your bot. It is recommended to keep at least the Intents.guilds intent enabled for proper functioning of library.

Custom events

Custom events are useful for several use cases and library allows you to create them and easily invoke them:

from qord import events
from dataclasses import dataclass

# For `event_name` parameter, make sure not to use an existing
# event name reserved by the library.

@dataclass
class ApplicationSubmit(events.BaseEvent, event_name="application_submit"):
    id: int
    name: str

@client.event("application_submit")
async def on_application_submit(event):
    print("Application submitted.")
    print(f"Name: {event.name}")
    print(f"ID: {event.id}")

You can then invoke the event somewhere else:

event = ApplicationSubmit(id=1, name="Jake")
client.invoke_event(event)

Events Structures

These classes define the structures of various events that are sent over Discord gateway.

BaseEvent

class qord.events.BaseEvent

Base class for events.

All custom events must inherit from this class. When subclassing the event_name parameter is required.

Note

Parameters documented below are passed during subclassing.

Parameters

event_name (builtins.str) –

The string representation of name of event. This is used for identifying the event and must be unique.

Warning

Do not use event names that are already reserved by the library for example the event names from GatewayEvent.

BaseGatewayEvent

class qord.events.BaseGatewayEvent

A typing.Protocol that details events sent over the gateway.

This protocol supports runtime checks like isinstance() or issubclass() etc.

shard: Optional[Shard]

The shard that received this event over gateway.

This attribute can be None in events that are not shard specific and are not invoked by a shard. The most common example is events.Ready.

GatewayDispatch

class qord.events.GatewayDispatch

Structure of a GATEWAY_DISPATCH event.

This event is called whenever gateway sends an event dispatch.

This event purely exists for debugging and experimental purposes and should not generally be used. This event will also call for dispatch events that are not supported by the library.

This event is only called when debug_events parameter is enabled in Client.

title: str

The title/name of event.

This name isn’t same as how library defines the events name. See Discord documentation for all events names.

https://discord.dev/topics/gateway#commands-and-events

data: Optional[Dict[str, Any]] = None

The raw event data.

This is mostly raw JSON payload however for some events, This can be None.

ShardReady

class qord.events.ShardReady

Structure of a SHARD_READY event.

This event is called whenever a shard successfully establishes a connection with Discord gateway and lazy loads cache for all guilds associated to that shard.

Ready

class qord.events.Ready

Structure of a READY event.

This event is called when all shards associated to the client have completely prepared their guilds cache and client is in ready state.

This event is not shard specific as such shard is always None.

Resumed

class qord.events.Resumed

Structure of a RESUMED event.

This event is called whenver a shard is resumed i.e successfully re-establishes a previously disconnected session.

shard: Shard

The shard that was resumed.

UserUpdate

class qord.events.UserUpdate

Structure for USER_UPDATE event.

This event is called whenever one or more properties of a user are updated.

before: User

The user before the update.

after: User

The user after the update.

GuildAvailable

class qord.events.GuildAvailable

Structure for GUILD_AVAILABLE event.

This event is called whenever a guild becomes available to the client. When initially connecting, This event may call several times for lazy loading of client guilds.

This event requires the guilds to be enabled. This intent is enabled by default.

guild: Guild

The guild that became available.

GuildUnavailable

class qord.events.GuildUnavailable

Structure for GUILD_UNAVAILABLE event.

This event is called whenever a guild becomes unavailable to the client most likely due to an outage.

This event requires the guilds to be enabled. This intent is enabled by default.

guild: Guild

The guild that became unavailable.

GuildJoin

class qord.events.GuildJoin

Structure for GUILD_JOIN event.

This event is called whenever the client user or bot joins a new guild.

This event requires the guilds to be enabled. This intent is enabled by default.

guild: Guild

The joined guild.

GuildLeave

class qord.events.GuildLeave

Structure for GUILD_LEAVE event.

This event is called whenever the client user or bot is removed (kicked, banned or simply left) from a guild.

This event requires the guilds to be enabled. This intent is enabled by default.

guild: Guild

The left guild.

GuildUpdate

class qord.events.GuildUpdate

Structure for GUILD_UPDATE event.

This event is called whenever one or more properties of a guild are updated.

This event requires the guilds to be enabled. This intent is enabled by default.

before: Guild

The copy of guild before the update.

after: Guild

The guild after the update.

RoleCreate

class qord.events.RoleCreate

Structure for ROLE_CREATE event.

This event is called whenever a role is created in a guild.

This event requires the guilds to be enabled. This intent is enabled by default.

role: Role

The role that was created.

guild: Guild

The guild that the created role belonged to.

RoleUpdate

class qord.events.RoleUpdate

Structure for ROLE_UPDATE event.

This event is called whenever one or more properties of a guild role are updated.

This event requires the guilds to be enabled. This intent is enabled by default.

before: Role

The role before the update.

after: Role

The role after the update.

guild: Guild

The guild that the updated role belonged to.

RoleDelete

class qord.events.RoleDelete

Structure for ROLE_DELETE event.

This event is called whenever a role is deleted in a guild.

This event requires the guilds to be enabled. This intent is enabled by default.

role: Role

The deleted role.

guild: Guild

The guild that the updated role belonged to.

GuildMemberAdd

class qord.events.GuildMemberAdd

Structure for GUILD_MEMBER_ADD event.

This event is called whenever a new member joins the guild.

This event requires the privileged intent, members to be enabled.

member: GuildMember

The member that joined the guild.

guild: Guild

The guild that was joined by the member.

GuildMemberUpdate

class qord.events.GuildMemberUpdate

Structure for GUILD_MEMBER_UPDATE event.

This event is called whenever a guild member is updated.

This event requires the privileged intent, members to be enabled.

before: GuildMember

The member before the update.

after: GuildMember

The member after the update.

guild: Guild

The associated guild.

GuildMemberRemove

class qord.events.GuildMemberRemove

Structure for GUILD_MEMBER_REMOVE event.

This event is called whenever a member is removed from the guild. The removal may be in form of leaving, getting kicked or banned etc.

This event requires the privileged intent, members to be enabled.

member: GuildMember

The member that had left the guild.

guild: Guild

The guild that was left by the member.

ChannelCreate

class qord.events.ChannelCreate

Structure for CHANNEL_CREATE event.

This event is called whenever a new channel is created in a guild.

Requires the guilds intents to be enabled. This intent is enabled by default.

channel: GuildChannel

The channel that was created.

guild: Guild

The guild where the event happened.

ChannelUpdate

class qord.events.ChannelUpdate

Structure for CHANNEL_UPDATE event.

This event is called whenever one or more properties of a guild channel are updated.

Requires the guilds intents to be enabled. This intent is enabled by default.

before: GuildChannel

The channel before the update.

after: GuildChannel

The channel after the update.

guild: Guild

The guild that the updated channel belonged to.

ChannelPinsUpdate

class qord.events.ChannelPinsUpdate

Structure for CHANNEL_PINS_UPDATE event.

This event is called whenever a message is pinned or unpinned in a channel. This event is not called if a pinned message is deleted.

Requires the guilds intents to be enabled. This intent is enabled by default.

channel: MessageableT

The channel whose pins were updated.

guild: Optional[Guild]

The guild where the event happened; If applicable otherwise None.

ChannelDelete

class qord.events.ChannelDelete

Structure for CHANNEL_DELETE event.

This event is called whenever a channel is deleted in a guild.

Requires the guilds intents to be enabled. This intent is enabled by default.

channel: GuildChannel

The channel that was deleted.

guild: Guild

The guild that the delete channel belonged to.

TypingStart

class qord.events.TypingStart

Structure for TYPING_START event.

This event is called whenever a user starts typing in a channel.

Requires the guild_message_typing intents to be enabled for guild typing events and direct_message_typing for DM typing events. These intents are enabled by default.

channel: MessageableT

The channel in which typing started in.

started_at: datetime

The time when the typing started.

user: Union[User, GuildMember]

The user or member that started typing.

If the event happened in a guild, This is GuildMember otherwise it is a User.

guild: Optional[Guild]

The guild in which typing started in if any.

EmojisUpdate

class qord.events.EmojisUpdate

Structure for EMOJIS_UPDATE event.

This event is called whenever emojis are updated in a guild i.e a new emoji is created, an emoji is deleted or updated.

This requires Intents.emojis_and_stickers to be enabled.

guild: Guild

The guild whose emojis were updated.

before: List[Emoji]

The list of emojis before the update.

after: List[Emoji]

The list of emojis after the update.

MessageCreate

class qord.events.MessageCreate

Structure for MESSAGE_CREATE event.

This event is called whenever a new message is sent in a guild or private channel.

This event requires the guild_messages and direct_messages intents enabled for guild and DM message events respectively. These intents are enabled by default.

message: Message

The message that was sent.

MessageUpdate

class qord.events.MessageUpdate

Structure for MESSAGE_UPDATE event.

This event is called whenever a message is updated aka edited.

This event requires the guild_messages and direct_messages intents enabled for guild and DM message events respectively. These intents are enabled by default.

before: Message

The message that was edited, before the edit happened.

after: Message

The message that was edited, after the edit happened.

MessageDelete

class qord.events.MessageDelete

Structure for MESSAGE_DELETE event.

This event is called whenever a message is deleted.

This event requires the guild_messages and direct_messages intents enabled for guild and DM message events respectively. These intents are enabled by default.

message: Message

The message that was deleted.

MessageBulkDelete

class qord.events.MessageBulkDelete

Structure for MESSAGE_BULK_DELETE event.

This event is called whenever multiple messages are deleted at the same time in a channel.

This event requires the guild_messages and direct_messages intents enabled for guild and DM message events respectively. These intents are enabled by default.

messages: List[Message]

The list of messages that were deleted.

This list only includes messages that could be resolved from the bot’s cache and may not include all messages that were deleted. You should use message_ids to get the IDs of all the messages deleted however do note that you cannot fetch those messages as they have been deleted.

channel: MessageableT

The channel in which messages were bulk deleted.

guild: Optional[Guild]

The relevant guild if any, None if the bulk delete happened in DMs.

message_ids: List[int]

The list of IDs of messages that were deleted.

ReactionAdd

class qord.events.ReactionAdd

Structure for REACTION_ADD event.

This event is called whenever a reaction is added on a message.

This requires Intents.guild_message_reactions or Intents.direct_message_reactions to be enabled for guilds and direct messages respectively.

message: Message

The message on which reaction was added.

reaction: Reaction

The added reaction.

user: Union[User, GuildMember]

The user who added the reaction.

ReactionRemove

class qord.events.ReactionRemove

Structure for REACTION_REMOVE event.

This event is called whenever a reaction is removed from a message.

This requires Intents.guild_message_reactions or Intents.direct_message_reactions to be enabled for guilds and direct messages respectively.

message: Message

The message from which the reaction was removed.

reaction: Reaction

The removed reaction.

user: Union[User, GuildMember]

The user who removed their reaction.

Unlike the events.ReactionAdd event, This attribute can be a GuildMember object only when members intents are enabled as Discord does not tend to send the member data in this event.

ReactionClear

class qord.events.ReactionClear

Structure for REACTION_CLEAR event.

This event is called whenever all reactions are cleared from a message at once.

This requires Intents.guild_message_reactions or Intents.direct_message_reactions to be enabled for guilds and direct messages respectively.

message: Message

The message from which the reactions were cleared.

reactions: List[Reaction]

The list of cleared reactions.

ReactionClearEmoji

class qord.events.ReactionClearEmoji

Structure for REACTION_CLEAR_EMOJI event.

This event is called whenever all reactions for a specific emoji are cleared from a message at once.

This requires Intents.guild_message_reactions or Intents.direct_message_reactions to be enabled for guilds and direct messages respectively.

message: Message

The message from which the reactions were cleared.

emoji: PartialEmoji

The emoji whose reactions were cleared.

reaction: Reaction

The reaction that was cleared.

ScheduledEventCreate

class qord.events.ScheduledEventCreate

Structure for SCHEDULED_EVENT_CREATE event.

This event is called whenever a new scheduled event is created in a guild.

Requires the scheduled_events intents to be enabled. This intent is enabled by default.

guild: Guild

The guild in which event was created.

scheduled_event: ScheduledEvent

The created scheduled event.

ScheduledEventUpdate

class qord.events.ScheduledEventUpdate

Structure for SCHEDULED_EVENT_UPDATE event.

This event is called whenever a scheduled event is updated in a guild.

Requires the scheduled_events intents to be enabled. This intent is enabled by default.

guild: Guild

The guild in which event was created.

before: ScheduledEvent

The scheduled event before the update.

after: ScheduledEvent

The scheduled event after the update.

ScheduledEventDelete

class qord.events.ScheduledEventDelete

Structure for SCHEDULED_EVENT_DELETE event.

This event is called whenever a scheduled event is deleted in a guild.

Requires the scheduled_events intents to be enabled. This intent is enabled by default.

guild: Guild

The guild from which the event was deleted.

scheduled_event: ScheduledEvent

The deleted scheduled event.

ScheduledEventUserAdd

class qord.events.ScheduledEventUserAdd

Structure for SCHEDULED_EVENT_USER_ADD event.

This event is called whenever a user subscribes to a scheduled event.

Requires the scheduled_events intents to be enabled. This intent is enabled by default.

guild: Guild

The guild that the event belongs to.

scheduled_event: ScheduledEvent

The scheduled event on which user subscribed.

user_id: int

The ID of user who subscribed.

user: Optional[GuildMember]

The user who subscribed.

This can be ``None``! When members are not enabled or member isn’t cached by any chance, This attribute can be None. You should consider fetching the member via Guild.fetch_member() with the given user_id.

ScheduledEventUserRemove

class qord.events.ScheduledEventUserRemove

Structure for SCHEDULED_EVENT_USER_REMOVE event.

This event is called whenever a user unsubscribes to a scheduled event.

Requires the scheduled_events intents to be enabled. This intent is enabled by default.

guild: Guild

The guild that the event belongs to.

scheduled_event: ScheduledEvent

The scheduled event on which user unsubscribed.

user_id: int

The ID of user who unsubscribed.

user: Optional[GuildMember]

The user who unsubscribed.

This can be ``None``! When members are not enabled or member isn’t cached by any chance, This attribute can be None. You should consider fetching the member via Guild.fetch_member() with the given user_id.