Event references¶

This serves as a reference for all events that can be used in the bot. The events are divided into categories, and each event has a description of what it does and what parameters it takes.

An example of how one event is used:

import discord_http

client = discord_http.Client(...)

@client.listener()
async def on_ready(user: discord_http.User):
    print(f"Logged in as {user}")

If you are trying to get listeners inside a cog, you will need to do the following:

from discord_http import commands, User

@commands.listener()
async def on_ready(self, user: User):
    print(f"Logged in as {user}")

Connection¶

async def on_ready(client)

Called when the bot token has been verified and everything is loaded, ready to start receiving events from Discord. Using this event will disable the default INFO print given by the library, and instead let you decide what it should do.

Parameters:: user – User object with information about the token provided.

async def on_ping(ping)

Called whenever Discord sends a ping to the bot, checking if the URL provided for interactions is valid. Using this event will disable the default INFO print given by the library, and instead let you decide what it should do.

Parameters:: ping – Ping object that tells what information was sent to the bot.

Webhook¶

async def on_raw_interaction(data)

Called whenever an interaction is received from Discord. In order to use this event, you must have Client.debug_events set to True, otherwise it will not be called.

Parameters:: data – dict raw dictionary with the interaction data sent by Discord.

async def on_interaction_dropped(ctx)

Called whenever an interaction is dropped because it arrived too late to be acknowledged in time. Discord requires interactions to be acknowledged within 3 seconds of creation. If it took longer than that just to reach the bot, the interaction is already invalid and is dropped without being processed.

Using this event will disable the default WARN print given by the library, and instead let you decide what it should do.

Parameters:: ctx – Context The context object for the interaction that was dropped.

Webhook Events¶

Note

Webhook Events are a separate feature from Interactions and Gateway events. Discord sends them as plain HTTP requests to a Webhook Events URL, which is configured independently from your Interactions Endpoint URL.

To receive them, set webhook_events_path when creating your client (it is None/disabled by default):

from discord_http import Client

client = Client(
    ...,
    webhook_events_path="/webhook-events"
)

Then, in the Discord Developer Portal, set your application’s Webhook Events URL to https://yourdomain.com/webhook-events (matching the path you chose above). Discord will send a PING to that URL to verify it right after you save it.

Unlike the events in the Gateway events category, these do not require enable_gateway=True and work purely over HTTP, the same way Interactions do.

async def on_application_authorized(user, guild, scopes, integration_type)

Called whenever a user authorizes (installs) the application.

Parameters:

scopes – list[str] the OAuth2 scopes that were authorized.
user – User object with information about the user that authorized the application.
guild – Guild | None object with information about the guild the application was installed to, only if it was installed to a guild.
integration_type – IntegrationType | None whether the app was installed to a guild or to a user account.

async def on_application_deauthorized(user)

Called whenever a user removes (deauthorizes) the application.

Parameters:: user – User object with information about the user that deauthorized the application.

async def on_raw_webhook_event(data)

Called whenever any webhook event payload is received from Discord, including ones the library does not turn into a named event (e.g. Social SDK-only events, which are not usable by bots). In order to use this event, you must have Client.debug_events set to True, otherwise it will not be called.

Parameters:: data – dict raw dictionary with the webhook event payload sent by Discord.

Note

on_entitlement_create, on_entitlement_update and on_entitlement_delete (documented under Global events) are also dispatched here whenever Discord delivers them as Webhook Events instead of Gateway events, so a single listener works regardless of which transport is configured.

Errors¶

async def on_event_error(client, error)

Called whenever an error occurs in an event (listener)

Using this event will disable the default ERROR print given by the library, and instead let you decide what it should do.

Parameters:

client – Client The client object.
error – Exception object with the error that occurred.

async def on_interaction_error(ctx, error):

Called whenever an error occurs in an interaction (command, autocomplete, button, etc.)

Using this event will disable the default ERROR print given by the library, and instead let you decide what it should do.

Parameters:

ctx – Context The context object.
error – Exception object with the error that occurred.

Gateway events¶

Note

These events are only provided if discord.http/gateway is enabled.

from discord_http import Client
from discord_http.gateway import Intents

