Event reference

Event names mostly correspond with the event names that are returned from a dispatch by Discord.

For more information about handling events, see Better Event Handling.

State events

await connect(ctx: EventContext)

Called as soon as READY is received on the gateway. This can be used to change status immediately after authentication, for example.

await ready(ctx: EventContext)

Called when a shard has finished streaming guilds and chunked all large guilds successfully. This is different to Discord’s READY event, which fires as soon as the connection has opened.

await shards_ready(ctx: EventContext)

Called when all the shards for a client are ready.

await resumed(ctx: EventContext)

Called when a bot has resumed the connection.

await guild_available(ctx: EventContext, guild: Guild)

Called when a previously unavailable guild becomes available. This is not called when Unavailable Guilds during streaming become available. For that, use guild_streamed().

await guild_join(ctx: EventContext, guild: Guild)

Called when the bot joins a new guild. This is not called when guilds are streaming. For that, use guild_streamed().

await guild_streamed(ctx: EventContext, guild: Guild)

Called when a guild is streamed during login.

await guild_chunk(ctx: EventContext, guild: Guild, member_count: int)

Called when a guild receives a Guild Member Chunk.

await guild_sync(ctx: EventContext, guild: Guild, member_count: int, presence_count: int)

Called when a guild receives a Guild Sync.

Note

This is a user-account only event.

await guild_unavailable(ctx: EventContext, guild: Guild)

Called when a guild goes unavailable.

await guild_leave(ctx: EventContext, guild: Guild)

Called when the bot leaves a guild.

await guild_update(ctx: EventContext, old_guild: Guild, new_guild: Guild)

Called when a guild updates. This could be from the name changing, icon changing, etc.

await guild_emojis_update(ctx: EventContext, old_guild: Guild, new_guild: Guild)

Called when the emojis update in a guild.

await guild_member_update(ctx: EventContext, old_member: Member, new_member: Member)

Called when a guild member updates. This could be from roles or nick changing.

presence_update(ctx: EventContext, old_member: Member, new_member: Member)

Called when a guild member has a presence update.

await user_settings_update(ctx: EventContext, old_settings: UserSettings, new_settings: UserSettings)

Called when a user’s settings update.

Note

This is a user-account only event.

await friend_update(ctx: EventContext, friend: RelationshipUser)

Called when a friend updates (name, presence).

Note

This is a user-account only event.

await relationship_add(ctx: EventContext, user: RelationshipUser)

Called when a relationship is added.

await relationship_remove(ctx: EventContext, user: RelationshipUser)

Called when a relationship is removed.

await user_typing(ctx: EventContext, channel: Channel, user: User)

Called when a user is typing (in a private or group DM).

await member_typing(ctx: EventContext, channel: Channel, user: User)

Called when a member is typing (in a guild).

await message_create(ctx: EventContext, message: Message)

Called when a message is created.

await message_update_uncached(ctx: EventContext, messsage: Message)

Called when a message is updated. This will ignore the cache.

await message_edit(ctx: EventContext, old_message: Message, new_message: Message)

Called when a message’s content is edited.

Warning

This event will only be called if a message that the bot has previously seen is in the message cache. Otherwise, the bot will silently eat the event.

await message_update(ctx: EventContext, old_message: Message, new_message: Message)

Called when a message is updated (a new embed is added, content is edited, etc).

This will fire on newly added embeds; if you don’t want this use message_edit instead.

Warning

This event will only be called if a message that the bot has previously seen is in the message cache. Otherwise, the bot will silently eat the event.

await message_delete_uncached(ctx: EventContext, message_id: int)

Called when a message is deleted. This will ignore the cache.

await message_delete(ctx: EventContext, message: Message)

Called when a message is deleted.

Warning

This event will only be called if a message that the bot has previously seen is in the message cache. Otherwise, the bot will silently eat the event.

await message_delete_bulk_uncached(ctx: EventContext, messages: List[int])

Called when messages are bulk deleted. This will ignore the cache.

await message_delete_bulk(ctx: EventContext, messages: List[Message])

Called when messages are bulk deleted.

Warning

This event will only be called if any messages that the bot has previously seen is in the message cache. Otherwise, the bot will silently eat the event.

await message_reaction_add(ctx: EventContext, message: Message, author: Union[Member, User], reaction)

Called when a message is reacted to.

await message_reaction_remove(ctx: EventContext, message, author, reaction)

Called when a reaction is removed from a message.

await message_ack(ctx: EventContext, channel: Channel, message: Message)

Called when a message is ACK’d.

Note

This is a user-account only event.

guild_member_add(ctx: EventContext, member: Member

:async:)

Called when a member is added to a guild.

await guild_member_remove(ctx: EventContext, member: Member)

Called when a member is removed from a guild.

await user_ban(ctx: EventContext, user: User)

Called when a user is banned from a guild.

await guild_member_ban(ctx: EventContext, member: Member)

Called when a member is banned from a guild.

user_unban(ctx: EventContext, user: User):

Called when a user is unbanned.

Note

There is no guild_member_unban event as members cannot be unbanned.

await channel_create(ctx: EventContext, channel: Channel)

Called when a channel is created.

await channel_update(ctx: EventContext, old_channel: Channel, new_channel: Channel)

Called when a channel is updated.

await channel_delete(ctx: EventContext, channel: Channel)

Called when a channel is deleted.

await group_user_add(ctx: EventContext, channel: Channel, user: User)

Called when a user is added to a group.

await group_user_remove(ctx: EventContext, channel: Channel, user: User)

Called when a user is removed from a group.

await guild_role_create(ctx: EventContext, role: Role)

Called when a role is created.

await guild_role_update(ctx: EventContext, old_role: Role, new_role: Role)

Called when a role is updated.

await guild_role_delete(ctx: EventContext, role: Role)

Called when a role is deleted.

await voice_state_update(ctx: EventContext, member, old_voice_state, new_voice_state)

Called when a member’s voice state updates.

Gateway Events

These events are low-level events; they deal with raw data received from the websocket connection.

await gateway_message_received(ctx: EventContext, data)

Called when a message is received on the websocket.

Warning

The data is the RAW DATA passed from the websocket. It could be compressed data; it is undecoded.

This event is often not useful; see gateway_event_received() or gateway_dispatch_received() for better functions.

await gateway_event_received(ctx: EventContext, data: dict)

Called when an event is received on the websocket, after decompressing and decoding.

await gateway_hello(ctx: EventContext, trace: List[str])

Called when HELLO is received.

await gateway_heartbeat(ctx: EventContext, stats)

Called when a heartbeat is sent.

await gateway_heartbeat_ack(ctx: EventContext)

Called when Discord ACKs a heartbeat we’ve sent.

await gateway_heartbeat_received(ctx: EventContext)

Called when Discord asks us to send a heartbeat.

await gateway_invalidate_session(ctx: EventContext, resume: bool)

Called when Discord invalidates our session.

await gateway_reconnect_received(ctx: EventContext)

Called when Discord asks us to send a reconnect.

await gateway_dispatch_received(ctx: EventContext, dispatch: dict)

Called when an event is dispatched.