Event Reference This section outlines the different types of events listened by Client. Events are dispatched by Discord’s gateway and allow your bot to respond to various actions happening in Discord.
Registering Events There are 3 ways to register an event:
1. Using @client.event @client.event async def on_message ( message ): print ( f "Received: { message.content } " )
2. Subclassing Client class MyClient ( discord . Client ): async def on_message ( self , message ): print ( f "Received: { message.content } " )
3. Using @client.listen @client.listen () async def on_message ( message ): print ( f "Received: { message.content } " ) # Listen only once @client.listen ( once = True ) async def on_ready (): print ( "Client is ready!" )
All event handlers must be coroutines (async functions). If they aren’t, you might get unexpected errors.
Application Commands
on_application_command async def on_application_command ( context : ApplicationContext)
Called when an application command is received. context
ApplicationContext
required
The ApplicationContext associated to the command being received.
on_application_command_completion
on_application_command_completion async def on_application_command_completion ( context : ApplicationContext)
Called when an application command is completed, after any checks have finished. context
ApplicationContext
required
The ApplicationContext associated to the command that was completed.
on_application_command_error
on_application_command_error async def on_application_command_error ( context : ApplicationContext, exception : DiscordException )
Called when an application command has an error. context
ApplicationContext
required
The ApplicationContext associated to the command that has an error.
The DiscordException associated to the error.
on_unknown_application_command
on_unknown_application_command async def on_unknown_application_command ( interaction : Interaction)
Called when an application command was not found in the bot’s internal cache. The interaction associated to the unknown command.
Connection Events
on_ready Called when the client is done preparing the data received from Discord. Usually after login is successful and Client.guilds and co. are filled up. This function is not guaranteed to be the first event called. This function is also not guaranteed to only be called once. The library implements reconnection logic and will call this event whenever a RESUME request fails.
Example: @client.event async def on_ready (): print ( f 'Logged in as { client.user } (ID: { client.user.id } )' ) print ( '------' )
on_connect Called when the client has successfully connected to Discord. This is not the same as the client being fully prepared (see on_ready). Overriding this event will not call Bot.sync_commands(). As a result, application commands will not be registered.
on_disconnect async def on_disconnect ()
Called when the client has disconnected from Discord, or a connection attempt has failed. This function can be called many times without a corresponding on_connect call.
on_resumed Called when the client has resumed a session.
on_error async def on_error ( event : str , * args , ** kwargs )
Usually when an event raises an uncaught exception, a traceback is printed to stderr and the exception is ignored. Override this to change this behaviour. The name of the event that raised the exception.
The positional arguments for the event that raised the exception.
The keyword arguments for the event that raised the exception.
Shard Events
on_shard_connect / on_shard_disconnect / on_shard_ready / on_shard_resumed
Shard Events async def on_shard_connect ( shard_id : int ) async def on_shard_disconnect ( shard_id : int ) async def on_shard_ready ( shard_id : int ) async def on_shard_resumed ( shard_id : int )
Similar to their non-shard counterparts, but used by AutoShardedClient to denote when a particular shard has connected/disconnected/ready/resumed. Guild Events
on_guild_join async def on_guild_join ( guild : Guild)
Called when a Guild is either created by the Client or when the Client joins a guild. Requires Intents.guilds to be enabled. The guild that was joined.
on_guild_remove async def on_guild_remove ( guild : Guild)
Called when a Guild is removed from the Client (banned, kicked, left, or deleted). Requires Intents.guilds to be enabled. The guild that got removed.
on_guild_update async def on_guild_update ( before : Guild, after : Guild)
Called when a Guild is updated (name, AFK channel, AFK timeout, etc.). Requires Intents.guilds to be enabled. The guild prior to being updated.
The guild after being updated.
on_guild_available / on_guild_unavailable
on_guild_available / on_guild_unavailable async def on_guild_available ( guild : Guild) async def on_guild_unavailable ( guild : Guild)
Called when a guild becomes available or unavailable. The guild must have existed in the Client.guilds cache. Requires Intents.guilds to be enabled. The guild that has changed availability.
on_guild_role_create / on_guild_role_delete
on_guild_role_create / on_guild_role_delete async def on_guild_role_create ( role : Role) async def on_guild_role_delete ( role : Role)
Called when a Guild creates or deletes a Role. Requires Intents.guilds to be enabled. The role that was created or deleted.
on_guild_role_update async def on_guild_role_update ( before : Role, after : Role)
Called when a Role is changed guild-wide. Requires Intents.guilds to be enabled. The updated role’s old info.
The updated role’s updated info.
on_guild_emojis_update async def on_guild_emojis_update ( guild : Guild, before : Sequence[GuildEmoji], after : Sequence[GuildEmoji] )
Called when a Guild adds or removes an emoji. Requires Intents.emojis_and_stickers to be enabled. The guild who got their emojis updated.
before
Sequence[GuildEmoji]
required
A list of emojis before the update.
after
Sequence[GuildEmoji]
required
A list of emojis after the update.
on_guild_stickers_update async def on_guild_stickers_update ( guild : Guild, before : Sequence[GuildSticker], after : Sequence[GuildSticker] )
Called when a Guild adds or removes a sticker. Requires Intents.emojis_and_stickers to be enabled. The guild who got their stickers updated.
before
Sequence[GuildSticker]
required
A list of stickers before the update.
after
Sequence[GuildSticker]
required
A list of stickers after the update.
Channel Events
on_guild_channel_create / on_guild_channel_delete
on_guild_channel_create / on_guild_channel_delete async def on_guild_channel_create ( channel : GuildChannel) async def on_guild_channel_delete ( channel : GuildChannel)
Called whenever a guild channel is created or deleted. Requires Intents.guilds to be enabled. The guild channel that got created or deleted.
on_guild_channel_update async def on_guild_channel_update ( before : GuildChannel, after : GuildChannel)
Called whenever a guild channel is updated (name, topic, permissions, etc.). Requires Intents.guilds to be enabled. The updated guild channel’s old info.
The updated guild channel’s new info.
on_guild_channel_pins_update
on_guild_channel_pins_update async def on_guild_channel_pins_update ( channel : GuildChannel | Thread, last_pin : datetime | None )
Called whenever a message is pinned or unpinned from a guild channel. Requires Intents.guilds to be enabled. channel
GuildChannel | Thread
required
The guild channel that had its pins updated.
The latest message that was pinned as an aware datetime in UTC. Could be None.
on_private_channel_update
on_private_channel_update async def on_private_channel_update ( before : GroupChannel, after : GroupChannel)
Called whenever a private group DM is updated (name, topic, etc.). Requires Intents.messages to be enabled. The updated group channel’s old info.
The updated group channel’s new info.
Member Events
on_member_join async def on_member_join ( member : Member)
Called when a Member joins a Guild. Requires Intents.members to be enabled.
on_member_remove async def on_member_remove ( member : Member)
Called when a Member leaves a Guild. Requires Intents.members to be enabled.
on_member_update async def on_member_update ( before : Member, after : Member)
Called when a Member updates their profile (nickname, roles, pending, communication_disabled_until, timed_out). Requires Intents.members to be enabled. The updated member’s old info.
The updated member’s updated info.
on_user_update async def on_user_update ( before : User, after : User)
Called when a User updates their profile (avatar, username, discriminator, global_name, primary_guild). Requires Intents.members to be enabled. The updated user’s old info.
The updated user’s updated info.
on_presence_update async def on_presence_update ( before : Member, after : Member)
Called when a Member updates their presence (status, activity). Requires Intents.presences and Intents.members to be enabled. The updated member’s old info.
The updated member’s updated info.
on_voice_state_update async def on_voice_state_update ( member : Member, before : VoiceState, after : VoiceState )
Called when a Member changes their VoiceState (joins/leaves voice, muted/deafened, etc.). Requires Intents.voice_states to be enabled. The member whose voice states changed.
The voice state prior to the changes.
The voice state after the changes.
Message Events
on_message async def on_message ( message : Message)
Called when a Message is created and sent. Requires Intents.messages to be enabled. Your bot’s own messages and private messages are sent through this event. This can lead to cases of ‘recursion’. Consider checking the user IDs.
Example: @client.event async def on_message ( message ): # Don't respond to ourselves if message.author == client.user: return if message.content == 'ping' : await message.channel.send( 'pong' )
on_message_edit async def on_message_edit ( before : Message, after : Message)
Called when a Message receives an update event. Triggers when a message is pinned/unpinned, content changed, embeds received/suppressed, or a poll ends. Requires Intents.messages to be enabled. The previous version of the message.
The current version of the message.
on_message_delete async def on_message_delete ( message : Message)
Called when a message is deleted. Only called if the message is in the internal message cache. Requires Intents.messages to be enabled.
on_bulk_message_delete async def on_bulk_message_delete ( messages : list[Message])
Called when messages are bulk deleted. Only includes messages found in the internal message cache. Requires Intents.messages to be enabled. The messages that have been deleted.
on_raw_message_edit async def on_raw_message_edit ( payload : RawMessageUpdateEvent)
Called when a message is edited. Unlike on_message_edit, this is called regardless of the internal message cache. Requires Intents.messages to be enabled. payload
RawMessageUpdateEvent
required
The raw event payload data.
on_raw_message_delete async def on_raw_message_delete ( payload : RawMessageDeleteEvent)
Called when a message is deleted. Unlike on_message_delete, this is called regardless of the internal message cache. Requires Intents.messages to be enabled. payload
RawMessageDeleteEvent
required
The raw event payload data.
on_raw_bulk_message_delete
on_raw_bulk_message_delete async def on_raw_bulk_message_delete ( payload : RawBulkMessageDeleteEvent)
Called when a bulk delete is triggered. Unlike on_bulk_message_delete, this is called regardless of the internal message cache. Requires Intents.messages to be enabled. payload
RawBulkMessageDeleteEvent
required
The raw event payload data.
Reaction Events
on_reaction_add async def on_reaction_add ( reaction : Reaction, user : User | Member)
Called when a message has a reaction added to it. Only called if the message is in the internal message cache. Requires Intents.reactions to be enabled. The current state of the reaction.
The user who added the reaction.
on_reaction_remove async def on_reaction_remove ( reaction : Reaction, user : User | Member)
Called when a message has a reaction removed from it. Only called if the message is in the internal message cache. Requires Intents.reactions and Intents.members to be enabled. The current state of the reaction.
The user who added the reaction.
on_reaction_clear async def on_reaction_clear ( message : Message, reactions : list[Reaction])
Called when a message has all its reactions removed from it. Requires Intents.reactions to be enabled. The message that had its reactions cleared.
The reactions that were removed.
on_reaction_clear_emoji async def on_reaction_clear_emoji ( reaction : Reaction)
Called when a message has a specific reaction removed from it. Requires Intents.reactions to be enabled. The reaction that got cleared.
on_raw_reaction_add / on_raw_reaction_remove
on_raw_reaction_add / on_raw_reaction_remove async def on_raw_reaction_add ( payload : RawReactionActionEvent) async def on_raw_reaction_remove ( payload : RawReactionActionEvent)
Called when a message has a reaction added or removed. Unlike the non-raw versions, these are called regardless of the internal message cache. Requires Intents.reactions to be enabled. payload
RawReactionActionEvent
required
The raw event payload data.
Thread Events
on_thread_create async def on_thread_create ( thread : Thread)
Called whenever a thread is created. Requires Intents.guilds to be enabled. The thread that got created.
on_thread_join async def on_thread_join ( thread : Thread)
Called whenever a thread is joined. Requires Intents.guilds to be enabled. The thread that got joined.
on_thread_update async def on_thread_update ( before : Thread, after : Thread)
Called whenever a thread is updated. Requires Intents.guilds to be enabled. The updated thread’s old info.
The updated thread’s new info.
on_thread_remove async def on_thread_remove ( thread : Thread)
Called whenever a thread is removed. This is different from a thread being deleted. Requires Intents.guilds to be enabled. The thread that got removed.
on_thread_delete async def on_thread_delete ( thread : Thread)
Called whenever a thread is deleted. Only called if the thread is in the cache. Requires Intents.guilds to be enabled. The thread that got deleted.
on_thread_member_join / on_thread_member_remove
on_thread_member_join / on_thread_member_remove async def on_thread_member_join ( member : ThreadMember) async def on_thread_member_remove ( member : ThreadMember)
Called when a ThreadMember leaves or joins a Thread. Requires Intents.members to be enabled. The member who joined or left.
Typing Events
on_typing async def on_typing ( channel : Messageable, user : User | Member, when : datetime )
Called when someone begins typing a message. Requires Intents.typing to be enabled. The location where the typing originated from.
The user that started typing.
When the typing started as an aware datetime in UTC.
on_raw_typing async def on_raw_typing ( payload : RawTypingEvent)
Called when someone begins typing a message. Unlike on_typing, this is called regardless of the user cache. Requires Intents.typing to be enabled. Ban Events
on_member_ban async def on_member_ban ( guild : Guild, user : User | Member)
Called when a user gets banned from a guild. Requires Intents.moderation to be enabled. The guild the user got banned from.
The user that got banned. Can be either User or Member depending if the user was in the guild at the time.
on_member_unban async def on_member_unban ( guild : Guild, user : User)
Called when a user gets unbanned from a guild. Requires Intents.moderation to be enabled. The guild the user got unbanned from.
The user that got unbanned.
Invite Events
on_invite_create / on_invite_delete
on_invite_create / on_invite_delete async def on_invite_create ( invite : Invite) async def on_invite_delete ( invite : Invite)
Called when an invite is created or deleted. Requires manage_channels permission. Requires Intents.invites to be enabled. The invite that was created or deleted.
Integration Events
on_integration_create / on_integration_update
on_integration_create / on_integration_update async def on_integration_create ( integration : Integration) async def on_integration_update ( integration : Integration)
Called when an integration is created or updated. Requires Intents.integrations to be enabled. The integration that was created or updated.
on_webhooks_update async def on_webhooks_update ( channel : GuildChannel)
Called whenever a webhook is created, modified, or removed from a guild channel. Requires Intents.webhooks to be enabled. The channel that had its webhooks updated.
AutoMod Events
on_auto_moderation_rule_create / on_auto_moderation_rule_update / on_auto_moderation_rule_delete
AutoMod Rule Events async def on_auto_moderation_rule_create ( rule : AutoModRule) async def on_auto_moderation_rule_update ( rule : AutoModRule) async def on_auto_moderation_rule_delete ( rule : AutoModRule)
Called when an auto moderation rule is created, updated, or deleted. Requires manage_guild permission. Requires Intents.auto_moderation_configuration to be enabled. The auto moderation rule.
on_auto_moderation_action_execution
on_auto_moderation_action_execution async def on_auto_moderation_action_execution ( payload : AutoModActionExecutionEvent)
Called when an auto moderation action is executed. Requires manage_guild permission. Requires Intents.auto_moderation_execution to be enabled. payload
AutoModActionExecutionEvent
required
The event’s data.
Other Events For a complete list of all events including:
Scheduled Events
Stage Instances
Polls
Voice Channel Status
Soundboard Sounds
Monetization/Entitlements
Audit Logs
Refer to the Discord API Events Documentation . 