client = Client(
    ...,
    enable_gateway=True,
    # intents=Intents
)

Global events¶

async def on_entitlement_create(entitlement):

Called whenever an entitlement is created

Parameters:: entitlement – Entitlements object with information about the entitlement.

async def on_entitlement_update(entitlement):

Called whenever an entitlement is updated

Parameters:: entitlement – Entitlements object with information about the entitlement.

async def on_entitlement_delete(entitlement):

Called whenever an entitlement is deleted

Parameters:: entitlement – Entitlements object with information about the entitlement.

async def on_subscription_create(subscription):

Called whenever a subscription is created

Parameters:: subscription – Subscription object with information about the subscription.

async def on_subscription_update(subscription):

Called whenever a subscription is updated

Parameters:: subscription – Subscription object with information about the subscription.

async def on_subscription_delete(subscription):

Called whenever a subscription is deleted

Parameters:: subscription – Subscription object with information about the subscription.

async def on_user_update(user):

Called whenever the bot’s own user is updated

Parameters:: user – User object with the updated information about the bot’s user.

async def on_application_command_permissions_update(permissions):

Called whenever the permissions of an application command are updated in a guild

Parameters:: permissions – GuildApplicationCommandPermissions object with information about the updated permissions.

async def on_rate_limited(payload):

Called whenever the shard gets rate limited on a gateway opcode (currently only opcode 8, Request Guild Members).

Note

If this was caused by a pending chunk_guild/fetch_members call, that call’s waiter is failed immediately with a RuntimeError instead of only timing out after 30 seconds.

Parameters:: payload – GatewayRateLimited object with information about the rate limit.

Shard events¶

Note

These events are only provided if discord.http/gateway is enabled. By default if the gateway is enabled, they will do [ INFO ] logs. You can in theory listen to the events and simply do nothing to disable the logs.

async def on_gateway_ready(client):

Called once every shard has become ready, meaning the whole gateway connection is now fully ready.

Parameters:: client – Client The client object.

async def on_shard_ready(shard):

Called whenever a shard is now ready

Parameters:: shard – ShardEventPayload object with information about the shard that is ready.

async def on_shard_resumed(shard):

Called whenever a shard is resumed

Parameters:: shard – ShardEventPayload object with information about the shard that was resumed.

async def on_shard_closed(shard_close_payload):

Called whenever a shard is closed

Parameters:: payload – ShardEventPayload object with information about the shard that crashed and more information.

Intents.guilds¶

async def on_guild_create(guild):

Called whenever a guild is created (Bot was added)

Note

This event is not called unless the shard is ready, to prevent spam.

Parameters:: guild – Guild object with information about the guild.

async def on_guild_update(guild):

Called whenever a guild is updated.

Parameters:: guild – Guild object with information about the guild.

async def on_guild_delete(guild):

Called whenever a guild is deleted (Bot was removed)

Note

Depending on your cache rules, Guild will either return Full or Partial object.

Parameters:: guild – PartialGuild object with information about the guild.

async def on_guild_available(guild):

Called whenever a guild was initially created, but came back from unavailable state

Note

Depending on your cache rules, Guild will either return Full or Partial object.

Parameters:: guild – Guild object with information about that guild

async def on_guild_unavailable(guild):

Called whenever a guild is deleted, but came back from available state

Note

Depending on your cache rules, Guild will either return Full or Partial object.

Parameters:: guild – Guild object with information about that guild

async def on_guild_role_create(role):

Called whenever a role was created

Note

Depending on your cache rules, Role.guild will either return Full or Partial object.

Parameters:: role – Role object with information about the role.

async def on_guild_role_update(role):

Called whenever a role was updated

Note

Depending on your cache rules, Role.guild will either return Full or Partial object.

Parameters:: role – Role object with information about the role.

async def on_guild_role_delete(role):

Called whenever a role was deleted

Parameters:: role – PartialRole object with information about the role.

async def on_channel_create(channel):

Called whenever a channel is created

Note

Depending on what channel was made, it will either return TextChannel, VoiceChannel, etc.

Parameters:: channel – BaseChannel object with information about the channel.

async def on_channel_update(channel):

Called whenever a channel is updated

Parameters:: channel – BaseChannel object with information about the channel.

async def on_channel_delete(channel):

Called whenever a channel is deleted

Parameters:: channel – BaseChannel object with information about the channel.

async def on_channel_pins_update(payload):

Called whenever a channel’s pins are updated

Parameters:: payload – ChannelPinsUpdate object with information about the pins.

async def on_voice_channel_status_update(guild, channel, status):

Called whenever a voice channel’s status is updated

Note

Depending on your cache rules, channel will either return Full or Partial object.

Parameters:

guild – Guild | PartialGuild object with information about the guild.
channel – BaseChannel | PartialChannel object with information about the voice channel.
status – str | None the new status of the voice channel, or None if it was cleared.

async def on_voice_channel_start_time_update(guild, channel, start_time):

Called whenever a voice channel’s session start time is updated

Note

Depending on your cache rules, channel will either return Full or Partial object.

Parameters:

guild – Guild | PartialGuild object with information about the guild.
channel – BaseChannel | PartialChannel object with information about the voice channel.
start_time – datetime.datetime | None the new voice session start time, or None if there is no active session.

async def on_thread_create(thread):

Called whenever a thread is created

Note

Depending on what type of thread was made, it will either return PublicThread, PrivateThread, etc.

Parameters:: thread – BaseChannel object with information about the thread.

async def on_thread_update(thread):

Called whenever a thread is updated

Note

Depending on what type of thread was updated, it will either return PublicThread, PrivateThread, etc.

Parameters:: thread – BaseChannel object with information about the thread.

async def on_thread_delete(thread):

Called whenever a thread is deleted

Parameters:: thread – PartialChannel object with information about the thread.

async def on_thread_list_sync(payload):

Called whenever a thread list is synced

Parameters:: payload – ThreadListSyncPayload object with information about the thread list.

async def on_thread_member_update(payload):

Called whenever a thread member is updated

Parameters:: payload – ThreadMembersUpdatePayload object with information about the thread member.

async def on_thread_members_update(payload):

Called whenever a thread members are updated

Parameters:: payload – ThreadMembersUpdatePayload object with information about the thread members.

async def on_stage_instance_create(stage_instance):

Called whenever a stage instance is created

Note

Depending on your cache rules, StageInstance.guild will either return Full or Partial object.

Parameters:: stage_instance – StageInstance object with information about the stage instance.

async def on_stage_instance_update(stage_instance):

Called whenever a stage instance is updated

Note

Depending on your cache rules, StageInstance.guild will either return Full or Partial object.

Parameters:: stage_instance – StageInstance object with information about the stage instance.

async def on_stage_instance_delete(stage_instance):

Called whenever a stage instance is deleted

Note

Depending on your cache rules, StageInstance.guild will either return Full or Partial object.

Parameters:: stage_instance – PartialStageInstance object with information about the stage instance.

Intents.guild_members¶

async def on_guild_member_add(guild, member):

Called whenever a member joins a guild

Note

Depending on your cache rules, Member.guild and guild will either return Full or Partial object.

Parameters:

guild – Guild | PartialGuild object with information about the guild.
member – Member object with information about the member.

async def on_guild_member_update(guild, member):

Called whenever a member is updated

Note

Depending on your cache rules, Member.guild and guild will either return Full or Partial object.

Parameters:

guild – Guild | PartialGuild object with information about the guild.
member – Member object with information about the member.

async def on_guild_member_remove(guild, member):

Called whenever a member leaves a guild

Note

Depending on your cache rules, guild will either return Full or Partial object.

Parameters:

guild – Guild | PartialGuild object with information about the guild.
member – User object with information about the member.

async def on_thread_members_update(payload):

Called whenever a thread members are updated

Note

Depending on your cache rules, ThreadMember.guild will either return Full or Partial object.

Parameters:: payload – ThreadMembersUpdatePayload object with information about the thread members.

Intents.guild_moderation¶

async def on_guild_audit_log_entry_create(entry):

Called whenever an audit log entry is created

Note

Depending on your cache rules, AuditLogEntry.guild will either return Full or Partial object.

Parameters:: entry – AuditLogEntry object with information about the audit log entry.

async def on_guild_ban_add(guild, user):

Called whenever a user is banned from a guild

Note

Depending on your cache rules, guild will either return Full or Partial object.

Parameters:

guild – Guild | PartialGuild object with information about the guild.
user – User object with information about the user.

async def on_guild_ban_remove(guild, user):

Called whenever a user is unbanned from a guild

Note

Depending on your cache rules, guild will either return Full or Partial object.

Parameters:

guild – Guild | PartialGuild object with information about the guild.
user – User object with information about the user.

Intents.guild_expressions¶

async def on_guild_emojis_update(guild, before, after):

Called whenever guild emojis have been updated

Warning

The before will remain the same as after unless you have Guild and Emoji cache flags enabled (not partial).

Parameters:

guild – Guild | PartialGuild object with information about the guild.
before – list[Emoji] emojis before the update.
after – list[Emoji] emojis after the update.

async def on_guild_stickers_update(guild, before, after):

Called whenever guild stickers have been updated

Warning

The before will remain the same as after unless you have Guild and Sticker cache flags enabled (not partial).

Parameters:

guild – Guild | PartialGuild object with information about the guild.
before – list[Sticker] stickers before the update.
after – list[Sticker] stickers after the update.

async def on_guild_soundboard_sound_create(sound):

Called whenever a soundboard sound is created

Note

Depending on your cache rules, SoundboardSound.guild will either return Full or Partial object.

Parameters:: sound – SoundboardSound object with information about the soundboard sound.

async def on_guild_soundboard_sound_update(sound):

Called whenever a soundboard sound is updated

Note

Depending on your cache rules, SoundboardSound.guild will either return Full or Partial object.

Parameters:: sound – SoundboardSound object with information about the soundboard sound.

async def on_guild_soundboard_sound_delete(sound):

Called whenever a soundboard sound is deleted

Note

Depending on your cache rules, SoundboardSound.guild will either return Full or Partial object.

Parameters:: sound – SoundboardSound object with information about the soundboard sound.

async def on_guild_soundboard_sounds_update(sounds):

Called whenever a soundboard sounds are updated

Note

Depending on your cache rules, sounds[].guild will either return Full or Partial object.

Parameters:: sounds – list[SoundboardSound] object with information about the soundboard sounds.

Intents.guild_integrations¶

async def on_guild_integrations_update(guild):

Called whenever a guild integration is updated

Note

Depending on your cache rules, guild will either return Full or Partial object.

Parameters:: guild – Guild | PartialGuild object with information about the guild.

async def on_integration_create(integration):

Called whenever an integration is created

Note

Depending on your cache rules, Integration.guild will either return Full or Partial object.

Parameters:: integration – Integration object with information about the integration.

async def on_integration_update(integration):

Called whenever an integration is updated

Note

Depending on your cache rules, Integration.guild will either return Full or Partial object.

Parameters:: integration – Integration object with information about the integration.

async def on_integration_delete(integration):

Called whenever an integration is deleted

Parameters:: integration – PartialIntegration object with information about the integration.

Intents.guild_webhooks¶

async def on_webhooks_update(channel):

Called whenever a webhook is updated

Note

Depending on your cache rules, channel will either return TextChannel/VoiceChannel/etc. or Partial object.

Parameters:: channel – PartialChannel | BaseChannel* object with information about the channel.

Intents.guild_invites¶

async def on_invite_create(invite):

Called whenever an invite is created

Parameters:: invite – Invite object with information about the invite.

async def on_invite_delete(invite):

Called whenever an invite is deleted

Parameters:: invite – PartialInvite object with information about the invite.

Intents.guild_voice_states¶

async def on_voice_state_update(before_voice, after_voice):

Called whenever a voice state is updated

Note

Depending on your cache rules, before_voice will either return Full, Partial object or None.

Parameters:

before_voice – VoiceState object with information about the new voice state.
after_voice – VoiceState object with information about the new voice state.

Intents.guild_presences¶

async def on_presence_update(presence):

Called whenever a presence is updated

Note

Depending on your cache rules, Presence.guild and Presence.user will either return Full or Partial object.

Parameters:: presence – Presence object with information about the presence.

Intents.guild_messages¶

Note

Message.content will only return something if you have enabled Intents.message_content.

async def on_message_create(message):

Called whenever a message is created

Parameters:: message – Message object with information about the message.

async def on_message_update(message):

Called whenever a message is updated

Parameters:: message – Message object with information about the message.

async def on_message_delete(message):

Called whenever a message is deleted

Parameters:: message – PartialMessage object with information about the message.

async def on_message_delete_bulk(payload):

Called whenever a message is deleted in bulk

Note

Depending on your cache rules, payload.guild will either return Full or Partial object.

Parameters:: payload – BulkDeletePayload object with information about the message.

Intents.direct_messages¶

Same as Intents.guild_messages

Intents.guild_message_reactions¶

async def on_message_reaction_add(reaction):

Called whenever a message reaction is added

Parameters:: reaction – Reaction object with information about the reaction.

async def on_message_reaction_remove(reaction):

Called whenever a message reaction is removed

Parameters:: reaction – Reaction object with information about the reaction.

async def on_message_reaction_remove_all(message):

Called whenever all message reactions are removed

Parameters:: reaction – PartialMessage object with information about the message.

async def on_message_reaction_remove_emoji(message, emoji):

Called whenever a message reaction is removed by an emoji

Parameters:

reaction – PartialMessage object with information about the message.
emoji – EmojiParser object with information about the emoji.

Intents.direct_message_reactions¶

Same as Intents.guild_message_reactions

Intents.guild_message_typing¶

async def on_typing_start(typing):

Called whenever a user starts typing

Note

Depending on your cache rules, typing.guild, typing.channel and typing.user will either return Full or Partial object.

Parameters:: typing – TypingStartEvent object with information about the typing.

Intents.direct_message_typing¶

Same as Intents.guild_message_typing

Intents.guild_scheduled_events¶

async def on_guild_scheduled_event_create(event):

Called whenever a guild scheduled event is created

Parameters:: event – ScheduledEvent object with information about the scheduled event.

async def on_guild_scheduled_event_update(event):

Called whenever a guild scheduled event is updated

Parameters:: event – ScheduledEvent object with information about the scheduled event.

async def on_guild_scheduled_event_delete(event):

Called whenever a guild scheduled event is deleted

Parameters:: event – PartialScheduledEvent object with information about the scheduled event.

async def on_guild_scheduled_event_user_add(event, member):

Called whenever a user is added to a guild scheduled event

Note

Depending on your cache rules, member will either return Full or Partial object.

Parameters:

event – ScheduledEvent object with information about the scheduled event.
member – PartialMember | Member object with information about the member.

async def on_guild_scheduled_event_user_remove(event, member):

Called whenever a user is removed from a guild scheduled event

Note

Depending on your cache rules, member will either return Full or Partial object.

Parameters:

event – ScheduledEvent object with information about the scheduled event.
member – PartialMember | Member object with information about the member.

Intents.auto_moderation_configuration¶

async def on_auto_moderation_rule_create(rule):

Called whenever an automod rule is created

Parameters:: rule – AutoModRule object with information about the automod rule.

async def on_auto_moderation_rule_update(rule):

Called whenever an automod rule is updated

Parameters:: rule – AutoModRule object with information about the automod rule.

async def on_auto_moderation_rule_delete(rule):

Called whenever an automod rule is deleted

Parameters:: rule – PartialAutoModRule object with information about the automod rule.

Intents.auto_moderation_execution¶

async def on_auto_moderation_action_execution(execution):

Called whenever an automod action is executed

Parameters:: execution – AutomodExecution object with information about the automod rule.

Intents.guild_message_polls¶

async def on_message_poll_vote_add(vote):

Called whenever a message poll vote is added

Note

Depending on your cache rules, vote.guild, vote.channel and vote.user will either return Full or Partial object.

Parameters:: vote – PollVoteEvent object with information about the poll vote.

async def on_message_poll_vote_remove(vote):

Called whenever a message poll vote is removed

Note

Depending on your cache rules, vote.guild, vote.channel and vote.user will either return Full or Partial object.

Parameters:: vote – PollVoteEvent object with information about the poll vote.

Intents.direct_message_polls¶

Same as Intents.guild_message_polls